훅(Hooks)으로 동작 강제하기

지침 파일에 "이건 하지 마세요"라고 적는 것은 부탁입니다. 훅은 규칙입니다. 하네스가 직접 실행하므로 모델의 판단과 무관하게 항상 동작합니다.

언제 훅이 필요한가

• "매번 X한 다음에 Y해줘" 같은 반복 요구가 있을 때
• 절대 일어나면 안 되는 명령이 있을 때 (rm -rf, 강제 푸시)
• 수정 후 항상 포매터나 린터를 돌려야 할 때
• 세션 시작마다 특정 정보를 주입하고 싶을 때

주요 시점

PreToolUse만이 차단 능력을 가집니다. 나머지는 관찰과 후처리용입니다.

예시 1 — 위험 명령 차단

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/guard.sh" }
        ]
      }
    ]
  }
}

guard.sh는 표준 입력으로 실행하려는 명령을 받고, 종료 코드로 판정합니다.

#!/usr/bin/env bash
input=$(cat)
if echo "$input" | grep -qE 'rm -rf /|git push --force'; then
  echo "차단됨: 되돌릴 수 없는 명령입니다." >&2
  exit 2   # 0이 아닌 값 → 실행 차단
fi
exit 0

예시 2 — 저장 후 자동 포맷

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATHS" }
        ]
      }
    ]
  }
}

이렇게 두면 "포맷 맞춰줘"라고 매번 말할 필요가 없습니다. 규칙이 되었기 때문입니다.

설계 원칙

1. 빠르게 끝나야 한다

훅은 매 도구 호출마다 실행됩니다. 수 초씩 걸리면 전체 작업이 체감상 느려집니다.

2. 조용해야 한다

정상 경로에서는 아무것도 출력하지 마세요. 출력은 곧 컨텍스트 소비입니다.

3. 실패해도 안전해야 한다

훅 스크립트 자체에 버그가 있으면 모든 작업이 막힙니다. 차단 조건은 좁고 명확하게 쓰세요.

4. 차단 이유를 알려준다

stderr에 남긴 메시지는 모델에게 전달됩니다. "왜 막혔는지"를 알려주면 다른 방법을 찾아 진행합니다.

디버깅

훅이 동작하지 않을 때 점검 순서:

1. 스크립트에 실행 권한이 있는가 (chmod +x)
2. 경로가 절대 경로인가 (~는 셸에 따라 확장되지 않을 수 있음)
3. matcher 패턴이 실제 도구 이름과 맞는가
4. 스크립트를 터미널에서 직접 실행하면 어떻게 되는가

훅은 "AI를 못 믿어서" 쓰는 장치가 아니라, 자율 실행 범위를 넓히기 위해 쓰는 장치입니다. 사고 가능성을 구조적으로 막아 두면 훨씬 과감하게 맡길 수 있습니다.