Hooks

• Claude Code의 라이프사이클 특정 시점에서 자동으로 실행되는 사용자 정의 셸 명령 또는 LLM 프롬프트
• PreToolUse, PostToolUse, Stop 등 이벤트에 반응하여 검증, 차단, 컨텍스트 주입 수행
• 3가지 핸들러 타입 지원: command (셸), prompt (LLM 단일턴), agent (도구 사용 가능한 subagent)

해당 개념이 필요한 이유

• 위험한 명령 자동 차단: rm -rf 같은 파괴적 명령을 사전에 차단
• 코드 품질 자동 검증: 파일 수정 후 자동으로 린팅/포매팅 실행
• 워크플로우 자동화: 세션 시작 시 환경 설정, 종료 시 정리 작업 등

AS-IS (Hooks 없이)

sequenceDiagram
    autonumber
    actor User
    participant Claude
    participant System as 파일 시스템

    User->>Claude: "코드 수정해줘"
    Claude->>System: Write (파일 저장)
    Note over System: ⚠️ 린팅 안 됨<br/>포매팅 안 됨

    Claude->>System: Bash "rm -rf /"
    Note over System: ⚠️ 위험한 명령<br/>사전 검증 없음

    Note over User: 매번 수동으로<br/>"린트 돌려줘"<br/>"위험한 거 하지마" 요청

TO-BE (Hooks 사용)

sequenceDiagram
    autonumber
    actor User
    participant Claude
    participant Hook as Hook Handler
    participant System as 파일 시스템

    User->>Claude: "코드 수정해줘"
    Claude->>Hook: PreToolUse (Bash "rm -rf")
    Hook-->>Claude: ❌ exit 2 "차단됨"
    Note over Claude: 위험한 명령 자동 차단

    Claude->>System: Write (파일 저장)
    System-->>Hook: PostToolUse (Write)
    Hook->>System: 자동 린팅/포매팅 실행
    Hook-->>Claude: ✅ "린트 통과"

Hook 이벤트 전체 목록

이벤트	발생 시점	차단 가능
SessionStart	세션 시작/재개 시	No
UserPromptSubmit	사용자 프롬프트 제출 후, Claude 처리 전	Yes
PreToolUse	도구 호출 실행 전	Yes
PermissionRequest	퍼미션 다이얼로그 표시 시	Yes
PostToolUse	도구 호출 성공 후	No (피드백만)
PostToolUseFailure	도구 호출 실패 후	No (피드백만)
Notification	알림 발생 시	No
SubagentStart	Claude Code Subagent 생성 시	No
SubagentStop	Claude Code Subagent 완료 시	Yes
Stop	Claude 응답 완료 시	Yes
TaskCompleted	태스크 완료 표시 시	Yes
PreCompact	컨텍스트 압축 전	No
SessionEnd	세션 종료 시	No

설정 구조 (3단계 중첩)

{
  "hooks": {
    "PostToolUse": [           // 1. Hook 이벤트 선택
      {
        "matcher": "Edit|Write",  // 2. Matcher로 필터링 (regex)
        "hooks": [                // 3. 핸들러 정의
          {
            "type": "command",
            "command": "/path/to/lint.sh"
          }
        ]
      }
    ]
  }
}

3가지 핸들러 타입

타입	type	설명	기본 timeout
Command	"command"	셸 명령 실행. stdin으로 JSON 입력, exit code로 결과	600초
Prompt	"prompt"	LLM에 프롬프트 전송, {ok: true/false} 응답	30초
Agent	"agent"	Read/Grep/Glob 도구 사용 가능한 subagent 생성	60초

Exit Code 규칙

Exit Code	의미	동작
0	성공	stdout의 JSON 파싱, 도구 호출 허용
2	차단	stderr를 Claude에 에러로 전달, 도구 호출 차단
기타	비차단 에러	stderr를 verbose 모드에 표시, 실행 계속

설정 파일 위치

위치	경로	적용 범위
Personal	~/.claude/settings.json	내 모든 프로젝트
Project	.claude/settings.json	해당 프로젝트 (공유 가능)
Local	.claude/settings.local.json	해당 프로젝트 (gitignore)
Plugin	<plugin>/hooks/hooks.json	플러그인 활성화된 곳
Claude Code Skills / Claude Code Subagent	frontmatter에 정의	해당 컴포넌트 활성 시

PreToolUse 실전 예시: 위험 명령 차단

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
 
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "파괴적 명령 차단됨"
    }
  }'
else
  exit 0
fi

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/block-rm.sh"
      }]
    }]
  }
}

PostToolUse 실전 예시: 자동 포매팅

#!/bin/bash
# .claude/hooks/auto-format.sh
 
# stdin에서 JSON 입력 읽기
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# 파일 확장자에 따라 포매터 실행
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    ;;
  *.py)
    black "$FILE_PATH" 2>/dev/null
    ;;
  *.dart)
    dart format "$FILE_PATH" 2>/dev/null
    ;;
esac
 
exit 0

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/block-rm.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/auto-format.sh"
      }]
    }]
  }
}

Stop Hook 동작 원리

• LLM이 “작업 완료”로 판단하고 종료하려는 순간 Claude Code 시스템이 자동 트리거
• 개발자가 호출하는 것이 아니라, 이벤트 기반 자동 감시
• approve → 정상 종료, block → 종료 거부 + reason을 Claude에 전달하여 작업 계속

