Claude Code 훅(Hooks)은 세션의 특정 시점마다 자동으로 실행되는 사용자 정의 규칙입니다. AI가 "기억해서" 하는 게 아니라 조건이 맞으면 매번 셸 명령이 실행되므로 — 저장할 때마다 자동 포맷, 위험한 명령 차단, 테스트 통과 전 커밋 금지 같은 가드레일을 결정적으로 걸 수 있습니다. (공식: code.claude.com/hooks)
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
훅이란
훅은 Claude Code 생명주기의 특정 순간에 실행되는, 사용자가 정의한 이벤트 핸들러(보통 셸 스크립트)입니다. 핵심은 "결정적"이라는 점입니다. 모델이 포맷을 하거나 테스트를 돌릴 것을 기억하는지에 의존하지 않고, 조건이 맞으면 매번 실행됩니다. 그래서 팀의 비협상 규칙(non-negotiables)을 거는 데 적합합니다.
3요소: 이벤트 · 매처 · 액션
모든 훅은 세 부분으로 이루어집니다.
- 이벤트(Event) — 훅이 발동하는 생명주기 순간(예: PreToolUse, PostToolUse, Stop, SessionStart).
- 매처(Matcher) — 언제 실행할지 좁히는 선택적 필터(예: "Bash" 도구만, "Edit|Write" 작업만).
- 액션(Action) — 실제로 실행되는 것. 대부분 셸 명령입니다.
대표 이벤트
가장 많이 쓰이는 둘은 PreToolUse와 PostToolUse입니다.
- PreToolUse — 도구 실행 "전". 검증하거나 위험한 작업을 막기에 좋습니다.
- PostToolUse — 도구 완료 "후". 포맷팅·테스트 같은 정리 작업에 어울립니다(단 이미 실행된 작업을 되돌리지는 못하고 피드백만 줍니다).
- Stop — Claude가 응답을 끝내려 할 때. 마무리 점검·알림에 씁니다.
- SessionStart / SessionEnd — 세션 시작·종료 시(준비·정리).
이 외에도 여러 이벤트가 있으며, 전체 목록과 개수는 버전에 따라 다릅니다 — /hooks나 공식 문서에서 확인하세요.
설정과 통신
설정은 두 가지입니다. 인터랙티브 /hooks 명령이 이벤트·매처·명령 선택을 안내해 주거나, ~/.claude/settings.json(전역)·.claude/settings.json(프로젝트)을 JSON으로 직접 편집합니다. 이벤트가 발동하면 Claude Code가 세션 ID·작업 디렉터리·도구 이름·입력 같은 JSON 맥락을 핸들러에 넘깁니다(command 훅은 stdin으로). 핸들러는 이를 보고 행동한 뒤 종료 코드로 결과를 전합니다. PreToolUse 훅이 종료 코드 2로 끝나면 그 도구 실행이 차단됩니다.
실전 예
- 자동 포맷 — PostToolUse + 매처 "Edit|Write" +
prettier --write. 파일을 저장할 때마다 포맷이 맞춰집니다. - 위험 명령 차단 — PreToolUse + 매처 "Bash"에서 위험한 패턴을 보면 종료 코드 2로 막습니다.
- 테스트 게이트 — Stop 훅으로 테스트가 통과해야 마무리되도록 거는 식의 점검.
알아둘 점
- 핸들러 4종 — command(셸)·prompt·agent·http. 일상 용도 대부분은 command로 충분합니다.
- 서브에이전트에도 발동 — Claude가 서브에이전트를 통해 도구를 쓰면, 그 도구에도 PreToolUse·PostToolUse 훅이 실행됩니다. 안전 게이트를 우회당하지 않게 해 줍니다.
- 동기 실행 = 성능 — 각 훅은 동기로 돌아 매칭된 도구 호출에 실행 시간이 더해집니다. 무거운 훅은 세션을 느리게 만들 수 있으니 빠르게 유지하세요.
- 팀 공유 — 프로젝트
.claude/settings.json에 두면 팀 전체가 같은 가드레일을 공유합니다.
관련 글
- 서브에이전트 — 작업 위임(훅이 함께 발동)
- 슬래시 명령어 —
/hooks로 설정 - 사용법 가이드 — 터미널에서 쓰기
- CLAUDE.md 가이드 — 프로젝트 규칙 전달
고지: 이 글은 Anthropic 공식 Claude Code 문서(code.claude.com)를 기준으로 작성했습니다. 훅 이벤트의 개수·이름·입력 스키마·종료 코드 동작은 정책과 버전에 따라 달라질 수 있으므로(변동 가능) /hooks와 공식 문서에서 확인하세요. 위험 명령 차단 등 보안용 훅은 보조 안전장치이며 완전한 방어를 보장하지 않습니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.