Hooks

문제

훅을 등록해도 걸리는지 바로 알 수 없습니다. 다음 프롬프트를 쳐야 발동하므로, 스크립트가 죽어 있으면 그때 사고로 알게 됩니다.

추천

등록하기 전에 Claude Code를 거치지 않고 stdin으로 직접 입력을 넣어 동작을 확인합니다. 파일 있음·없음·무관 입력 세 분기를 전부 확인한 다음에 등록합니다.

예시

등록 한 줄

가드를 포함한 형태입니다. 스크립트가 없는 머신에서도 죽지 않습니다. 가드가 왜 필수인지는 Hooks에 있습니다.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "f=\"$HOME/<repo>/hooks/hint.py\"; [ -f \"$f\" ] && python3 \"$f\" || true",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

반복 주입이 노이즈라면 session_id별 상태 파일로 세션당 1회로 억제합니다.

파이프 테스트 명령

Claude Code를 거치지 않고 훅 스크립트에 직접 입력을 넣어 확인합니다. 등록 전에도, 등록 후 수정할 때도 이 명령으로 먼저 확인합니다.

echo '{"prompt":"npm run build 에러났어","session_id":"t1"}' \
  | sh -c 'f="$HOME/<repo>/hooks/hint.py"; [ -f "$f" ] && python3 "$f" || true'

세 분기를 다 확인합니다.

• 파일이 있고 프롬프트가 매칭되면 additionalContext가 나와야 합니다.
• 파일이 있고 프롬프트가 무관하면 아무 출력도 없어야 합니다. 0토큰입니다.
• 파일이 없으면 조용히 통과해야 합니다. exit 0입니다.

등록한 뒤에는 /hooks를 한 번 열거나 세션을 재시작해야 설정 워처가 읽습니다.

실패에서만 발동하는 훅

도구 실패에만 훅을 걸고 싶으면 PostToolUseFailure를 씁니다. 성공한 작업이나 일반 프롬프트에는 실행되지 않습니다.

{
  "hooks": {
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "f=\"$HOME/<repo>/hooks/hint.py\"; [ -f \"$f\" ] && python3 \"$f\" || true",
            "timeout": 2
          }
        ]
      }
    ]
  }
}

이유

훅 실행 계약은 Hooks에서 다룹니다. 가드가 필수인 이유, stdin/stdout 계약, cwd를 믿을 수 없는 이유가 거기 있습니다. 훅 성능 특성은 Rules에 있습니다. 지연에서는 매칭 로직보다 프로세스 기동 시간이 차지하는 비중이 큽니다. 여기서는 등록 전에 파이프로 검증하는 절차만 남깁니다.

하지 말 것

가드 없이 스크립트 경로를 하드코딩하기. 파일 없는 머신에서 매 프롬프트가 막힙니다. 자세한 사고 경로는 Hooks에 있습니다.

스크립트 안에서 예외를 그대로 던지기. 전면 try/except와 exit 0이 없으면 훅 하나가 전체 세션을 막습니다.

매칭 함수만 벤치마킹하고 “가벼우니 괜찮다”고 결론짓기. 실제 지연에는 프로세스 기동 시간이 포함됩니다. Rules를 참고하십시오.