sequenceDiagram
    autonumber
    participant Claude
    participant System as Claude Code Runtime
    participant Hook as Stop Hook Handler
    participant State as State File

    Claude->>System: "작업 완료, 종료합니다"
    System->>Hook: Stop 이벤트 자동 트리거
    Hook->>State: .ai-dev-cycle-state.json 읽기
    State-->>Hook: currentPhase: 2

    alt currentPhase < 5 (미완료)
        Hook-->>System: ❌ block + "Phase 2 미완료"
        System-->>Claude: "Phase 3-5를 완료하세요"
        Note over Claude: 종료 거부됨<br/>남은 Phase 계속 수행
    else currentPhase >= 5 (완료)
        Hook-->>System: ✅ approve
        Note over Claude: 정상 종료
    end

Decision Output 구조

필드	타입	필수	설명
decision	"approve" | "block"	Yes	종료 허용 또는 거부
reason	string	No	거부 사유 (Claude에 전달)
systemMessage	string	No	추가 컨텍스트 (Claude에 시스템 메시지로 전달)

{
  "decision": "block",
  "reason": "Phase 3 (Result Report) not completed",
  "systemMessage": "currentPhase is 2. Complete Phase 3-5 before stopping."
}

Stop Hook 실전 예시: 워크플로우 Phase 완료 검증

#!/bin/bash
# ~/.claude/scripts/ai-dev-cycle-guard.sh
# ai-dev-cycle 워크플로우의 Phase 완료를 검증하는 Stop Hook
 
STATE_FILE=".claude/.ai-dev-cycle-state.json"
 
# state file이 없으면 ai-dev-cycle이 아님 → 통과
if [ ! -f "$STATE_FILE" ]; then
  exit 0
fi
 
CURRENT_PHASE=$(jq -r '.currentPhase // 0' "$STATE_FILE")
 
if [ "$CURRENT_PHASE" -lt 5 ]; then
  jq -n \
    --arg phase "$CURRENT_PHASE" \
    '{
      "decision": "block",
      "reason": ("Phase " + $phase + " 진행 중. Phase 5(Retrospective)까지 완료 후 종료하세요."),
      "systemMessage": ("currentPhase: " + $phase + ". Complete remaining phases before stopping.")
    }'
  exit 0
fi
 
# Phase 5 완료 → 종료 허용
exit 0

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/scripts/ai-dev-cycle-guard.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Hook의 한계 — 스텝 강제의 현실적 범위

Hook이 보장할 수 있는 것 vs 없는 것

구분	보장 가능	보장 불가
Phase 단위	Phase 5 완료 전 종료 차단	Phase 내부 Step 생략 감지
도구 단위	특정 도구 호출 전/후 검증	Step 순서 강제
종료 시점	조건 미충족 시 block	Step을 건너뛰고 Phase만 진행하는 것

flowchart LR
    subgraph "Hook이 감지 가능"
        A["Phase 2 → Phase 5<br/>통째로 생략"] -->|Stop Hook| B["❌ block"]
    end

    subgraph "Hook이 감지 불가"
        C["Step 1 → Step 3 생략<br/>→ Step 7 직행"] -->|"?"| D["감지 못함"]
    end

LangGraph와의 구조적 차이

	LangGraph	Claude Code Hook
제어 주체	코드 (State Machine)	LLM (자율 판단)
스텝 강제	add_conditional_edges로 구조적 보장	프롬프트로 지시 (우회 가능)
Evaluator 루프	조건 불충족 시 이전 노드로 자동 되돌림	불가
검증 시점	매 노드 전환마다	Stop / PreToolUse 등 이벤트만
유연성	낮음 (사전 정의 필수)	높음 (자연어 대응)

flowchart TB
    subgraph "LangGraph — 코드가 순서 강제"
        L1[Step 1] -->|"conditional_edge"| L2[Step 2]
        L2 -->|"conditional_edge"| L3[Evaluator]
        L3 -->|FAIL| L2
        L3 -->|PASS| L4[Step 3]
    end

    subgraph "Claude Code — LLM이 자율 판단"
        C1[Step 1] -.->|"프롬프트 지시"| C2[Step 2]
        C2 -.->|"생략 가능"| C3[Step 3]
        C3 -.->|"Stop 시도"| C4{Stop Hook}
        C4 -->|block| C3
        C4 -->|approve| C5[종료]
    end

베스트 프랙티스: 3계층 방어

flowchart TD
    A["1계층: 프롬프트 강화<br/>(Critical Rules)"] -->|"대부분 작동<br/>LLM 선의 의존"| B["2계층: State File 추적<br/>(Step 단위 기록)"]
    B -->|"기록 자체를<br/>생략할 수 있음"| C["3계층: Stop Hook<br/>(Phase 완료 검증)"]
    C -->|"Phase 통째로<br/>생략 방지"| D["종료 허용"]

    style A fill:#e8f5e9
    style B fill:#fff3e0
    style C fill:#ffebee

계층	방법	강제력	방어 범위
1계층	프롬프트 강화 (Critical Rules)	낮음	Step 단위 (LLM이 준수할 때)
2계층	State File (Step 기록)	중간	Step 단위 (기록 시)
3계층	Stop Hook (command)	높음	Phase 단위 (우회 불가)

• 100% 보장은 불가능 — Claude Code는 LLM이 오케스트레이터이므로 코드 레벨 강제가 없음
• 3계층 조합이 현실적 최선 — Phase 생략은 Stop Hook이, Step 생략은 프롬프트가 방어

참고 문서

• Hooks 공식 레퍼런스
• Hooks 가이드 (퀵스타트)