Claude Code 훅(hooks): 이벤트, 예시, 작동 방식

Claude Code 훅 이벤트

레퍼런스에는 30개가 넘는 이벤트가 있어요. 아래는 대부분의 훅이 쓰는 이벤트예요. matcher로 훅을 특정 도구, 파일, 소스로 좁힐 수 있어요.

훅을 두는 위치

Claude Code 훅 예시, 단계별로

각 블록을 설정 파일의 hooks 키 아래에 추가하세요. 파일에 이미 hooks 객체가 있다면 통째로 바꾸지 말고 이벤트를 같은 레벨의 키로 추가하세요. /hooks를 실행하면 Claude Code가 훅을 불러왔는지 확인할 수 있어요. Claude에게 훅을 대신 써 달라고 해도 돼요.

1. Claude가 나를 필요로 할 때 데스크톱 알림 받기

   ~/.claude/settings.json에 Notification 훅을 추가해요. 이 예시는 macOS의 osascript를 써요. Linux에서는 notify-send, Windows에서는 PowerShell을 쓰세요.

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       ]
     }
   }

2. Claude가 편집하는 모든 파일 자동 포맷팅하기

   Edit|Write에 매칭되는 PostToolUse 훅이 stdin의 JSON에서 편집된 파일 경로를 jq로 읽고 Prettier를 실행해요. .claude/settings.json에 두면 팀 전체가 함께 써요.

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
           ]
         }
       ]
     }
   }

3. 위험한 명령 차단하기

   Bash에 대한 PreToolUse 훅이 이 스크립트를 실행해요. 종료 코드 2는 호출을 차단하고, stderr에 쓴 내용은 Claude에게 피드백으로 전달돼서 Claude가 방향을 바꿀 수 있어요. 종료 코드 0은 결정하지 않는다는 뜻이라 일반 권한 확인이 그대로 적용돼요.

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh, Bash의 PreToolUse 훅으로 실행
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # Claude에게 전달되는 피드백
     exit 2                                               # 2 = 작업 차단
   fi
   
   exit 0  # 결정 없음: 일반 권한 흐름이 적용됨

4. 작업이 끝날 때까지 Claude가 계속 일하게 하기

   prompt 유형의 Stop 훅이 모든 작업이 끝났는지 모델에게 물어봐요. 답이 ok: false면 Claude는 reason을 다음 지시로 삼아 계속 일해요. 이게 대표적인 Stop 훅 예시예요.

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

출처: Claude Code 문서, Automate actions with hooks

훅이 동작을 결정하는 방식

• 입력: 각 훅은 도구 이름과 tool_input, 세션 ID, cwd 같은 이벤트 정보를 stdin으로 JSON 형태로 받아요.
• 종료 코드 0: 이의 없음. SessionStart, UserPromptSubmit 같은 일부 이벤트에서는 일반 stdout이 Claude의 컨텍스트에 추가돼요.
• 종료 코드 2: 이벤트가 허용하면 차단. stderr는 이벤트에 따라 Claude나 나에게 전달돼요.
• stdout으로 JSON 출력: 더 세밀한 제어. 권한 결정을 담은 hookSpecificOutput, 도구 입력을 고쳐 쓰는 updatedInput, additionalContext 등이 있어요.
• 그 밖의 종료 코드: 훅에 onFailure: "block"을 설정하지 않았다면 보통 차단하지 않는 오류로 처리돼요.
• 한 이벤트에 매칭된 여러 훅은 병렬로 실행돼요.

command, prompt, agent, HTTP 훅

훅 vs 스킬 vs CLAUDE.md, 그리고 주의할 점

• CLAUDE.md와 스킬은 Claude가 대체로 따르는 지시이고, 훅은 항상 실행돼요. 절대 건너뛰면 안 되는 일은 훅에 넣으세요.
• PostToolUse는 이미 실행된 작업을 되돌릴 수 없어요. 막으려면 PreToolUse를 쓰세요.
• Stop은 작업이 끝날 때만이 아니라 Claude가 응답을 마칠 때마다 실행되고, 사용자가 중단했을 때는 실행되지 않아요.
• 훅은 스스로 슬래시 명령을 실행하거나 도구를 호출할 수 없어요. 종료 코드, stdout, stderr, JSON으로만 응답해요.
• "disableAllHooks": true로 훅을 끌 수 있어요. 단, 관리형 훅은 관리형 설정에서도 끄지 않는 한 계속 실행돼요.
• 훅은 내 Claude Code 환경 안에서만 동작해요. 모든 Claude 제품에 걸친 조직 차원의 검사는 별개 기능인 Claude inference hooks예요.
• 테스트 출력을 걸러내는 PreToolUse 훅은 토큰 사용량을 줄이는 가장 좋은 방법 중 하나이기도 해요.

훅은 Claude Code가 규칙을 지키게 하고, Crewmark는 계속 일하게 해요.

사람 없이 돌아가는 에이전트를 안전하게 만드는 게 훅이에요. 포맷팅, 테스트, 가드레일이 매번 실행되니까요. Crewmark는 Claude Code, Codex, DeepSeek Harness, OpenCode 세션을 직무, 목표, 근무 시간을 가진 AI 직원으로 바꾸고, 하트비트로 깨워서 보드의 다음 이슈를 가져가게 해요. 프로젝트의 훅도 적용된 상태로요.

1. 훅을 커밋하기

   .claude/settings.json의 훅은 내 세션처럼 직원의 세션에서도 로드되므로, 직원이 편집한 파일은 포맷팅되고 위험한 명령은 차단돼요.

2. 하트비트로 일을 시작하게 하기

   근무 시간 동안 직원은 15분, 30분, 60분마다 같은 대화에서 깨어나요. Claude Code를 능동적으로 만드는 방법을 참고하세요.

3. 내가 필요한 일에만 답하기

   직원은 자기 이슈에 댓글을 남기고, 결정이 필요하면 메시지를 보내요. AI 직원이란도 읽어 보세요.

Claude Code 훅 자주 묻는 질문