Claude Code Hooks 운영 루프: prompt·agent·async 훅으로 멈춤 기준 세우기 | DAKER 커뮤니티
Claude Code Hooks는 Claude가 알아서 잘 멈추기를 기다리는 대신, 팀이 정한 계속·멈춤 기준을 이벤트마다 확인하게 만드는 운영 루프입니다. Claude Code Hooks란, 세션 시작·프롬프트 제출·도구 호출·멈춤 시점 같은 lifecycle 이벤트에서 미리 정한 검사를 실행하는 자동화 장치입니다. 공식 Hooks reference는 command, HTTP, MCP tool, prompt, agent, async hook까지 같은 문서에서 다루므로, 이제 훅을 단순 차단 스크립트가 아니라 팀 완료 기준으로 설계할 수 있습니다.
문제 상황: 언제 Claude Code Hooks를 봐야 하나요?
훅을 처음 붙일 때는 위험 명령 차단만 떠올리기 쉽습니다. 하지만 긴 세션에서는 더 큰 문제가 ‘끝났다고 말해도 되는가’입니다. 이 기준이 없으면 리뷰, 테스트, 문서 업데이트가 빠진 채로 대화가 닫힙니다.
핵심 개념: 무엇을 기준으로 판단하나요?
prompt hook은 빠른 JSON 판단에, agent hook은 더 전문적인 검토에, async hook은 파일 변경 뒤 백그라운드 확인에 어울립니다. 이벤트마다 block이 대화에 미치는 영향이 다르므로 Stop과 SubagentStop부터 작게 시작하는 편이 좋습니다.
단계별 사용법: 오늘 어떤 순서로 적용하나요?
아래 순서는 처음 적용하는 팀이 바로 따라 할 수 있는 최소 루틴입니다.
- 먼저 훅의 목적을 차단, 보강, 완료 검산 중 하나로 정합니다.
- Stop 또는 SubagentStop에서 완료 기준을 점검할 짧은 prompt hook을 설계합니다.
- 도구 호출 전후 검사는 PreToolUse와 PostToolUse에만 좁게 둡니다.
- 시간이 걸리는 테스트나 파일 변경 검사는 async hook 후보로 분리합니다.
- block이 대화를 끝내는 이벤트와 Claude에게 이유를 돌려주는 이벤트를 구분해 문서화합니다.
짧은 예시: 선택 기준을 어떻게 말하면 좋나요?
작업 요청에는 목표, 확인 기준, 남은 한계를 함께 씁니다. 그러면 Claude Code 세션이 끝날 때 결과와 미확인 범위를 분리해 보고하기 쉬워집니다.
| 훅 종류 | 잘 맞는 역할 | 처음 적용할 기준 |
|---|---|---|
| Prompt Hook | 빠른 완료·정책 판단 | Stop에서 모든 요청이 끝났는지 묻습니다 |
| Agent Hook | 전문 검토가 필요한 판단 | 보안·리뷰처럼 별도 역할이 필요한 때 씁니다 |
| Async Hook | 파일 변경 뒤 오래 걸리는 확인 | 테스트나 포맷 확인을 백그라운드로 보냅니다 |
| Command Hook | 결정적 차단과 스크립트 실행 | 위험 명령이나 필수 로그 검사를 처리합니다 |
워크플로 이미지: 어떤 흐름으로 기억하면 되나요?
팀 적용 체크리스트: 무엇을 빠뜨리면 안 되나요?
체크리스트는 자동화를 더 많이 켜기 위한 문서가 아니라, 끝났다고 말할 수 있는 증거를 남기는 장치입니다.
- 훅이 막는 조건과 계속하게 하는 조건을 같은 문서에 적었나요?
- Stop 훅의 ok false 이유가 Claude에게 다음 행동으로 돌아가나요?
- PreToolUse 차단이 필요한지, PostToolUse 검산이면 충분한지 나눴나요?
- async hook 실패가 조용히 묻히지 않도록 로그 위치를 정했나요?
- 비밀값, 로컬 경로, 외부 URL이 훅 로그에 그대로 남지 않나요?
공식 출처: 어디를 기준으로 확인했나요?
작성 기준일 현재 기능 사실은 Anthropic 공식 Claude Code 문서 3개 항목으로 비공개 검증했습니다. 공개 링크는 DAKER 정책에 맞춰 아래 내부 링크만 남깁니다.
- DAKER 클로드 코드 디렉터리
- Claude Code hooks exit code 2 검증 글
- Claude Code PermissionRequest hooks 글
- Claude Code subagent hooks 글
FAQ: 자주 묻는 질문은 무엇인가요?
prompt hook은 무엇을 반환해야 하나요?
공식 reference 기준 prompt hook은 ok 값과 reason을 담은 JSON 판단을 반환합니다. ok가 false일 때의 효과는 이벤트마다 다릅니다.
Stop hook에서 ok false가 나오면 어떻게 되나요?
Stop과 SubagentStop에서는 reason이 Claude에게 다음 지시처럼 돌아가고, Claude가 남은 작업을 계속할 수 있습니다.
async hook은 모든 검증에 써도 되나요?
아닙니다. 시간이 걸리는 확인에 유용하지만 한계가 있으므로, 게시나 배포처럼 반드시 통과해야 하는 검사는 별도 게이트로 남겨야 합니다.
오늘 바로 붙일 훅은 무엇인가요?
긴 작업이 자주 미완료로 끝난다면 Stop prompt hook부터 붙여 ‘테스트, 문서, 남은 위험’을 확인하게 해 보세요.
오늘은 팀의 Claude Code 작업 하나를 골라 목표, 확인 기준, 남은 한계를 세 줄로 다시 써 보세요.