Claude Code Hooks 8가지 프로덕션 패턴: 자동화 & 보안 가드 (2026)

Claude Code hooks는 도구 호출과 라이프사이클 이벤트를 가로채 셸 스크립트를 실행할 수 있게 해주는 메커니즘입니다. 6가지 이벤트(PreToolUse, PostToolUse, SessionStart, Stop, UserPromptSubmit, Notification)가 예측 가능한 시점에 발생하며, exit code 0은 계속, exit code 2는 차단을 의미합니다 (2026 기준). 이 가이드는 공식 문서의 bash 포맷터 예시를 넘어, 실전 프로덕션에서 검증된 8가지 패턴을 다룹니다 — 위험 명령 차단, 자동 포맷, 프롬프트 재작성, 비용 가드, 테스트 트리거, git stash 안전망, 풍부한 세션 부트스트랩까지.

6가지 Hook 이벤트 종류

Hooks는 ~/.claude/settings.json(사용자) 또는 .claude/settings.json(프로젝트)에 정의합니다. 각 이벤트는 matcher(도구 이름 패턴)와 실행할 명령 목록을 받습니다.

Hook은 JSON을 stdin으로 받습니다 (도구 이름, 인자, 작업 디렉토리, 트랜스크립트 경로). stdout은 Pre/Post/SessionStart에서 추가 컨텍스트로 사용됩니다. PreToolUse에서 stderr에 출력하고 exit 2로 종료하면 호출이 멈춥니다 — 이것이 보안 게이트입니다.

패턴 1: 위험 명령 차단

가장 흔한 시나리오: Claude가 rm -rf /, git push --force origin main, 운영 DB에 DROP TABLE 같은 명령을 실행하지 못하게 막기.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat); cmd=$(echo \"$input\" | jq -r '.tool_input.command'); if echo \"$cmd\" | grep -qE 'rm -rf /|push --force.*main|DROP TABLE.*prod'; then echo 'Blocked dangerous command' >&2; exit 2; fi; exit 0"
          }
        ]
      }
    ]
  }
}

이 hook은 모든 Bash 호출 전에 명령 문자열을 검사합니다. 패턴이 매치되면 exit 2로 차단하고 stderr 메시지가 Claude에 반환됩니다.

패턴 2: 자동 포맷 (Prettier, Black)

PostToolUse hook으로 Claude가 파일을 작성한 직후 포맷터를 자동 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat); path=$(echo \"$input\" | jq -r '.tool_input.file_path'); case \"$path\" in *.ts|*.tsx|*.js|*.jsx) bunx prettier --write \"$path\";; *.py) black \"$path\";; esac"
          }
        ]
      }
    ]
  }
}

Claude가 작성한 코드는 자동으로 팀 스타일에 맞춰집니다. 사후 수정 없이 일관된 코드 베이스 유지.

패턴 3: 프롬프트 재작성 (시그니처 추가)

UserPromptSubmit hook으로 사용자 프롬프트에 자동으로 컨텍스트를 추가합니다.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat); prompt=$(echo \"$input\" | jq -r '.prompt'); date=$(date '+%Y-%m-%d'); echo \"오늘 날짜: $date\\n\\n$prompt\""
          }
        ]
      }
    ]
  }
}

매 프롬프트에 오늘 날짜가 자동으로 추가됩니다. Claude가 시점에 맞는 응답을 제공할 수 있게 됩니다.

패턴 4: 비용 가드 (예산 한도)

세션 토큰 사용량이 일정 한도를 넘으면 추가 호출을 차단합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "tokens=$(jq -r '.session_tokens_used // 0' < ~/.claude/session-state.json); if [ \"$tokens\" -gt 500000 ]; then echo \"Token budget exceeded: $tokens/500K\" >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

세션당 50만 토큰 한도. 비용 폭발 방지. 자세한 비용 최적화는 Claude API 비용 완전 가이드를 참고하세요.

패턴 5: 테스트 자동 실행

PostToolUse hook으로 코드 수정 후 자동으로 관련 테스트를 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat); path=$(echo \"$input\" | jq -r '.tool_input.file_path'); if echo \"$path\" | grep -qE 'src/'; then test_path=$(echo \"$path\" | sed 's|src/|tests/|;s|\\.ts$|.test.ts|'); [ -f \"$test_path\" ] && bun test \"$test_path\" 2>&1 | tail -5; fi"
          }
        ]
      }
    ]
  }
}

