Claude Code 훅: 프로덕션 예제로 완성하는 개발자 완벽 가이드

Claude Code 훅: 프로덕션 대응 예제가 포함된 개발자 완전 가이드

Claude Code는 코드 작성에 뛰어나지만, 여전히 확률적 시스템입니다. 파일 편집 후마다 Prettier를 실행하라고 요청할 수도 있고, 그 지시사항을 CLAUDE.md에 넣어둘 수도 있습니다. 그런데 가끔은 그저... 잊어버립니다. Claude Code 훅은 Claude가 수행하는 모든 작업의 이전, 도중, 이후에 일어나는 일을 결정적이고 확실하게 제어할 수 있게 해줌으로써 이 문제를 해결합니다.

지난 몇 달간 수십 개의 프로젝트에서 훅을 설정해 왔고, 어느새 훅은 제 Claude Code 설정에서 가장 중요한 부분이 되었습니다. 이 가이드는 기초부터 지금 당장 어떤 프로젝트에든 그대로 적용할 수 있는 프로덕션 대응 스타터 키트까지 모든 것을 다룹니다. Claude Code를 Cursor나 Copilot 같은 도구와 함께 사용해 본 적이 있다면 커스터마이징의 가치를 이미 알고 있을 것이며, 훅은 거기서 한 단계 더 나아갑니다.

Claude Code 훅이란? (그리고 왜 알아야 할까?)

Claude Code 훅은 Claude Code 라이프사이클의 특정 지점에서 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트 또는 LLM 프롬프트입니다. Anthropic 공식 문서에 따르면, Claude가 무시할 수 있는 프롬프트 지침과 달리 훅은 매번 결정적으로 실행되어 서식, 보안, 알림, 워크플로우 자동화에 대한 확실한 제어권을 제공합니다.

확률적 문제

CLAUDE.md 지시사항에는 이런 특성이 있다. 그것은 계약이 아니라 제안이라는 점이다. 프로젝트 컨텍스트에 "TypeScript 파일을 편집한 후에는 항상 npx prettier --write를 실행하라"고 적어 둘 수 있고, Claude는 대부분의 경우 이를 따를 것이다. 하지만 팀 전체의 코드 포맷을 강제하거나, 프로덕션으로의 푸시를 차단하거나, 보안 감사를 위해 모든 셸 명령을 기록하는 상황에서는 "대부분의 경우"로는 충분하지 않다.

이것이 모든 AI 코딩 도구가 안고 있는 핵심적인 긴장이다. Claude는 언어 모델이며, 확률에 기반해 작동한다. 컨텍스트 엔지니어링으로 행동을 유도할 수는 있지만, 보장할 수는 없다.

훅이 이 문제를 해결하는 방법

훅은 LLM을 완전히 우회합니다. 훅은 특정 라이프사이클 이벤트에서 실행되는 셸 스크립트, HTTP 호출 또는 AI 평가입니다. 도구가 실행되기 전(PreToolUse), 완료된 후(PostToolUse), 알림이 나타날 때, 세션이 시작될 때, 또는 Claude가 멈출 때 작동합니다. Git 훅과 비슷하지만, AI 코딩 어시스턴트를 위한 것이라고 생각하시면 됩니다.

네 가지 훅 유형이 존재합니다. command(셸 스크립트), HTTP(웹훅 POST 요청), prompt(단일 턴 Claude 예/아니오 평가), 그리고 agent(도구 접근 권한을 가진 서브에이전트 생성)입니다. 각각에 대해 나중에 자세히 설명하겠지만, command 훅으로 필요한 작업의 약 90%를 처리할 수 있습니다.

Claude Code Hooks의 작동 방식: 라이프사이클 흐름

Claude Code hooks는 정의된 라이프사이클에 따라 실행됩니다. 이벤트가 발생하고(예: PreToolUse), matcher가 해당 hook의 적용 여부를 확인한 뒤, hook 스크립트가 실행되면서 stdin으로 JSON을 전달받고, 종료 코드가 이후 동작을 결정합니다. 종료 코드 0은 계속 진행, 종료 코드 2는 해당 작업 차단을 의미합니다. 이 흐름은 어떤 hook 타입을 사용하든 동일합니다.

이벤트 -> 매처 -> 훅 -> 종료 코드 (4단계 흐름)

