Claude Code 후크 개요

Claude Code 후크는 라이프사이클의 특정 시점에 사용자 정의 셸 명령을 실행합니다.

후크는 알림, 자동 포맷팅, 로깅, 피드백, 권한 관리 등 다양한 용도로 사용됩니다.

설정 파일(~/.claude/settings.json 등)에 matcher와 hooks 배열로 구성하여 후크를 등록합니다.

후크 이벤트는 PreToolUse, PostToolUse, Notification, Stop 네 가지로 나뉩니다.

후크는 stdin으로 JSON 입력을 받고 exit 코드 또는 JSON 출력으로 제어 신호를 반환합니다.

Exit 코드 0은 성공, 2는 블로킹 에러, 그 외는 비차단 에러를 의미합니다.

JSON 출력으로 continue, decision, reason 필드를 사용해 더 정교한 제어가 가능합니다.

보안 고려사항으로 입력 검증, 변수 인용, 절대 경로 사용 등의 모범 사례가 필요합니다.

후크는 병렬로 실행되며 최대 60초 타임아웃과 세션 시작 시 스냅샷으로 외부 변경을 방지합니다.

디버깅은 /hooks 메뉴 확인, 설정 파일 JSON 유효성 검사, 수동 테스트, exit 코드 확인 등을 통해 수행합니다.