소스 파일 수정 시 대응하는 테스트 파일이 있으면 자동 실행. 결과는 Claude의 다음 응답에 컨텍스트로 들어갑니다.

패턴 6: Git Stash 안전망

Claude가 큰 변경을 시도하기 전에 자동으로 stash로 백업합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat); cmd=$(echo \"$input\" | jq -r '.tool_input.command'); if echo \"$cmd\" | grep -qE 'rm -|git reset --hard|git checkout \\.'; then git stash push -m \"auto-stash before $(echo \"$cmd\" | head -c 30)\"; fi"
          }
        ]
      }
    ]
  }
}

위험할 수 있는 명령 직전 stash 생성. 잘못된 경우 git stash pop으로 복구 가능.

패턴 7: 세션 부트스트랩

SessionStart hook으로 세션 시작 시 자동 컨텍스트 주입.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"# 현재 git 상태\"; git status --short; echo \"\\n# 최근 커밋 3개\"; git log --oneline -3; echo \"\\n# TODO 목록\"; [ -f TODOS.md ] && head -20 TODOS.md"
          }
        ]
      }
    ]
  }
}

세션 시작 시 Claude는 git 상태, 최근 커밋, TODO를 자동으로 알게 됩니다. "현재 상태 알려줘" 같은 질문 불필요.

패턴 8: 도구 사용 로그

PostToolUse hook으로 모든 도구 호출을 파일에 기록합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat); tool=$(echo \"$input\" | jq -r '.tool_name'); ts=$(date -Iseconds); echo \"[$ts] $tool\" >> ~/.claude/tool-log.txt"
          }
        ]
      }
    ]
  }
}

세션이 끝나면 ~/.claude/tool-log.txt에 모든 도구 호출 기록. 디버깅과 패턴 분석에 유용.

Hook 디버깅 팁

1. stderr 사용: hook 디버깅 시 stdout 대신 stderr에 출력. stdout은 Claude 컨텍스트에 들어가 혼란을 일으킵니다.
2. JSON 입력 확인: command: cat > /tmp/hook-input.json 로 입력을 파일로 저장 후 검사.
3. exit 코드: 항상 명시적으로 exit 0 또는 exit 2 사용. 묵시적 종료는 예측 불가.
4. 타임아웃: hook은 30초 이내 종료. 긴 작업은 백그라운드로.

자세한 Claude Code 활용 패턴은 Claude Code 완전 가이드를 참고하세요.

Frequently Asked Questions

Hook은 어디에 정의하나요?

프로젝트별 hook은 .claude/settings.json, 사용자 전역 hook은 ~/.claude/settings.json에 정의합니다. 두 파일 모두 적용되며, 같은 이벤트에 대한 정의는 병합됩니다.

Hook이 실패하면 어떻게 되나요?

PreToolUse에서 exit 2를 반환하면 도구 호출이 차단됩니다. PostToolUse에서 실패하면 출력만 무시되고 도구 자체는 이미 실행 완료 상태입니다. 항상 명시적 exit 코드를 사용하세요.

Hook의 성능 영향은?

각 hook은 30초 타임아웃이 있지만, 실제로는 100-500ms 내에 끝나는 것이 권장됩니다. 무거운 작업(테스트 실행, 빌드)은 백그라운드로 트리거하세요.

여러 hook이 같은 이벤트에 있으면 순서는?

settings.json의 배열 순서대로 실행됩니다. 같은 matcher의 hooks는 순차 실행되며, 하나라도 exit 2를 반환하면 후속 hook은 실행되지 않고 전체가 차단됩니다.

Hook으로 Claude의 응답을 수정할 수 있나요?

UserPromptSubmit hook의 stdout은 사용자 프롬프트를 대체/보강합니다. Stop hook은 응답 후 발생하므로 응답 자체를 수정할 수는 없지만, 다음 응답을 위한 컨텍스트는 추가할 수 있습니다.

Claude Code 자동화 마스터하기

P1 Power Prompts 300 ($29) — Claude Code hooks 활용, 보안 가드, 자동화 패턴을 포함한 300개의 검증된 프롬프트 컬렉션. 솔로 개발자 기준 월 평균 50시간 절약.