모든 훅 실행은 다음과 같이 작동합니다:

1. EVENT FIRES          e.g., PreToolUse(Write)
       |
2. MATCHER CHECKS       Does "Write" match the hook's matcher pattern?
       |
3. HOOK EXECUTES        Shell script runs, receives JSON via stdin
       |
4. EXIT CODE DECIDES    0 = proceed | 2 = block | other = error

stdin으로 전달되는 JSON에는 이벤트에 대한 모든 정보가 담겨 있습니다: tool_name, tool_input(파일 경로, 내용, 명령어), 그리고 세션 메타데이터가 그것입니다. 스크립트는 이 JSON을 읽어 필요한 로직을 수행한 뒤, 적절한 코드로 종료합니다.

PreToolUse 훅의 경우, 종료 코드 2가 가장 강력한데, 이 코드는 해당 동작을 완전히 차단하고 사용자의 stdout 메시지를 피드백으로 Claude에게 다시 전달하기 때문입니다. Claude는 이 메시지를 확인하고 자신의 접근 방식을 조정할 수 있습니다.

설정 범위: 사용자, 프로젝트, 로컬

훅은 세 가지 수준의 settings.json에 저장됩니다:

프로젝트 설정은 팀에게 가장 유용합니다. 훅을 .claude/settings.json에 넣고 커밋하면, 팀의 모든 개발자가 동일한 가드레일을 자동으로 적용받게 됩니다.

if 필드: 세분화된 필터링

Claude Code v2.1.85부터 훅은 도구 이름뿐 아니라 도구 인자로도 필터링할 수 있는 if 필드를 지원합니다. Anthropic 훅 레퍼런스에 문서화되어 있듯이, 이를 통해 모든 Bash 호출마다 실행되는 대신 git push와 일치하는 Bash 명령에서만 트리거되는 훅을 작성할 수 있습니다.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

이는 큰 개선이었습니다. if 이전에는 너무 광범위하게 일치시키거나(모든 Bash 명령), 스크립트 내부에서 필터링을 해야 했습니다(지저분한 방식).

모든 Claude Code 훅 이벤트: 빠른 참조 표

Claude Code는 라이프사이클 전반에 걸쳐 20개 이상의 훅 이벤트를 제공하며, 이는 공식 훅 레퍼런스와 Claude Code 변경 로그에 문서화되어 있습니다. 가장 많이 사용되는 것은 PreToolUse, PostToolUse, Notification, Stop이지만, ConfigChange나 FileChanged 같은 새로운 이벤트는 고급 자동화 패턴을 가능하게 합니다.

전체 참조 표는 다음과 같습니다:

프로 팁: 훅의 80%는 PreToolUse와 PostToolUse를 사용하게 될 것입니다. 그다음으로 유용한 것은 SessionStart로, 모든 세션 시작 시 Claude가 필요로 하는 프로젝트 컨텍스트를 주입하는 데 안성맞춤입니다.

Claude Code의 4가지 훅 유형 설명

Claude Code는 네 가지 훅 핸들러 유형을 지원합니다. command 훅은 셸 스크립트를 실행하고, HTTP 훅은 URL로 POST를 보내며, prompt 훅은 Claude에게 예/아니오 질문을 던지고, agent 훅은 도구 접근 권한을 가진 서브에이전트를 생성합니다. 경험상 command 훅으로 사용 사례의 90%를 처리할 수 있습니다. 외부 연동에는 HTTP를, AI의 판단이 필요한 섬세한 결정에는 prompt 훅과 agent 훅을 사용하세요.

커맨드 훅 (핵심 일꾼)

커맨드 훅은 셸 명령어를 실행하고 종료 코드를 사용해 결과를 판별합니다. 이벤트의 JSON 데이터를 stdin으로 전달받습니다.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

포맷팅, 파일 보호, 알림 및 대부분의 자동화에 바로 이것을 사용하게 됩니다. 빠르고, 간단하며, 예측 가능합니다.

HTTP 훅 (외부 연동)

HTTP 훅은 이벤트 JSON을 본문으로 담아 지정된 URL로 POST 요청을 보냅니다. 응답 상태 코드에 따라 결과가 결정됩니다(200 = 진행, 403 = 차단).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

