하네스 엔지니어링 9단계 베스트 프랙티스 #4. 검증 (Hook)

시리즈 맥락 복기

Step 3까지 우리는 "에이전트에게 무엇을 시킬 것인가"를 정의했습니다. 하지만 시킨 일을 잘못 실행하는 것을 막을 장치가 없으면, Skill이 늘어날수록 사고 위험도 함께 커집니다. Step 4의 Hook은 바로 이 방어선입니다.

1. #0 업무 프로세스 매핑
2. #1 프로젝트 규칙 설정
3. #2 Code Wiki 작성
4. #3 Skill 정의
5. #4 검증 (Hook) ← 이번 편
6. #5 자동 트리거 + 완료 조건
7. ... (#8까지)

이 단계의 의미 — Hook은 하네스의 안전벨트다

Hook은 에이전트가 도구를 실행하기 직전과 직후에 끼어드는 코드입니다. 말에 비유하면 안전벨트 혹은 브레이크에 가깝습니다. 사람이 "출발!"을 외쳐도, Hook이 "길이 막혔다"고 판단하면 실행을 차단합니다. 반대로 실행 후에는 상태를 업데이트해 "여기까지 왔다"는 흔적을 남깁니다.

해결하려는 문제

• 자연어 → Shell 변환의 위험: "정리해줘"라는 말이 rm -rf로 해석되는 사고를 실행 전에 차단합니다.
• 파이프라인 중도 중단: "1~6단계 중 3단계에서 끊긴 작업"을 감지해 세션 종료를 차단합니다.
• 로깅 누락: 무엇이 실행됐는지 감사 로그를 자동으로 남깁니다 (#7에서 자세히).

효과 — 어떻게 체감되는가

개인 환경에서 Hook을 도입하기 전과 후의 가장 큰 차이는 "사고가 일어났을 때의 복구 비용"입니다. git reset --hard 같은 실수 한 번으로 작업을 날려본 경험이 있다면, 훅 한 줄이 얼마나 큰 보험인지 바로 체감할 수 있습니다.

베스트 프랙티스 — Dispatcher 패턴으로 Hook을 모듈화

하나의 훅에 모든 로직을 욱여넣지 말고, 디스패처 → 파이프라인 모듈 구조로 분리합니다.

왜 PreToolUse 훅이 모든 Bash를 거쳐야 하는가

AI는 자연어를 Shell 명령으로 변환하는데, 이 과정에서 의도와 다른 위험 명령이 나올 수 있습니다. "정리해줘"가 rm -rf ~/가 되거나, 리팩토링 중 git reset --hard가 튀어나올 수 있습니다. 이를 실행 전에 잡아야 하므로, 모든 Bash 명령이 PreToolUse 훅을 통과하는 구조로 만듭니다.

# 1. 안전 검증
block, msg = safety.check_safety(cmd, data)
if block:
    audit.log_event(...)            # 차단 이력 기록
    print(msg, file=sys.stderr)     # AI에게 사유 전달
    sys.exit(2)                     # 실행 차단

# 2. git commit 전 파이프라인별 검증
for validator in [calendar_sync.pre_commit, vault_manager.pre_commit, ...]:
    block, msg = validator(cmd, data)
    if block:
        print(msg, file=sys.stderr)
        sys.exit(2)

파이프라인별 pre_commit 검증을 여러 개 두는 이유는, 각 Skill마다 commit 전 확인해야 할 조건이 다르기 때문입니다.

파이프라인	pre_commit이 확인하는 것
일정 동기화	싱크 6단계 중 도중이면 "아직 미완료" 차단
대시보드 개발	코드 변경 후 테스트 안 돌렸으면 "테스트 먼저" 차단
지식금고 관리	테스트 미통과 시 commit 차단

상태 파일 라이프사이클 — 생성·갱신·소멸

파이프라인 진행 상태는 /tmp/에 JSON 파일로 둡니다. 중요한 점은 상태 파일을 스크립트가 아닌 훅이 관리한다는 것입니다. 스크립트는 상태 파일 존재조차 모릅니다. 훅이 명령어 문자열의 키워드를 보고 외부에서 추적하므로, 기존 스크립트를 수정하지 않고도 파이프라인 추적을 붙일 수 있습니다.

{
  "pipeline": "calendar_sync",
  "step1_sync": true,
  "step2_content": false,
  "step3_git": false,
  "step4_notify": false,
  "claude_pid": 129677
}

• 생성: PostToolUse 훅이 명령어를 검사해 생성
• 갱신: 다음 Step 실행 시 해당 Step을 true로 변경
• 소멸(정상): Stop 훅에서 모든 Step이 true이면 삭제
• 소멸(비정상): 2시간 TTL + 세션 격리(claude_pid 비교)로 자동 정리

Stop 훅 — 미완료 작업 종료 차단

AI가 대화를 끝내려 할 때 Stop 훅이 실행됩니다. 이 훅은 모든 파이프라인 상태 파일을 돌면서 현재 세션에서 시작했지만 아직 끝나지 않은 작업이 있는지 확인합니다. 있으면 구체적인 미완료 목록을 보여주고 exit(2)로 종료를 차단합니다. AI는 이 목록을 보고 이어서 작업을 수행합니다.

Hook 설계 3대 원칙

1. 타임아웃 10초 이내: 훅이 느리면 전체 에이전트 체감 속도가 떨어집니다. 복잡한 로직은 비동기 처리로 빼세요.
2. exit(2) 차단, exit(0) 통과: Claude Code 훅 프로토콜. 이를 지키지 않으면 훅이 무시됩니다.
3. 훅은 감시만, 수정은 금지: 훅에서 파일을 건드리면 부작용으로 인한 디버깅 지옥이 시작됩니다.

다음 단계 예고 — Step 5 자동 트리거 + 완료 조건

Hook까지 갖추면 "사람이 명령하면 안전하게 돈다"까지 완성됩니다. 다음 편에서는 사람 없이도 시작되는 루프를 위해 cron/GitHub 이벤트/메시지 트리거와, 기계적 완료 조건(테스트·빌드·린트)을 다룹니다.

한 줄 요약: "Skill이 가속 페달이라면, Hook은 안전벨트와 브레이크다."

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.