Claude Code 완전 가이드 · 4 min read
Hooks 시스템
Claude Code의 에이전틱 루프 바깥에서 특정 이벤트에 반응하는 결정론적 스크립트입니다. LLM이 관여하지 않는 자동화 레이어입니다.
Hook 이벤트 (19개)
| # | 이벤트 | 설명 | 차단 |
|---|---|---|---|
| 1 | PreToolUse | 도구 호출 전 | Yes |
| 2 | PostToolUse | 도구 호출 후 | No |
| 3 | PostToolUseFailure | 도구 호출 실패 후 | No |
| 4 | PermissionRequest | 사용자 승인 요청 시 | No |
| 5 | UserPromptSubmit | 사용자 입력 제출 시 | Yes |
| 6 | Notification | 알림 전송 시 | No |
| 7 | Stop | Claude 응답 완료 시 | No |
| 8 | SubagentStart | 서브에이전트 시작 | No |
| 9 | SubagentStop | 서브에이전트 완료 | No |
| 10 | PreCompact | Compact 작업 전 | No |
| 11 | SessionStart | 세션 시작/재개 | No |
| 12 | SessionEnd | 세션 종료 | No |
| 13 | Setup | /setup 실행 시 | No |
| 14 | TeammateIdle | 팀원 유휴 상태 | No |
| 15 | TaskCompleted | 백그라운드 작업 완료 | No |
| 16 | ConfigChange | 설정 파일 변경 | No |
| 17 | WorktreeCreate | 워크트리 생성 | No |
| 18 | WorktreeRemove | 워크트리 제거 | No |
| 19 | InstructionsLoaded | CLAUDE.md 로드 시 | No |
4가지 핸들러 타입
1. Command (가장 일반적)
{
"type": "command",
"command": "python3 scripts/hooks.py",
"timeout": 5000,
"async": true
}2. HTTP (외부 서비스 알림)
{
"type": "http",
"url": "https://hooks.slack.com/services/...",
"method": "POST"
}3. Prompt (단일 턴 LLM)
{
"type": "prompt",
"prompt": "Review this code change for security issues",
"model": "haiku"
}4. Agent (멀티 턴 + 도구 사용)
{
"type": "agent",
"prompt": "Run the test suite and verify all tests pass",
"model": "sonnet"
}실전 활용 패턴
- 자동 포매팅 — PostToolUse에서 Write|Edit 후 eslint/prettier 실행 (Boris: CI 실패의 ~10%를 잡음)
- 위험 명령 차단 — PreToolUse에서
rm -rf,dd등 차단 (exit code 2 반환) - 품질 게이트 — Stop 훅에서 agent 타입으로 테스트 통과 확인
- 컨텍스트 주입 — SessionStart에서 최근 GitHub 이슈, 환경 정보 로드
- 보안 스캔 — PermissionRequest를 Opus로 라우팅하여 공격 패턴 분석 (Boris)
- 설정 감사 — ConfigChange로 모든 설정 변경 로깅
WARNING: 작성 중 차단(write-time blocking)보다 **제출 시 차단(block-at-submit)**을 사용하세요. 계획 중간에 끊기면 에이전트 성능이 저하됩니다. — Shrivu Shankar