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	Subagents 생성 시	No
SubagentStop	Subagents 완료 시	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 / Subagents	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"
      }]
    }]
  }
}

참고 문서

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