Slack, Discord, PagerDuty 또는 커스텀 대시보드로 이벤트를 전송하는 데 적합합니다. 또한 도구 실행을 허용하기 전에 외부 정책 엔진에 질의하는 용도로도 활용할 수 있습니다.

프롬프트 훅 (AI 기반 의사결정)

프롬프트 훅은 이벤트 데이터를 Claude 자체에 전달하여 단일 턴으로 예/아니오 평가를 수행합니다. Claude는 "decision": "allow" 또는 "decision": "block"과 그 근거를 담은 JSON 응답을 반환합니다.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

이 기능은 아껴 사용하세요. 훅 실행마다 전체 LLM 호출이 발생하여 지연 시간과 비용이 추가됩니다. 하지만 "이 데이터베이스 마이그레이션이 파괴적으로 보이는가?"처럼 진정으로 주관적인 안전 점검이 필요한 경우에는 이만한 대안이 없습니다. Claude Code 모델 전환에 관심이 있으시다면, 프롬프트 훅에 사용되는 모델은 현재 세션 모델을 따릅니다.

에이전트 훅 (도구 지원 검증)

에이전트 훅은 Read, Grep, Glob 도구에 접근할 수 있는 하위 에이전트를 생성합니다. 하위 에이전트는 결정을 내리기 전에 파일을 검사할 수 있습니다.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

가장 강력한 훅 유형이지만, 가장 느리기도 합니다. 좋은 판단을 위해 파일 컨텍스트가 필요한 중요한 검증에만 사용하세요.

7가지 실전용 Claude Code 훅 예제 (복사-붙여넣기 가능)

가장 유용한 Claude Code 훅으로는 파일 수정 후 Prettier나 Black으로 자동 포맷팅, 보호된 파일에 대한 쓰기 차단, 작업 완료 시 데스크톱 알림 전송, 세션 시작 시 프로젝트 컨텍스트 주입, 코드 변경 후 테스트 실행, 브랜치 보호 규칙 적용, 모든 도구 사용 감사 등이 있습니다. 저는 지난 3개월간 모든 프로젝트에서 이 훅들의 다양한 변형 버전을 운영해 왔습니다.

아래 각 예제는 .claude/settings.json에 바로 넣을 수 있는 완성된 settings.json 스니펫입니다. awesome-claude-code 같은 커뮤니티 컬렉션에는 더 다양한 패턴이 있습니다.

1. 저장 시 자동 포맷

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

이 훅은 모든 Write 또는 Edit 이후에 실행되며, stdin JSON에서 파일 경로를 추출해 적절한 포매터를 실행합니다. 마지막의 exit 0은 훅이 절대 차단하지 않도록 보장합니다. 포맷 실패로 Claude가 멈춰서는 안 됩니다.

Pro 팁: 여러 언어를 사용한다면 *.go에는 gofmt을, *.rs에는 rustfmt을 추가하세요.

2. 보호된 파일에 대한 쓰기 차단

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

종료 코드 2는 해당 작업을 차단하고 JSON 메시지를 Claude에게 다시 전달합니다. Claude는 피드백을 확인하고 대응을 조정하는데, 대개 해당 파일을 수정하려 했다고 알려주면서 수동으로 처리해 달라고 요청합니다. if 필드는 이 규칙이 모든 Write에서 실행되지 않도록 막아줍니다.

3. 작업 완료 시 데스크톱 알림

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

macOS(osascript)와 Linux(notify-send)에서 작동합니다. matcher가 비어 있으면 모든 알림에 반응합니다. 오래 걸리는 작업을 시작해 놓고 다른 창으로 전환할 때 정말 유용합니다.

4. 세션 시작 시 컨텍스트 주입

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

이렇게 하면 현재 프로젝트 이름, Git 브랜치, 마지막 커밋이 모든 세션에 주입됩니다. Claude는 이 컨텍스트를 자동으로 전달받으므로, 어떤 브랜치에 있는지 별도로 알려줄 필요가 없습니다.

5. 코드 변경 후 테스트 자동 실행

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

일치하는 테스트 파일이 있으면, Claude가 소스를 수정한 후 자동으로 실행됩니다. tail -5는 출력을 간결하게 유지하고, timeout은 테스트 스위트가 과도하게 실행되는 것을 방지합니다. 이는 AI 기반 코드 리뷰 워크플로우와 잘 어울립니다.

