Claude Code Hooks - 에이전트 라이프사이클 제어 시스템

개요

Claude Code Hooks는 AI 에이전트의 동작을 결정론적으로 제어할 수 있는 시스템입니다. 확률적인 AI 시스템에 결정론적 가드레일을 추가하는 개념입니다.

3가지 핸들러 타입

• Command (type: "command"): 셸 명령 실행, JSON stdin 입력/exit code 반환
• Prompt (type: "prompt"): Claude 모델에 단일 턴 평가 요청
• Agent (type: "agent"): Read, Grep, Glob 등 도구 접근 가능한 서브에이전트 생성

라이프사이클 이벤트

• SessionStart: 세션 시작 시
• PreToolUse: 도구 실행 전 (위험한 작업 차단 가능)
• PostToolUse: 도구 실행 후 (자동 포매팅 등)
• Notification: 알림 필요 시
• Stop: 응답 완료 시

Exit Code

• 0: 성공, 진행
• 2: 차단 (PreToolUse시 도구 호출 차단, stderr가 Claude에게 에러로 전달)

설정 위치

• ~/.claude/settings.json (전체 프로젝트)
• .claude/settings.json (프로젝트별, git 공유)
• .claude/settings.local.json (프로젝트별, gitignore)

Hooks vs CLAUDE.md

CLAUDE.md는 "아마 따를 것"이지만, Hooks는 "항상 실행"됩니다. 프로덕션/규제 환경에서 이 차이는 결정적입니다.

추천 시작점

1. PostToolUse에 자동 포매팅
2. PreToolUse에 위험 명령 차단
3. Stop에 데스크톱 알림

출처: Claude Code 공식 문서