Claude Code Hooks 운영 루프: prompt·agent·async 훅으로 멈춤 기준 세우기 | DAKER 커뮤니티
Claude Code Hooks를 처음 떠올릴 때는 대개 위험한 명령을 막는 장치부터 생각하게 됩니다. 하지만 실제로 긴 세션을 운영하다 보면 더 자주 부딪히는 문제는 따로 있습니다. 정말 끝났다고 말해도 되는지, 그 기준이 대화 안에서 분명하게 확인되지 않는다는 점입니다.
이 글은 Claude가 알아서 잘 멈추기를 기대하는 대신, 팀이 정한 계속·멈춤 기준을 lifecycle 이벤트마다 확인하는 운영 루프로서 Claude Code Hooks를 바라봅니다. Claude Code Hooks란 세션 시작·프롬프트 제출·도구 호출·멈춤 시점 같은 이벤트에서 미리 정한 검사를 실행하는 자동화 장치입니다. 공식 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 | 결정적 차단과 스크립트 실행 | 위험 명령이나 필수 로그 검사를 처리합니다 |
운영 흐름은 어떻게 기억하면 되나요?
전체 흐름은 단순합니다. 먼저 종료 시점에서 완료 기준을 확인하고, 도구 호출 전후에는 꼭 필요한 검사만 두며, 오래 걸리는 확인은 async hook으로 분리합니다. 이렇게 나누면 대화 흐름을 과하게 끊지 않으면서도 필요한 검증을 유지할 수 있습니다.
팀 적용 때 빠뜨리기 쉬운 점은 무엇인가요?
체크리스트는 자동화를 더 많이 켜기 위한 문서가 아니라, 끝났다고 말할 수 있는 증거를 남기는 장치입니다.
- 훅이 막는 조건과 계속하게 하는 조건을 같은 문서에 적었나요?
- Stop 훅의 ok false 이유가 Claude에게 다음 행동으로 돌아가나요?
- PreToolUse 차단이 필요한지, PostToolUse 검산이면 충분한지 나눴나요?
- async hook 실패가 조용히 묻히지 않도록 로그 위치를 정했나요?
- 비밀값, 로컬 경로, 외부 URL이 훅 로그에 그대로 남지 않나요?
자주 묻는 질문
prompt hook은 무엇을 반환해야 하나요?
공식 reference 기준 prompt hook은 ok 값과 reason을 담은 JSON 판단을 반환합니다. ok가 false일 때의 효과는 이벤트마다 다릅니다.
Stop hook에서 ok false가 나오면 어떻게 되나요?
Stop과 SubagentStop에서는 reason이 Claude에게 다음 지시처럼 돌아가고, Claude가 남은 작업을 계속할 수 있습니다.
async hook은 모든 검증에 써도 되나요?
아닙니다. 시간이 걸리는 확인에 유용하지만 한계가 있으므로, 게시나 배포처럼 반드시 통과해야 하는 검사는 별도 게이트로 남겨야 합니다.
오늘 바로 붙일 훅은 무엇인가요?
긴 작업이 자주 미완료로 끝난다면 Stop prompt hook부터 붙여 테스트, 문서, 남은 위험을 확인하게 하는 방식이 출발점이 될 수 있습니다.
참고 자료
- DAKER 클로드 코드 디렉터리
- Claude Code hooks exit code 2 검증 글
- Claude Code PermissionRequest hooks 글
- Claude Code subagent hooks 글
여러분의 팀에서는 Claude Code가 끝났다고 말하기 전에 어떤 기준을 한 번 더 확인하면 가장 도움이 되나요?