6. 브랜치 보호 적용 (고급)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

이 설정은 main, master, production 브랜치를 대상으로 하는 모든 git push를 차단합니다. Claude는 이에 대한 피드백을 받고, 대신 기능 브랜치 생성을 제안합니다.

7. 보안 감사 로깅 (고급)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

Claude가 실행하는 모든 Bash 명령을 UTC 타임스탬프와 함께 감사 파일에 기록합니다. 보안 검토와 세션 중 Claude가 실제로 수행한 작업을 파악하는 데 매우 유용합니다. .claude/audit.log는 .gitignore에 추가해 두세요.

훅(Hooks) vs MCP vs 스킬(Skills) vs CLAUDE.md: 무엇을 언제 써야 할까

반드시 항상 실행되어야 하는 결정론적 자동화(포맷팅, 차단, 알림)에는 훅을 사용하세요. Claude에게 외부 도구와 데이터에 대한 접근 권한을 부여하려면 MCP를 사용하세요. 재사용 가능한 프롬프트 패키지에는 스킬을 사용하세요. 행동 지침과 프로젝트 컨텍스트에는 CLAUDE.md를 사용하세요. 훅은 보장되지만, 그 외의 모든 것은 확률적입니다. 이것이 가장 중요한 단일 구분이며, 저는 팀에 조언할 때마다 이 지점으로 계속 돌아오게 됩니다.

의사결정 매트릭스

MCP에 대한 심층 분석은 MCP 가이드를 확인하세요. Cursor에서 넘어오셨다면, Cursor의 규칙 시스템이 CLAUDE.md와 대략 유사하지만, Cursor에는 hooks와 같은 기능이 없습니다.

서로 겹칠 때 (그리고 선택하는 방법)

제가 사용하는 의사결정 흐름은 다음과 같습니다:

• "예외 없이 매번 반드시 실행되어야 하는가?", Hook. 코드 포맷, 보호된 파일 차단, 알림 전송. 모호함이 전혀 없습니다.
• "Claude에게 없는 새로운 기능이 필요한가?", MCP 서버. 데이터베이스 접근, API 호출, 외부 문서 검색.
• "특정 워크플로를 위한 재사용 가능한 지침을 원하는가?", Skill(슬래시 명령어). 코드 리뷰 템플릿, 배포 체크리스트.
• "이 프로젝트에서 Claude의 행동을 형성하고 싶은가?", CLAUDE.md. 코딩 표준, 아키텍처 결정, 선호하는 라이브러리.

경계를 명확히 해주는 실제 예시:

• "항상 Prettier로 포맷해" = Hook (매번 반드시 실행되어야 함)
• CLAUDE.md에 "포맷에는 Prettier를 사용해" = Guidance (Claude가 잊을 수 있음)
• "우리 회사 문서를 검색해" = MCP (새로운 기능)
• "코드 리뷰할 때 우리 스타일 가이드를 따라" = Skill 또는 CLAUDE.md

Anthropic의 플러그인 발표에서 설명했듯이, Hook은 MCP와 Skill을 포함하는 더 넓은 플러그인 생태계의 한 부분입니다. 이들은 서로 경쟁하기보다 보완하도록 설계되었습니다.

스타터 키트: 어떤 프로젝트든 바로 적용할 수 있는 Claude Code Hooks 설정

Claude Code용 스타터 hooks 설정에는 파일 편집 시 자동 포맷, 작업 완료 시 알림, 민감한 파일 보호, 세션 컨텍스트 주입, 그리고 정리를 위한 stop hook이 포함되어야 합니다. 이 설정은 제가 모든 새 프로젝트에 그대로 적용하는 바로 그 구성으로, 스택에 맞게 조정하지만 구조는 동일하게 유지됩니다.

설정

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

스택에 맞게 커스터마이즈하는 방법

위의 설정에서 포맷 명령어와 테스트 명령어를 사용 중인 스택에 맞게 교체하세요. 구조는 동일하게 유지됩니다.

후크가 작동하는지 확인하기

후크가 활성화되어 있는지 확인하는 세 가지 방법:

