Claude Code는 코드 작성에 뛰어나지만, 여전히 확률 기반 시스템입니다. 파일을 편집할 때마다 Prettier를 실행하도록 요청할 수 있습니다. CLAUDE.md에 그 지시문을 작성할 수 있습니다. 하지만 때로는 그냥... 잊어버립니다. Claude Code hooks는 Claude가 수행하는 모든 동작 전후에 무엇이 일어나는지에 대해 결정적이고 보장된 제어를 제공함으로써 이 문제를 해결합니다.
지난 몇 개월 동안 수십 개의 프로젝트에서 hooks를 구성해왔으며, 이것이 나의 Claude Code 설정에서 가장 중요한 부분이 되었습니다. 이 가이드는 기초부터 오늘날 모든 프로젝트에 바로 적용할 수 있는 프로덕션 레디 스타터 키트까지 모든 것을 다룹니다. Cursor나 Copilot 같은 도구와 함께 Claude Code를 사용해본 적이 있다면, 이미 커스터마이제이션의 가치를 알고 있을 것입니다. hooks는 그것을 한 단계 더 나아갑니다.
Claude Code Hooks란 무엇인가요 (그리고 왜 신경 써야 할까요)?
Claude Code hooks는 Claude Code의 생명주기 내 특정 지점에서 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트 또는 LLM 프롬프트입니다. Anthropic의 공식 문서에 따르면, Claude가 무시할 수 있는 프롬프트 지시문과는 달리, hooks는 매번 결정적으로 실행되어 포매팅, 보안, 알림 및 워크플로우 자동화에 대해 보장된 제어를 제공합니다.
확률 기반의 문제
CLAUDE.md 지시문에 대한 문제점은 이렇습니다: 그것들은 제안일 뿐이지, 계약이 아닙니다. 프로젝트 컨텍스트에 "TypeScript 파일을 편집한 후 항상 npx prettier --write를 실행하라"고 작성할 수 있으며, Claude는 대부분 그것을 따를 것입니다. 하지만 팀 전체에서 코드 포매팅을 강제하거나, 프로덕션으로의 푸시를 차단하거나, 보안 감시를 위해 모든 셸 명령을 기록할 때 "대부분의 경우"는 충분하지 않습니다.
이것이 모든 AI 코딩 도구의 핵심 긴장입니다. Claude는 언어 모델입니다. 확률에 따라 작동합니다. 컨텍스트 엔지니어링은 동작을 유도할 수 있지만, 보장할 수는 없습니다.
Hooks가 이를 어떻게 해결하는가
Hooks는 LLM을 완전히 우회합니다. 특정 생명주기 이벤트에서 실행되는 셸 스크립트, HTTP 호출 또는 AI 평가입니다. 도구가 실행되기 전(PreToolUse), 완료된 후(PostToolUse), 알림이 나타날 때, 세션이 시작될 때, 또는 Claude가 중지할 때를 생각해보세요. Git hooks처럼 생각해 볼 수 있지만, AI 코딩 어시스턴트용입니다.
네 가지 hook 유형이 있습니다: command(셸 스크립트), HTTP(webhook POST 요청), prompt(단일 턴 Claude yes/no 평가) 및 agent(도구 액세스 권한이 있는 서브에이전트를 생성). 각각을 나중에 분석해볼 것입니다. command hooks는 필요한 것의 약 90%를 처리합니다.
Claude Code Hooks 작동 원리: 생명주기 플로우
Claude Code hooks는 정의된 생명주기에서 실행됩니다: 이벤트가 발생하면(예: PreToolUse), matcher가 hook이 적용되는지 확인하고, hook 스크립트가 실행되며 stdin에서 JSON을 받으며, 종료 코드가 다음에 무엇이 일어나는지를 결정합니다. 종료 코드 0은 계속 진행을 의미하고, 종료 코드 2는 동작을 차단합니다. 이 플로우는 사용하는 hook 유형과 관계없이 동일합니다.
이벤트 → Matcher → Hook → 종료 코드(4단계 플로우)
모든 hook 실행이 작동하는 방식은 다음과 같습니다:
stdin에 도달하는 JSON에는 이벤트에 대한 모든 것이 포함됩니다: tool_name, tool_input(파일 경로, 콘텐츠, 명령) 및 세션 메타데이터. 스크립트가 이 JSON을 읽고, 필요한 로직을 수행하고, 적절한 코드로 종료합니다.
PreToolUse hooks의 경우, 종료 코드 2가 강력한 코드입니다. 동작을 완전히 차단하고 stdout 메시지를 Claude에게 피드백으로 보냅니다. Claude는 메시지를 보고 접근 방식을 조정할 수 있습니다.
설정 범위: 사용자, 프로젝트 및 로컬
Hooks는 settings.json의 세 가지 수준에 있습니다:
프로젝트 설정은 팀에게 가장 유용합니다. hooks를 .claude/settings.json에 드롭하고, 커밋하면, 팀의 모든 개발자가 자동으로 동일한 보호장치를 얻게 됩니다.
if 필드: 세밀한 필터링
Claude Code v2.1.85 이후, hooks는 if 필드를 지원하여 도구 이름뿐만 아니라 도구 인자로도 필터링할 수 있습니다. Anthropic hooks 참조에서 문서화된 대로, 모든 단일 Bash 호출에서 발생하는 대신 git push와 일치하는 Bash 명령에서만 트리거되는 hook를 작성할 수 있습니다.
이것은 게임 체인저였습니다. if가 있기 전에는 너무 광범위하게 일치시키거나(모든 Bash 명령) 스크립트 내부에서 필터링해야 했습니다(지저분함).
모든 Claude Code Hook 이벤트: 빠른 참조 표
Claude Code는 공식 hooks 참조 및 Claude Code 변경 로그에 문서화된 생명주기 전반에 걸쳐 20개 이상의 hook 이벤트를 제공합니다. 가장 일반적으로 사용되는 것은 PreToolUse, PostToolUse, Notification 및 Stop입니다. 하지만 ConfigChange 및 FileChanged 같은 최신 이벤트는 고급 자동화 패턴을 열어줍니다.
완전한 참조는 다음과 같습니다:
전문가 팁: hooks의 80%에 PreToolUse와 PostToolUse를 사용할 것입니다. SessionStart는 그 다음으로 유용합니다. 모든 세션 시작 시 Claude가 필요로 하는 프로젝트 컨텍스트를 주입하기에 완벽합니다.
4가지 Claude Code Hook 유형 설명됨
Claude Code는 네 가지 hook 핸들러 유형을 지원합니다: command hooks는 셸 스크립트를 실행하고, HTTP hooks는 URL에 POST를 하며, prompt hooks는 Claude에게 yes/no 질문을 하고, agent hooks는 도구 액세스 권한이 있는 서브에이전트를 생성합니다. 우리의 경험에 따르면, command hooks는 사용 사례의 90%를 처리합니다. 외부 통합의 경우 HTTP를 사용하고, 세밀한 AI 판단이 필요한 결정의 경우 prompt 및 agent hooks를 사용합니다.
Command Hooks(주력)
Command hooks는 셸 명령을 실행하고 종료 코드를 사용하여 결과를 결정합니다. stdin에서 이벤트의 JSON 데이터를 받습니다.
포매팅, 파일 보호, 알림 및 대부분의 자동화에 사용할 것입니다. 빠르고, 간단하며, 예측 가능합니다.
HTTP Hooks(외부 통합)
HTTP hooks는 이벤트 JSON을 본문으로 하여 URL에 POST 요청을 보냅니다. 응답 상태 코드가 결과를 결정합니다(200 = 계속 진행, 403 = 차단).
Slack, Discord, PagerDuty 또는 사용자 정의 대시보드로 이벤트를 보내기에 좋습니다. 또한 이를 사용하여 도구 실행을 허용하기 전에 외부 정책 엔진을 쿼리할 수도 있습니다.
Prompt Hooks(AI 기반 결정)
Prompt hooks는 이벤트 데이터를 Claude 자체로 전달하여 단일 턴 yes/no 평가를 수행합니다. Claude는 "decision": "allow" 또는 "decision": "block" 그리고 이유를 포함한 JSON 응답을 반환합니다.
이를 드물게 사용하세요. 각 hook 실행마다 전체 LLM 호출에 대해 지연 시간과 비용이 추가됩니다. 하지만 "이 데이터베이스 마이그레이션이 파괴적으로 보이는가?"와 같이 진정으로 주관적인 보안 검사의 경우 이를 이기기 어렵습니다. Claude Code 모델 전환에 대해 궁금하다면, prompt hooks에 사용되는 모델은 현재 세션 모델을 따릅니다.
Agent Hooks(도구 지원 검증)
Agent hooks는 Read, Grep 및 Glob 도구에 액세스할 수 있는 서브에이전트를 생성합니다. 서브에이전트는 결정을 내리기 전에 파일을 검사할 수 있습니다.
이것은 가장 강력한 hook 유형이지만 가장 느립니다. 파일 컨텍스트가 좋은 결정을 내리는 데 필요한 고위험 검사를 위해 예약하세요.
7가지 프로덕션 레디 Claude Code Hook 예제(복사 붙여넣기 준비됨)
가장 유용한 Claude Code hooks에는 파일 편집 후 Prettier 또는 Black을 사용한 자동 포매팅, 보호된 파일에 대한 쓰기 차단, 작업 완료 시 데스크톱 알림 전송, 세션 시작 시 프로젝트 컨텍스트 주입, 코드 변경 후 테스트 실행, 브랜치 보호 강제 및 모든 도구 사용 감사가 포함됩니다. 지난 3개월 동안 이들의 변형을 모든 프로젝트에서 실행해왔습니다.
아래의 각 예제는 .claude/settings.json에 드롭할 수 있는 완전한 settings.json 스니펫입니다. awesome-claude-code와 같은 커뮤니티 컬렉션에는 더 많은 패턴이 있습니다.
1. 저장 시 자동 포매팅
이는 모든 Write 또는 Edit 후에 실행되고, stdin JSON에서 파일 경로를 추출하며, 적절한 포매터를 실행합니다. 끝의 exit 0은 hook이 절대 차단되지 않음을 보장합니다. 포매팅 실패가 Claude를 중단해서는 안 됩니다.
전문가 팁: .go에는 gofmt, .rs에는 rustfmt를 추가하십시오. 여러 언어를 다루는 경우.
2. 보호된 파일에 대한 쓰기 차단
...