Hooks System — From Advisory to Guaranteed

Hooks 시스템 — 규칙에서 보장으로

CLAUDE.md 규칙은 확률적이다. Hooks는 결정론적이다. 비용이 높은 규칙은 반드시 Hook으로 승격해야 한다.

🍌 NANO BANANA CHEATSHEET · CH 07

Overview

개관

2026년 Claude Code 마스터들이 한결같이 강조하는 것: 규칙이 3번 이상 무시됐으면 Hook으로 바꿀 때다.

규칙(CLAUDE.md)과 Hook의 근본 차이:

규칙: "하드코딩된 API 키를 사용하지 마세요" → Claude가 '이번엔 임시니까' 하고 무시할 수 있다
Hook: exit 2를 반환하는 PreToolUse → 시스템이 블로킹한다. Claude가 어떻게 생각하든 실행되지 않는다

Hook은 Claude를 위한 것이 아니다. 시스템을 위한 것이다.

🎯 Learning Goals

PreToolUse와 PostToolUse의 차이와 사용 시나리오를 이해한다
exit code 2로 Claude의 작업을 블로킹하는 Hook을 작성할 수 있다
파일 수정 후 자동으로 테스트를 실행하는 PostToolUse Hook을 설정한다
rm -rf, git push --force 같은 위험 명령어를 차단하는 안전 Hook을 구성한다

Sections

본문

PreToolUse — 실행 전 블로킹

Hook이 exit code 2를 반환하면 Claude는 해당 도구 호출을 실행하지 못한다. stdout의 내용이 Claude에게 피드백으로 전달된다.

가장 강력한 사용 사례:

위험 명령어 차단: rm -rf, git push --force
프로덕션 환경 보호: 특정 경로의 파일은 직접 수정 금지
하드코딩 탐지: 코드에 API 키 패턴이 감지되면 차단

PostToolUse — 실행 후 자동화

파일 수정 후 자동으로 관련 테스트를 실행하는 가장 강력한 개발 패턴.

Write나 Edit 도구가 실행된 후 → 수정된 파일의 관련 테스트를 자동 실행 → 결과를 Claude 컨텍스트에 피드백 → Claude가 실패한 테스트를 즉시 수정.

이 루프가 자동화되면 TDD가 힘들지 않아진다.

세 가지 필수 안전 Hook

모든 프로젝트에 기본으로 설정해야 할 3개의 Hook:

위험 명령어 차단: rm -rf, dd, mkfs 패턴 감지 시 exit 2 2.

하드코딩 시크릿 탐지: sk-, pk_, AKIA, ghp_ 패턴이 Write되면 경고 3.

테스트 자동 실행: .ts/.tsx 파일 수정 시 npm test --related 자동 실행

💡 Analogy · 비유

신호등 vs 교통 표지판

교통 표지판('속도 제한 60')은 규칙이다. 지키는 사람도 있고 무시하는 사람도 있다. 신호등은 Hook이다. 빨간 불이면 어떤 운전자도 진행하지 못한다 — 시스템이 강제한다. CLAUDE.md는 표지판이고 Hook은 신호등이다.

settings.json Hook 설정 — 필수 안전 패턴 3종

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '\n# 위험 명령어 차단\nif echo "$CLAUDE_TOOL_INPUT" | grep -qE \"rm -rf|dd if=|mkfs|> /dev/\"; then\n  echo \"[HOOK BLOCKED] 위험 명령어 감지. 확인 후 수동으로 실행하세요.\"\n  exit 2\nfi\n'"
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '\n# 하드코딩 시크릿 탐지\nif echo "$CLAUDE_TOOL_INPUT" | grep -qE \"(sk-|pk_|AKIA|ghp_)[a-zA-Z0-9]{20,}\"; then\n  echo \"[SECURITY] 하드코딩된 API 키 감지. .env 파일로 이동하세요.\"\n  exit 2\nfi\n'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '\n# TypeScript 파일 수정 시 관련 테스트 자동 실행\nif echo "$CLAUDE_TOOL_RESULT_FILE" | grep -qE \"\\.tsx?$\"; then\n  npm test -- --related "$CLAUDE_TOOL_RESULT_FILE" --passWithNoTests 2>&1 | tail -20\nfi\n'"
          }
        ]
      }
    ]
  }
}

PreToolUse Hook에서 exit 2 반환 시 Claude의 Bash 실행이 차단된다. PostToolUse Hook은 파일 수정 후 자동으로 관련 테스트를 실행하고 결과를 Claude에게 피드백한다.

🏭 현업에서의 평가

Hooks 설정을 보면 이 팀이 Claude Code를 얼마나 진지하게 쓰는지 알 수 있다. Hooks가 없다면 아직 규칙에만 의존하는 단계다. PreToolUse 블로킹 Hook이 있고 그 이유를 설명할 수 있다면 그 팀은 진지한 사용자다.

✅ 시니어가 보는 것

위험 명령어를 차단하는 PreToolUse Hook이 있는가
하드코딩 시크릿 탐지 Hook이 설정되어 있는가
PostToolUse로 자동 테스트 실행이 구성되어 있는가
Hook 실패 메시지가 명확한 원인과 해결 방법을 안내하는가

Key Takeaways

핵심 정리

exit 2 = 블로킹, exit 1 = 경고

이 차이가 Hook의 핵심이다. 강제하려면 반드시 exit 2를 사용한다.

규칙 3회 무시 → Hook 승격 신호

CLAUDE.md 규칙이 계속 무시된다면 Hook으로 바꿀 때다.

PostToolUse 자동 테스트가 가장 강력

코드 수정 즉시 테스트가 돌아가는 루프가 개발 품질을 극적으로 높인다.

← Ch06 · CLAUDE.md Mastery — Context Engineering Ch08 · Multi-Agent Workflows & Git Worktrees →