1. /hooks 명령어, Claude Code에서 /hooks를 입력하면 등록된 모든 후크와 매처(matcher), 상태를 확인할 수 있습니다.
2. 트랜스크립트 검사, 후크가 실행된 후 세션 트랜스크립트를 확인하세요. 후크 실행 기록이 출력 내용 및 종료 코드와 함께 표시됩니다.
3. 빠른 토글, settings.json에 "disableAllHooks": true를 추가하면 설정을 삭제하지 않고도 모든 후크를 일시적으로 비활성화할 수 있습니다. 이를 제거하거나(또는 false로 설정하여) 다시 활성화할 수 있습니다.

CI/CD 통합: 헤드리스 모드의 Claude Code 훅

Claude Code 훅은 헤드리스 모드(claude -p)에서도 작동하지만 몇 가지 차이점이 있습니다. Notification 훅은 계속 트리거되지만, 데스크톱 알림 대신 로깅으로 리다이렉트하는 것이 좋습니다. 종료 코드 2를 반환하는 PreToolUse 훅은 사람의 검토를 위해 헤드리스 세션을 일시 중지할 수 있습니다. GitHub Actions는 훅과 함께 anthropics/claude-code-action@v1을 사용합니다. 이를 통해 자동화된 워크플로를 구축할 수 있습니다.

헤드리스 모드 동작

헤드리스 모드에서의 큰 놀라움: 종료 코드 2로 종료되는 PreToolUse 훅은 단순히 조용히 실패하지 않습니다. 세션을 일시 중지하고 --resume으로 재개할 수 있게 해주며, 이를 통해 CI 파이프라인에 사람이 개입하는(human-in-the-loop) 패턴을 제공합니다.

GitHub Actions 통합

다음은 훅과 함께 Claude Code를 사용하는 최소한의 GitHub Actions 워크플로입니다. 공식 GitHub Actions 가이드에 안내된 대로:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.claude/settings.json 훅은 저장소를 따라 이동하므로, CI에서도 로컬과 정확히 동일하게 실행됩니다. 다만 데스크톱 전용 도구(osascript 등)에 의존하는 훅에는 폴백이나 조건문을 반드시 마련해 두세요.

팀 훅 관리

팀에서 효과적으로 작동하는 패턴입니다:

• .claude/settings.json (커밋됨), 팀 공유 훅: 파일 보호, 포매터, 브랜치 보호. 모든 구성원에게 적용됩니다.
• .claude/settings.local.json (gitignore됨), 개인 훅: 알림 환경설정, 커스텀 로깅, 실험적 훅.
• ~/.claude/settings.json (사용자 전역), 모든 프로젝트에 적용되는 기본값: 알림 스타일, 개인 포맷팅 환경설정.

이는 .editorconfig(커밋됨)와 로컬 IDE 설정(개인)이 작동하는 방식과 유사합니다. Angelo Lima의 CI/CD 가이드에서 언급했듯이, 공유 훅을 표준화한 팀은 Claude Code에서 "제 컴퓨터에서는 잘 되는데요" 문제가 적게 발생합니다.

Claude Code 훅 문제 해결 및 흔한 실수

Claude Code 훅에서 자주 발생하는 문제로는 훅이 실행되지 않는 경우(매처 철자와 settings.json 위치를 확인하세요), 훅은 실행되지만 차단하지 못하는 경우(잘못된 종료 코드, 1이 아닌 2를 사용하세요), 무한 루프(Stop 훅이 자기 자신을 다시 트리거하는 경우), 그리고 느린 시작 속도(동기 훅이 너무 많은 경우)가 있습니다. 제가 가장 자주 보는 실수는 종료 코드 혼동인데, 개발자들이 exit 2를 의도하면서 exit 1을 사용하는 경우입니다.

Hook이 실행되지 않음

증상: Hook을 추가했지만 이벤트가 발생해도 아무 일도 일어나지 않습니다.

해결 방법:

• Matcher 오타, Matcher는 대소문자를 구분합니다. "write"는 Write 도구와 일치하지 않습니다. /hooks로 정확한 도구 이름을 확인하세요.
• 잘못된 설정 파일, ~/.claude/settings.json에 있는 Hook은 프로젝트 스코프의 /hooks 출력에 표시되지 않습니다. 프로젝트 루트의 .claude/settings.json을 사용해 보세요.
• JSON 구문 오류, 불필요한 쉼표나 누락된 괄호가 있으면 전체 hooks 설정이 조용히 비활성화됩니다. jq .로 settings.json의 유효성을 검사하세요.
• disableAllHooks: true, 누군가(또는 이전 디버깅 세션)가 이 플래그를 켜둔 것은 아닌지 확인하세요.

