Claude Code가 “완료”라고 답해도 테스트 실행이나 결과 파일 생성이 증명되지는 않습니다. Stop Hook은 turn이 끝나기 전에 짧은 로컬 검사를 실행할 수 있습니다. CI나 전체 테스트 전략을 대신하지는 않습니다.

최소 Hook

.claude/settings.json의 Stop 이벤트에서 ./scripts/check-before-stop.sh를 짧은 timeout으로 실행합니다. 스크립트는 focused test와 dist/app.js 같은 파일을 검사합니다.

성공하면 0을 반환합니다. 실패하면 stderr에 한 줄 이유를 쓰고 2를 반환합니다. Claude Code에서는 exit code 2만 Stop을 막고 이유를 Claude에게 전달합니다. 1은 보통 종료를 막지 않는 hook 오류입니다.


{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "./scripts/check-before-stop.sh",
        "timeout": 30
      }]
    }]
  }
}


chmod +x scripts/check-before-stop.sh

Stop Hook은 turn 끝에 검사를 실행합니다. CLAUDE.md는 규칙을 설명하지만 명령을 실행하지 않습니다. CI는 독립적으로 실행되며 최종 경계입니다.


npm test -- --runInBand >/dev/null 2>&1 || { echo "Stop blocked: npm test" >&2; exit 2; }
test -s dist/app.js || { echo "Stop blocked: dist/app.js missing" >&2; exit 2; }
exit 0

전체 흐름 검증

없는 파일 경로를 넣고 수동 실행에서 2를 확인합니다.
Claude Code로 작은 작업을 실행해 Stop이 막히고 짧은 이유가 표시되는지 봅니다.
테스트나 경로를 고친 뒤 다시 실행해 0에서 정상 종료되는지 확인합니다.
stop_hook_active가 true라면 무작정 retry하지 말고 지정된 검사를 고치거나 세션을 멈춰 hook을 수정합니다.

API Key, .env, 전체 로그를 출력하지 마세요. API 설정은 BetterToken Claude Code 문서에서 확인할 수 있습니다.

Claude Code Stop Hook: “완료” 전에 검사하기

최소 Hook

전체 흐름 검증

LLM 워크플로를 최적화할 준비가 되셨나요?