훅은 실행되지만 차단하지 않음

증상: PreToolUse 훅이 실행되지만, 해당 작업이 그대로 계속 진행됩니다.

해결 방법:

• 잘못된 종료 코드, 종료 코드 1은 "오류"(훅 실패)를 의미하며, "차단"을 의미하지 않습니다. 작업을 차단하려면 exit 2를 사용하세요. 공식 문서에서도 언급하듯, 거의 모든 사람이 이 부분에서 실수합니다.
• stdout JSON 누락, 차단 훅의 경우, 작업이 차단된 이유를 Claude가 알 수 있도록 JSON 메시지를 출력하세요: echo '{"message": "Blocked: reason"}'

무한 루프

증상: Claude가 같은 작업을 계속 다시 시도하거나, 컴퓨터가 의심스러울 정도로 뜨거워집니다.

해결 방법:

• Stop 훅이 작업을 트리거하는 경우, Stop 훅이 파일을 쓰거나 Claude의 응답을 유발하는 명령을 실행하면 루프가 발생합니다. Stop 훅은 로깅, 알림, 정리 같은 수동적인 작업만 수행해야 합니다.
• PostToolUse 훅이 편집을 유발하는 경우, 파일을 수정하는 PostToolUse 훅은 또 다른 PostToolUse 이벤트를 트리거합니다. 구체적인 매처나 if 필드로 이를 방지하세요.

성능 문제

증상: Claude의 시작이나 도구 실행 속도가 눈에 띄게 느려진다.

해결 방법:

• SessionStart 훅이 너무 많음, 각 훅은 시작 시 동기적으로 실행된다. 가볍게 유지하라(각각 1초 이내).
• 핫 패스에 무거운 스크립트 사용, PreToolUse와 PostToolUse 훅은 빈번하게 실행된다. 스크립트에서 네트워크 요청이나 무거운 연산을 수행한다면 timeout 필드(밀리초 단위)를 추가하고, HTTP 훅으로 전환할지 검토하라.
• 캐싱 미적용, 동일한 항목을 반복적으로 확인하는 경우(예: "이 브랜치가 보호 브랜치인가?"), 훅 호출마다 Git 명령을 실행하는 대신 결과를 임시 파일에 캐시하라.

자주 묻는 질문

Claude Code 훅이란 무엇이며 어떻게 작동하나요?

Claude Code 훅은 Claude Code 세션 중 특정 라이프사이클 이벤트에서 실행되는 사용자 정의 자동화 스크립트입니다. settings.json에서 매처 패턴과 핸들러(셸 명령어, HTTP 엔드포인트, 프롬프트 또는 에이전트)를 지정하여 구성합니다. 일치하는 이벤트가 발생하면 훅이 자동으로 실행되며 종료 코드를 사용해 결과를 제어합니다.

Claude Code의 settings.json에서 훅(hook)을 어떻게 설정하나요?

"hooks" 객체를 세 가지 설정 위치 중 하나에 추가하세요: ~/.claude/settings.json(사용자 전역), .claude/settings.json(프로젝트 공유), 또는 .claude/settings.local.json(프로젝트 개인용). 각 이벤트 유형은 matcher, 선택적 if 필드, 그리고 type과 command 또는 url을 가진 핸들러 객체를 포함하는 hooks 배열로 매핑되는 훅 정의 배열에 대응합니다.

PreToolUse 훅과 PostToolUse 훅의 차이점은 무엇인가요?

PreToolUse는 도구가 실행되기 전에 발생하며, 종료 코드 2로 실행을 차단할 수 있는 권한을 제공합니다. PostToolUse는 실행이 완료된 후에 발생하며, 포맷팅, 테스트, 로깅에 유용합니다. PreToolUse는 사전 방지와 게이트용입니다. PostToolUse는 검증과 정리용입니다. 둘 다 stdin을 통해 도구 이름과 입력을 JSON으로 받습니다.

Claude Code 훅으로 위험한 명령어를 차단할 수 있나요?

네. PreToolUse 훅에서 종료 코드 2를 반환하면 모든 도구 실행을 차단할 수 있습니다. 민감한 파일에 대한 쓰기를 보호하고, rm -rf나 git push main 같은 위험한 패턴에 해당하는 셸 명령어를 차단하며, 프로덕션 데이터베이스에 대한 접근을 방지할 수 있습니다. 차단 메시지는 피드백으로 Claude에 전달되므로, Claude가 접근 방식을 조정할 수 있습니다.

Claude Code에서 사용할 수 있는 훅 이벤트는 무엇인가요?

Claude Code는 15개 이상의 이벤트를 제공합니다. 도구 실행을 위한 PreToolUse와 PostToolUse, 알림을 위한 Notification, 세션 종료를 위한 Stop, 초기화를 위한 SessionStart, 입력 필터링을 위한 UserPromptSubmit, 컨텍스트 관리를 위한 PreCompact와 PostCompact, 그리고 ConfigChange, FileChanged, TaskCreated, PermissionDenied 같은 최신 이벤트가 있습니다. 위 훅 이벤트 섹션의 전체 참조 표를 확인하세요.

훅은 MCP 도구 및 스킬과 어떻게 다른가요?

훅은 결정적입니다. Claude의 판단과 관계없이 일치하는 이벤트에 항상 실행됩니다. MCP 도구는 Claude의 기능을 확장하지만(데이터베이스 접근, API 호출) 언제 사용할지는 Claude가 선택합니다. 스킬은 슬래시 명령으로 호출되는 재사용 가능한 명령어 패키지입니다. CLAUDE.md는 행동 지침을 제공합니다. 매번 반드시 실행되어야 하는 작업에는 훅을, Claude에게 새로운 능력이 필요할 때는 MCP를 사용하세요.

Claude Code 훅은 헤드리스 모드에서도 작동하나요?

네, 단 몇 가지 주의사항이 있습니다. 헤드리스 모드(claude -p)에서도 훅은 정상적으로 실행되지만, macOS 알림과 같은 데스크톱 전용 훅에는 대체 수단이 필요합니다. 중요한 점은 종료 코드 2로 종료되는 PreToolUse 훅은 --resume을 통해 사람의 승인을 위해 헤드리스 세션을 일시 중지할 수 있다는 것입니다. 이를 통해 특정 작업에 수동 승인이 필요한 휴먼 인 더 루프(Human-in-the-loop) CI/CD 파이프라인을 구현할 수 있습니다.

후크는 몇 개부터 너무 많을까? 후크가 Claude Code를 느리게 하나?

엄격한 상한선은 없지만, 각 동기 후크는 지연 시간을 추가합니다. SessionStart 후크는 시작 시 실행되므로 빠르게 유지하세요(각각 1초 이내). PreToolUse와 PostToolUse 후크는 조건에 맞는 도구 호출마다 실행되므로, 여기서 무거운 스크립트를 쓰면 지연이 빠르게 누적됩니다. 전체 후크 수를 10~15개 이하로 유지하고, if 필드로 범위를 좁히며, timeout 값을 추가해 스크립트 폭주를 방지하는 것을 권장합니다.

Prettier나 Black으로 코드를 자동 포맷하는 데 훅을 사용할 수 있나요?

네, 가장 인기 있는 훅 활용 사례입니다. Write|Edit과 매칭되는 PostToolUse 훅을 만들고, stdin JSON에서 파일 경로를 추출한 뒤, 파일 확장자에 따라 적절한 포매터를 실행하면 됩니다. TypeScript, JavaScript, Python 파일을 처리하는 바로 복사해 사용할 수 있는 완성된 설정은 프로덕션 예시 섹션의 첫 번째 예시를 참고하세요.

Claude Code 훅은 안전한가요? 보안 위험은 무엇인가요?

훅은 사용자의 전체 권한으로 실행되며, 샌드박스가 없습니다. 악의적인 훅은 SSH 키를 읽거나, 파일을 삭제하거나, 데이터를 유출할 수 있습니다. 신뢰할 수 있는 출처의 훅만 사용하고, 공유된 .claude/settings.json은 프로젝트에 적용하기 전에 검토하세요. 공유해서는 안 되는 개인용 훅에는 .claude/settings.local.json을 사용하세요. 더 폭넓은 AI 안전 패턴은 LLM 가드레일 가이드를 참고하세요.