간략 요약: Claude Code 훅은 AI 코딩 세션의 특정 생명 주기 시점에 실행되는 자동화 스크립트로, 개발자가 사용자 정의 명령을 실행하고, 작업을 검증하며, 코드를 포맷하고, 알림을 보내고, 프로젝트 규칙을 적용할 수 있게 합니다. 이 훅은 SessionStart, PreToolUse, PostToolUse와 같은 이벤트를 통해 Claude의 워크플로와 통합되며, 구성 가능한 타임아웃 및 종료 코드 동작과 함께 명령 기반, HTTP 기반, 프롬프트 기반 실행 패턴을 지원합니다.

Claude Code의 훅 시스템은 AI 코딩 어시스턴트를 유용한 도구에서 완전 자동화된 개발 환경으로 변화시킵니다. 대부분의 개발자는 훅을 통해 가능한 제어 수준을 인지하지 못합니다.

하지만 중요한 점은 훅이 단순히 파일 편집 후 스크립트를 실행하는 것 이상이라는 것입니다. Claude의 전체 의사 결정 과정에 걸쳐 가로채기 지점을 제공합니다. 명령을 실행하기 전. 도구 호출이 실패한 후. 권한이 필요한 경우. 사용자 프롬프트를 처리하기 전에도 가능합니다.

이 가이드에서는 공식 문서에서 제공하는 모든 내용과 함께, 커뮤니티 토론을 통해 프로덕션 환경에서 실제로 작동하는 실용적인 패턴을 다룹니다.

Claude Code 훅이 실제로 하는 일

공식 Claude Code 문서에 따르면, 훅은 Claude Code의 생명 주기 특정 시점에 실행되는 사용자 정의 쉘 명령, HTTP 엔드포인트 또는 프롬프트 삽입입니다. 표준 입력을 통해 구조화된 JSON 입력을 받고 종료 코드 또는 HTTP 응답을 통해 워크플로를 제어합니다.

자동화는 대부분의 가이드에서 제시하는 것보다 더 깊이 들어갑니다. 훅은 도구 실행을 완전히 차단하거나, Claude의 추론에 추가적인 컨텍스트를 삽입하거나, 외부 서비스를 트리거하거나, Claude가 준수해야 하는 유효성 검사 규칙을 강제할 수 있습니다.

세 가지 핵심 훅 유형이 있습니다:

명령 훅: stdout, stderr 및 종료 코드를 통해 통신하는 쉘 스크립트
HTTP 훅: POST 요청을 받고 JSON 응답을 반환하는 원격 엔드포인트
프롬프트 훅: 특정 이벤트에서 Claude의 컨텍스트에 삽입되는 동적 지침

각 유형은 다른 자동화 패턴에 사용됩니다. 명령 훅은 로컬 유효성 검사 및 포맷팅을 처리합니다. HTTP 훅은 외부 서비스 및 데이터베이스와 통합됩니다. 프롬프트 훅은 외부 프로세스 없이 Claude의 동작을 수정합니다.

훅 생명 주기 및 이벤트 시스템

공식 문서는 Claude Code 실행 흐름 중에 발생하는 여러 훅 이벤트(SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification 등)를 정의합니다. 각 이벤트가 언제 발생하는지 이해하는 것이 가능한 자동화 수준을 결정합니다.

이벤트	실행 시점	차단 가능 여부
SessionStart	세션이 시작되거나 재개될 때	아니요
UserPromptSubmit	Claude가 처리하기 전에 프롬프트를 제출할 때	예
PreToolUse	도구 호출이 실행되기 전	예
PermissionRequest	권한 대화 상자가 나타날 때	예
PostToolUse	도구 호출이 성공한 후	아니요
PostToolUseFailure	도구 호출이 실패한 후	아니요
Notification	Claude Code가 알림을 보낼 때	아니요
SubmitMessage	Claude가 사용자에게 메시지를 제출할 때	아니요
ContextCompaction	컨텍스트 창이 제한에 가까워질 때	아니요

차단 기능이 가장 중요합니다. PreToolUse 훅은 위험한 작업을 실행 전에 방지할 수 있습니다. 종료 코드 1은 작업을 차단합니다. 종료 코드 0은 작업을 허용합니다. 종료 코드 2는 Claude에게 재고를 요청하도록 합니다.

하지만 잠시만요. PostToolUse 훅은 도구가 이미 실행되었기 때문에 작업을 되돌릴 수 없습니다. 이 제한은 유효성 검사 로직이 어떻게 구성되는지를 결정합니다. 중요한 검사는 PreToolUse에 있어야 합니다. 정리 및 포맷팅은 PostToolUse에 있어야 합니다.

Claude Code 설정 시 AI 도구 혜택 찾아보기

Claude Code 훅을 사용 중이라면 워크플로 주변의 다른 AI 도구도 선택하고 있을 수 있습니다. Get AI Perks는 AI 및 클라우드 도구에 대한 스타트업 크레딧 및 소프트웨어 할인을 한 곳에 모아 제공합니다. 이 플랫폼에는 200개 이상의 제안이 포함되어 있으며, 각 제안에 대한 혜택 조건 및 청구 가이드가 있습니다.

Claude 또는 기타 AI 도구 혜택 찾기?

Get AI Perks를 확인하여 다음을 수행하세요:

Claude 및 기타 AI 도구 제안 찾아보기
신청 전 혜택 조건 비교
도구 스택 전반에 걸쳐 스타트업 할인 찾기

👉 현재 AI 소프트웨어 혜택을 둘러보려면 Get AI Perks를 방문하세요.

구성 및 파일 구조

훅은 프로젝트 내의 .claude/settings.json 파일에 정의됩니다. 구성 스키마는 전역 훅과 훅이 언제 실행되는지를 필터링하는 도구별 매처를 지원합니다.

기본 명령 훅 구조:

{
"hooks": [
{
"event": "PostToolUse",
"command": "prettier --write",
"args": ["${file}"]
}
]
}

${file} 변수는 도구 입력에서 실제 파일 경로로 확장됩니다. 공식 문서에 따르면, 훅은 명령 및 args 필드에서 이러한 변수 확장을 지원합니다.

훅 위치 계층 구조

Claude Code는 훅 정의에 대해 여러 위치를 확인하며, 명확한 우선 순위 순서를 따릅니다:

프로젝트 수준: 현재 작업 공간의 .claude/settings.json
사용자 수준: 모든 세션을 위한 ~/.claude/settings.json
플러그인 제공: 설치된 플러그인과 함께 번들링된 훅

프로젝트 훅은 동일한 이벤트에 대해 사용자 훅을 재정의합니다. 이를 통해 전역 알림 핸들러를 유지하면서 프로젝트별 포맷팅 규칙을 적용할 수 있습니다.

선택적 실행을 위한 매처 패턴

매처 시스템은 훅을 특정 도구 또는 조건으로 필터링합니다. 매처가 없으면 훅은 이벤트가 발생할 때마다 실행됩니다.

{
"hooks": [
{
"event": "PreToolUse",
"matcher": {
"toolName": "edit_file",
"pathPattern": "src/**/*.ts"
},
"command": "./scripts/validate-typescript.sh"
}
]
}

pathPattern 필드는 glob 구문을 허용합니다. toolName 필드는 edit_file, execute_command, read_file, create_directory와 같은 Claude의 내장 도구와 일치합니다.

커뮤니티 토론에 따르면 매처 조합은 AND 논리로 작동합니다. 훅이 실행되려면 지정된 모든 매처가 일치해야 합니다.

명령 훅: 쉘 스크립트 통합

명령 훅은 구조화된 JSON 입력을 사용하여 쉘 명령 또는 스크립트를 실행합니다. 로컬 자동화를 위한 가장 일반적인 훅 유형입니다.

공식 문서에 따르면 명령 훅은 다음 구조로 표준 입력을 통해 JSON을 받습니다:

{
"event": "PreToolUse",
"toolName": "edit_file",
"toolInput": {
"path": "src/app.ts",
"content": "..."
},
"sessionId": "abc123",
"turnId": "turn-456"
}스크립트는 이 입력을 파싱하여 결정을 내립니다. Python 유효성 검사 훅은 다음과 같을 수 있습니다:#!/usr/bin/env python3
import sys
import json

input_data = json.load(sys.stdin)
tool_input = input_data.get('toolInput', {})
file_path = tool_input.get('path', "")

if file_path.startswith('protected/'):
print("Cannot edit protected files", file=sys.stderr)
sys.exit(1)

sys.exit(0)

종료 코드 0은 작업을 허용합니다. 종료 코드 1은 작업을 차단하고 stderr 메시지를 Claude에 표시합니다. 종료 코드 2는 이벤트에 따라 특별한 동작을 트리거합니다.

종료 코드 2 동작

공식 훅 참조 문서에 따르면, 종료 코드 2는 이벤트별 의미를 갖습니다(PreToolUse: 차단하고 재고 요청; UserPromptSubmit: 차단 없이 컨텍스트 제공; PermissionRequest: 권한 차단):

PreToolUse: 도구를 차단하고 stderr 메시지를 컨텍스트로 사용하여 Claude가 재고하도록 요청합니다.
UserPromptSubmit: stderr 출력을 차단 없이 추가 컨텍스트로 제공합니다.
PermissionRequest: 권한 부여를 차단합니다.

이는 하드 차단과 허용 사이의 중간 지점을 만듭니다. Claude는 작업이 왜 문제가 될 수 있는지에 대한 피드백을 받고 접근 방식을 조정할 수 있습니다.

비동기 명령 훅

async: true 플래그는 훅을 Claude의 워크플로를 차단하지 않고 백그라운드에서 실행합니다. 이는 배포 알림 또는 메트릭 수집과 같이 느린 작업에 중요합니다.

{
"event": "PostToolUse",
"matcher": {
"toolName": "execute_command"
},
"command": "./scripts/log-to-analytics.sh",
"async": true,
"timeout": 30
}

비동기 훅이 트리거되면 Claude Code는 프로세스를 시작하고 즉시 계속 진행합니다. timeout 필드는 최대 실행 시간을 초 단위로 설정합니다. 지정하지 않으면 비동기 훅은 10분 기본 타임아웃을 사용합니다.

솔직히 말해서, 비동기 훅은 Claude가 계속 진행된 후에 실행되므로 작업을 차단할 수 없습니다. 로깅, 알림 및 정리에는 작동하지만 유효성 검사에는 작동하지 않습니다.

HTTP 훅: 외부 서비스 통합

HTTP 훅은 원격 엔드포인트에 JSON 페이로드를 POST하고 응답을 파싱하여 제어합니다. 이는 유효성 검사 서비스, 데이터베이스 및 타사 도구와의 통합을 가능하게 합니다.

기본 HTTP 훅 구성:

{
"event": "PreToolUse",
"url": "api.example.com/validate",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
},
"timeout": 5
}

페이로드 구조는 명령 훅 입력과 일치하지만 HTTP POST 본문으로 도착합니다. 응답이 Claude의 다음 동작을 결정합니다.

HTTP 응답 처리

공식 문서에 따르면, HTTP 훅은 상태 코드 및 본문 내용을 기반으로 응답을 해석합니다:

상태 코드	효과	메시지 출처
200	작업 허용	응답 본문 (선택 사항)
400	작업 차단	Claude에 표시되는 응답 본문
500	훅 오류, 작업 허용	기록되지만 Claude에 표시되지 않음
기타	작업 허용	훅 실패가 워크플로를 차단하지 않음

응답 본문에는 Claude가 볼 수 있는 메시지 필드가 포함될 수 있습니다. 이를 통해 유효성 검사 서비스는 작업이 차단된 이유를 설명할 수 있습니다.

환경 변수 보간

HTTP 훅은 url, 헤더 및 기타 문자열 필드에서 ${VAR} 구문을 지원합니다. 변수는 Claude Code가 실행되는 환경에서 확장됩니다.

공식 MCP 문서에 따르면, 환경 변수 확장은 기본 대체 구문 ${VAR:-default}를 포함하며, VAR이 설정되어 있으면 VAR로 확장되고 그렇지 않으면 기본값을 사용합니다.

보안 제약: GitHub 이슈 #28044에 따르면, HTTP 훅은 allowedEnvVars 구성 필드에 명시적으로 나열된 환경 변수만 액세스할 수 있습니다. 이는 우발적인 자격 증명 노출을 방지합니다.

프롬프트 훅: 컨텍스트 삽입

프롬프트 훅은 특정 이벤트에서 Claude의 컨텍스트에 동적 지침을 삽입합니다. 외부 프로세스나 API 호출 없이 동작을 수정합니다.

{
"event": "SessionStart",
"prompt": "You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises."
}

삽입된 텍스트는 해당 세션의 Claude 시스템 지침의 일부가 됩니다. 프롬프트 훅은 이벤트 데이터를 기반으로 확장되는 템플릿 변수도 사용할 수 있습니다.

동적 프롬프트 생성

공식 문서에 따르면, 프롬프트 훅은 동적 프롬프트를 생성하는 명령 필드를 지원합니다:

{
"event": "ContextCompaction",
"type": "prompt",
"command": "./scripts/generate-context-summary.sh"
}

명령은 표준 JSON 입력을 표준 입력을 통해 받고 표준 출력으로 프롬프트 텍스트를 출력합니다. 이를 통해 프로젝트 상태에 기반한 컨텍스트 인식 지침 생성이 가능합니다.

에이전트 기반 훅

에이전트 훅은 직접적인 프롬프트 삽입 대신 이벤트를 처리하는 하위 에이전트를 지정합니다. 하위 에이전트는 이벤트에 대한 컨텍스트를 받고 다단계 추론을 수행할 수 있습니다.

{
"event": "PostToolUseFailure",
"agent": "debugger",
"agentPrompt": "A tool call failed. Analyze the error and suggest fixes."
}

이름이 지정된 하위 에이전트는 프로젝트 구성에 정의되어야 합니다. 에이전트 훅은 간단한 프롬프트 삽입으로는 제공할 수 없는 복잡한 의사 결정 로직을 가능하게 합니다.

실용적인 훅 패턴

커뮤니티 토론과 공식 예제는 프로덕션에서 안정적으로 작동하는 특정 자동화 패턴을 보여줍니다.

편집 후 코드 자동 포맷

가장 일반적인 패턴은 Claude가 파일을 편집한 후 코드를 자동으로 포맷하는 것입니다:

{
"event": "PostToolUse",
"matcher": {
"toolName": "edit_file",
"pathPattern": "**/*.{js,ts,jsx,tsx}"
},
"command": "prettier",
"args": ["--write", "${toolInput.path}"]
}

${toolInput.path} 변수는 편집된 파일 경로로 확장됩니다. PostToolUse는 성공적인 편집 후 포맷팅이 이루어지도록 보장하지만 Claude의 워크플로를 차단하지는 않습니다.

보호된 파일 수정 차단

PreToolUse 훅은 파일 보호 규칙을 적용합니다:

{
"event": "PreToolUse",
"matcher": {
"toolName": "edit_file"
},
"command": "./scripts/check-protected.sh"
}

스크립트는 대상 경로를 보호된 패턴과 비교하고 코드 1로 종료하여 금지된 편집을 차단합니다.

Claude가 입력이 필요할 때 알림 받기

공식 워크플로 가이드에 따르면, Notification 훅은 데스크톱 알림을 트리거하거나 외부 서비스로 메시지를 보낼 수 있습니다:

{
"event": "Notification",
"command": "osascript",
"args": ["-e", "display notification \"${message}\" with title \"Claude Code\""]
}

이것은 Claude Code가 사용자 입력을 기다리거나 작업 완료 후 등 알림을 보낼 때마다 트리거됩니다.

압축 후 컨텍스트 재삽입

ContextCompaction 훅은 대화 창이 꽉 찼을 때 중요한 컨텍스트를 복원합니다:

{
"event": "ContextCompaction",
"type": "prompt",
"command": "cat .claude/critical-context.md"
}

명령 출력은 압축이 이전 메시지를 제거한 후 Claude의 컨텍스트에 다시 삽입됩니다. 이를 통해 중요한 프로젝트별 지침 손실을 방지합니다.

구성 변경 감사

Claude가 구성 파일을 수정할 때 추적합니다:

{
"event": "PostToolUse",
"matcher": {
"toolName": "edit_file",
"pathPattern": "**/{package.json,.env,*.config.*}"
},
"command": "git",
"args": ["add", "${toolInput.path}"],
"async": true
}

비동기 실행은 Git 작업이 완료되는 동안 Claude를 차단하지 않습니다. 이를 통해 수동 스테이징 없이 구성 변경에 대한 감사 추적을 생성합니다.

JSON 출력 및 결정 제어

명령 훅은 간단한 종료 코드 이상의 상세한 피드백을 제공하기 위해 구조화된 JSON을 출력할 수 있습니다. 공식 참조에 따르면, JSON 출력은 Claude가 의사 결정을 위해 해석하는 다중 필드 응답을 가능하게 합니다.

{
"allowed": false,
"message": "This file is protected by team policy",
"suggestion": "Create a new file in src/features/ instead"
}

allowed 필드는 작업이 진행될지 여부를 제어합니다. message는 Claude에게 컨텍스트로 표시됩니다. suggestion 필드는 대안적인 접근 방식을 제공합니다.

훅이 JSON을 출력하려면 다음을 수행해야 합니다:

표준 출력으로 유효한 JSON 작성
코드 0(허용) 또는 1(차단)로 종료
최소한 allowed 부울 필드 포함

Claude Code는 JSON을 파싱하고 이를 피드백 루프를 개선하는 데 사용합니다. 종료 코드는 여전히 주요 결정을 내리지만, JSON은 더 풍부한 컨텍스트를 제공합니다.

훅 입력 필드 참조

모든 훅은 공통 필드와 이벤트별 데이터를 포함하는 JSON 객체를 표준 입력을 통해 받습니다. 완전한 스키마를 이해하면 더 정교한 훅 로직을 만들 수 있습니다.

공통 입력 필드

모든 훅은 다음 기본 필드를 받습니다:

event: 훅 이벤트 이름 (예: "PreToolUse")
sessionId: 현재 Claude 세션의 고유 식별자
turnId: 현재 대화 턴의 식별자
timestamp: 이벤트가 발생한 ISO 8601 타임스탬프

도구 이벤트 필드

PreToolUse, PostToolUse 및 PostToolUseFailure 이벤트에는 다음이 포함됩니다:

toolName: 호출되는 도구의 이름 (edit_file, execute_command 등)
toolInput: 도구의 입력 매개변수를 포함하는 객체
toolResponse: 도구 출력 데이터 (PostToolUse만 해당)
error: 메시지 및 코드를 포함한 오류 세부 정보 (PostToolUseFailure만 해당)

toolInput 구조는 도구마다 다릅니다. edit_file의 경우 path와 content를 포함합니다. execute_command의 경우 command와 args를 포함합니다.

권한 이벤트 필드

PermissionRequest 이벤트에는 다음이 포함됩니다:

permissionType: 요청된 권한 유형 (file_write, command_execute 등)
requestedAction: 권한이 필요한 특정 작업
resourcePath: 영향을 받는 파일 경로 또는 리소스 식별자

MCP 도구 훅

공식 훅 참조에 따르면, 훅은 mcpTool 매처 필드를 사용하여 모델 컨텍스트 프로토콜(MCP) 도구와 일치시킬 수 있습니다. 이를 통해 Claude가 MCP 서버에서 제공하는 외부 도구를 사용할 때 훅 실행이 가능합니다.

{
"event": "PreToolUse",
"matcher": {
"mcpTool": "database/query"
},
"command": "./scripts/validate-sql.sh"
}

mcpTool 값은 형식 server-name/tool-name에서 도구 이름과 일치합니다. 이를 통해 데이터베이스 쿼리, API 호출 또는 기타 외부 작업에 대한 유효성 검사 로직을 적용할 수 있습니다.

GitHub 기능 요청은 MCP 통합이 더욱 심화될 것이라는 관심이 높아지고 있음을 나타냅니다. MCP 서버 알림을 검사하고 외부 이벤트에 응답할 수 있는 훅을 포함합니다.

보안 고려 사항

훅은 Claude Code 자체와 동일한 권한으로 실행됩니다. 이는 다중 사용자 환경 및 공유 구성에 대한 보안 영향을 초래합니다.

명령 실행 샌드박스

GitHub 이슈 #28044에 따르면, HTTP 훅은 네트워크 액세스를 제한하고 환경 변수를 필터링하는 샌드박스 프록시를 통해 라우팅됩니다. 명령 훅은 이러한 제한이 없으며 완전한 쉘 액세스로 실행됩니다.

문서에서는 다음 사항을 권장합니다:

훅 명령에 자격 증명을 저장하지 마십시오.
민감한 데이터는 환경 변수를 사용하십시오.
${...} 확장에서 오는 모든 입력을 검증하십시오.
외부 서비스에 대한 타임아웃 제한을 구현하십시오.
실패 시 차단을 방지하기 위해 중요하지 않은 작업에는 비동기 훅을 사용하십시오.

훅 실행 격리

~/.claude/settings.json의 사용자 수준 훅은 모든 프로젝트에 적용됩니다. 이는 서로 다른 신뢰 경계에서 작업할 때 위험을 초래합니다. 프로젝트 수준 훅은 사용자 훅을 재정의하지만 완전히 비활성화할 수는 없습니다.

Claude Code의 /hooks 메뉴는 현재 세션의 모든 활성 훅을 표시합니다. 민감한 프로젝트에서 작업하기 전에 이 목록을 검토하면 잠재적인 보안 문제를 식별하는 데 도움이 됩니다.

디버깅 및 문제 해결

훅 실패는 Claude의 대화에서 항상 명확하게 드러나지는 않습니다. 공식 문서는 여러 디버깅 접근 방식을 제공합니다.

훅 실행 로그

Claude Code는 세션 디버그 출력에 훅 실행을 기록합니다. 문제 해결 가이드에 따르면, 디버그 로깅을 활성화하면 다음을 확인할 수 있습니다:

각 이벤트에 대해 어떤 훅이 일치했는지
각 훅에 전송된 JSON 입력
훅 프로세스의 stdout 및 stderr 출력
종료 코드 및 실행 시간
HTTP 훅의 HTTP 응답 코드 및 본문

Claude Code를 시작하기 전에 환경에서 CLAUDE_DEBUG=1을 설정하여 디버그 로깅을 활성화하십시오.

훅 독립적 테스트

명령 훅은 수동으로 JSON 입력을 구성하여 Claude Code 외부에서 테스트할 수 있습니다:

echo '{"event":"PreToolUse","toolName":"edit_file","toolInput":{"path":"test.txt"}}' | ./scripts/my-hook.sh

이를 통해 실제 Claude 작업을 트리거하지 않고 훅 로직을 검증할 수 있습니다. 종료 코드와 stdout/stderr 출력은 예상되는 동작과 일치해야 합니다.

일반적인 훅 실패

커뮤니티 토론에서는 다음과 같은 빈번한 문제를 식별했습니다:

타임아웃 오류: 기본 10분 타임아웃이 느린 작업에는 너무 짧음—timeout 필드로 늘리십시오.
경로 확장 실패: ${file}과 같은 변수가 파일 컨텍스트를 포함하지 않는 이벤트에 대해 정의되지 않음
권한 오류: 훅 스크립트에 실행 권한이 없음—chmod +x script.sh 실행
JSON 파싱 오류: 훅에서 생성된 잘못된 JSON—반환하기 전에 jq로 검증
환경 변수 사용 불가: 훅 프로세스로 전파되지 않은 변수—Claude Code의 환경 확인

훅 성능 영향

동기 훅은 완료될 때까지 Claude의 워크플로를 차단합니다. 기본 10분 타임아웃은 무기한 중단을 방지하지만, 짧은 지연도 여러 작업에 걸쳐 누적됩니다.

실무자들은 간단한 유효성 검사 훅은 성능에 거의 영향을 미치지 않는다고 보고합니다. 파일 포맷팅 훅은 눈에 띄지만 허용 가능한 성능 영향을 줍니다. 외부 API 호출은 워크플로 마찰을 일으킬 수 있습니다. 복잡한 계산 작업은 비동기 실행의 이점을 얻습니다.

훅 배치

여러 훅이 동일한 이벤트와 일치할 수 있습니다. 참조 문서에 따르면, 훅은 정의 순서대로 순차적으로 실행됩니다. 어떤 훅이라도 작업을 차단하면 나머지 훅은 실행되지 않습니다.

이는 성능에 중요합니다. 200ms씩 걸리는 다섯 개의 동기 훅은 이벤트당 1초씩 추가됩니다. 관련 유효성 검사를 단일 훅으로 결합하면 오버헤드를 줄일 수 있습니다.

고급 패턴

기본 자동화를 넘어, 훅은 정교한 워크플로 사용자 정의를 가능하게 합니다.

상태 저장 훅 체인

훅은 파일이나 데이터베이스를 사용하여 실행 간에 상태를 유지할 수 있습니다. PostToolUse 훅은 나중에 PreToolUse 훅이 검증할 성공적인 작업을 기록할 수 있습니다:

#!/bin/bash
# Record successful edits
echo "${toolInput.path}" >> .claude/edit-history.txt

동반되는 PreToolUse 훅은 중복 작업을 방지하거나 순서 제약을 적용하기 위해 이 기록을 확인할 수 있습니다.

조건부 훅 활성화

환경 변수는 런타임에 훅 동작을 제어합니다. CLAUDE_SKIP_HOOKS=1을 설정하면 비상 상황에 훅이 비활성화됩니다.

훅 자체는 환경 플래그를 확인할 수 있습니다:

#!/bin/bash
if [ "${STRICT_MODE}" = "1" ]; then
# Apply strict validation
exit 1
fi
exit 0

이를 통해 구성 변경 없이 개발 모드 대 프로덕션 모드 동작이 가능합니다.

다단계 유효성 검사

PreToolUse 훅은 종료 코드 2가 경고와 함께 Claude가 진행하도록 허용하는 다단계 유효성 검사를 구현할 수 있습니다:

하드 실패 (종료 코드 1): 위험한 작업 차단
소프트 경고 (종료 코드 2): Claude에게 재고하도록 알림
컨텍스트 포함 통과 (종료 코드 0 + JSON): 추가 정보 제공

이는 이진 허용/거부보다 더 미묘한 유효성 검사 스펙트럼을 만듭니다.

CI/CD와 통합

공식 플랫폼 통합 문서에 따르면, Claude Code는 자동화된 코드 검토 및 이슈 트리아지를 위해 CI/CD 환경에서 실행됩니다. 훅은 이 자동화를 확장합니다.

GitHub Actions 워크플로는 자동화된 세션 중에 팀 정책을 적용하는 훅을 정의할 수 있습니다:

-- name: Run Claude Code with strict hooks
env:
STRICT_MODE: 1
run: |
claude "Review this PR and suggest improvements"

STRICT_MODE 플래그는 훅 스크립트에서 조건부 유효성 검사 로직을 활성화합니다. 이를 통해 자동화된 세션이 상호 작용 개발보다 더 엄격한 규칙을 따르도록 보장합니다.

감사 추적 생성

CI 환경의 PostToolUse 훅은 모든 Claude 작업에 대한 상세한 감사 로그를 생성합니다:

{
"event": "PostToolUse",
"command": "./scripts/log-to-database.sh",
"async": true
}

백그라운드 로깅은 성능에 영향을 미치지 않지만 규정 준수 및 디버깅을 위해 완전한 작업 기록을 제공합니다.

/hooks 메뉴

Claude Code는 현재 세션의 모든 활성 훅을 표시하는 /hooks 명령을 제공합니다. 공식 문서에 따르면, 이 메뉴는 다음을 표시합니다:

훅 이벤트 유형
매처 패턴
명령 또는 URL 엔드포인트
훅이 비동기로 실행되는지 여부
구성 소스 (프로젝트, 사용자 또는 플러그인)

훅을 선택하면 전체 구성을 보고 현재 세션에 대해 일시적으로 비활성화할 수 있습니다.

훅 비활성화 또는 제거

훅 정의에 "enabled": false를 추가하여 구성을 제거하지 않고 훅을 비활성화할 수 있습니다. 이렇게 하면 구성을 유지하면서 실행을 방지합니다.

훅을 영구적으로 제거하려면 해당 settings.json 파일에서 항목을 삭제하십시오. 변경 사항은 다음 세션 재시작 시 또는 /reload 실행 시 적용됩니다.

기술 및 에이전트의 훅

공식 문서에 따르면, 기술 또는 하위 에이전트 구성 내에 정의된 훅은 해당 기술 또는 에이전트가 실행될 때만 적용됩니다. 이를 통해 특정 워크플로에 대한 특화된 자동화가 가능합니다.

디버깅 하위 에이전트에는 모든 도구 호출을 로깅하는 훅이 포함될 수 있습니다:

{
"name": "debugger",
"hooks": [
{
"event": "PostToolUse",
"command": "./scripts/log-debug.sh",
"async": true
}
]
}

이 훅은 일반 Claude Code 작업 중이 아니라 디버거 에이전트 세션 중에만 트리거됩니다.

스크립트 경로 참조

훅 명령은 상대 경로와 절대 경로를 모두 지원합니다. 상대 경로는 Claude Code가 실행되는 프로젝트 루트에서 확인됩니다.

커뮤니티 토론에서 나온 모범 사례:

훅 스크립트를 .claude/hooks/ 디렉토리에 저장하십시오.
설명적인 이름 사용: hook1.sh가 아닌 validate-typescript.sh
스크립트 실행 가능하게 만들기: chmod +x .claude/hooks/*.sh
Shebang 라인 포함: #!/usr/bin/env bash 또는 #!/usr/bin/env python3
Bash 스크립트에서 set -e를 사용하여 오류 처리 추가

향후 훅 기능

GitHub 기능 요청은 계획 및 요청된 훅 개선 사항을 보여줍니다:

인라인 스크립트 훅: 외부 파일 없이 settings.json에서 직접 훅 로직 정의
MCP 도구 통합: 쉘 명령 대신 훅에서 MCP 서버 도구 호출
다중 에이전트 협업: 다른 기계의 Claude 인스턴스 간에 조정하는 훅
향상된 타이핑: 훅 입력/출력 스키마에 대한 TypeScript 유형 정의

GitHub 이슈 #4274에 따르면, 통합 훅 유형(MCP 도구, 인라인 스크립트, API 호출)에 대한 요청은 구성을 단순화하고 개발자 경험을 개선하는 것을 목표로 합니다.

자주 묻는 질문

훅은 Claude가 위험한 명령을 실행하는 것을 막을 수 있나요?

예. PreToolUse 훅은 코드 1로 종료하여 모든 도구 실행을 차단할 수 있습니다. 여기에는 파일 편집, 명령 실행 및 MCP 도구 호출이 포함됩니다. 훅은 전체 도구 입력을 받고 작업을 허용하기 전에 어떤 기준과도 비교하여 검증할 수 있습니다.

작동하지 않는 훅을 어떻게 디버깅하나요?

Claude Code를 시작하기 전에 CLAUDE_DEBUG=1로 디버그 로깅을 활성화하십시오. 세션 로그에서 어떤 훅이 일치했는지, 전송된 JSON 입력, stdout/stderr 출력 및 종료 코드를 포함한 훅 실행 세부 정보를 확인하십시오. 샘플 JSON을 훅 스크립트로 파이프하여 훅을 독립적으로 테스트하십시오.

훅은 모든 Claude Code 플랫폼과 함께 작동하나요?

훅은 CLI, 데스크톱 앱 및 VS Code 확장 프로그램에서 작동합니다. 공식 문서에 따르면, 훅은 파일 시스템에 액세스할 수 있는 Claude Code가 실행되는 곳 어디에서나 실행됩니다. 브라우저 기반 Claude 및 모바일 앱은 샌드박싱 제약으로 인해 훅을 지원하지 않습니다.

훅은 Claude의 응답이나 동작을 수정할 수 있나요?

프롬프트 훅은 Claude의 동작에 영향을 미치는 지침을 삽입합니다. 에이전트 훅은 이벤트 처리를 특수 하위 에이전트에 위임합니다. 그러나 훅은 Claude의 생성된 텍스트나 추론 프로세스를 직접 수정할 수 없습니다. 컨텍스트를 제공하고 작업을 차단하는 방식으로 작동합니다.

async와 sync 훅의 차이점은 무엇인가요?

동기 훅은 완료 또는 타임아웃될 때까지 Claude의 워크플로를 차단합니다. 비동기 훅은 차단하지 않고 백그라운드에서 실행됩니다. 동기 훅은 종료 코드를 통해 작업을 방지할 수 있습니다. 비동기 훅은 Claude가 훅이 완료되기 전에 계속 진행하므로 차단할 수 없습니다. 로깅 및 알림에는 비동기, 유효성 검사에는 동기 사용.

팀원들과 훅을 공유하려면 어떻게 해야 하나요?

.claude/settings.json 파일을 버전 관리에 커밋하십시오. 프로젝트 수준 훅은 저장소를 복제한 모든 팀원에게 적용됩니다. 조직 전체 정책을 위해 팀은 구성원들이 ~/.claude/settings.json에 복사하는 공유 사용자 수준 설정 파일을 유지할 수 있습니다.

HTTP 훅이 방화벽 뒤의 내부 API를 호출할 수 있나요?

예, Claude Code가 해당 API에 대한 네트워크 액세스 권한이 있는 환경에서 실행되는 경우 가능합니다. HTTP 훅은 Claude Code를 실행하는 기계에서 표준 POST 요청을 보냅니다. 기업 방화벽 및 VPN은 일반적으로 적용됩니다. 문서에서 언급된 샌드박스 프록시는 네트워크 라우팅이 아닌 환경 변수 노출을 제어합니다.

훅은 Claude Code의 토큰 사용량을 증가시키나요?

프롬프트 훅은 텍스트를 Claude의 컨텍스트에 삽입하여 토큰을 소모합니다. 명령 및 HTTP 훅은 직접적으로 토큰 사용량에 영향을 미치지 않지만, 출력(오류 메시지, 제안)은 대화 컨텍스트의 일부가 됩니다. 설명 메시지가 있는 종료 코드 2는 간단한 차단이 있는 종료 코드 1보다 더 많은 컨텍스트를 추가합니다.

결론

Claude Code 훅은 AI 어시스턴트를 강력한 도구에서 완전 자동화된 개발 플랫폼으로 변화시킵니다. 이벤트 시스템은 세션 초기화부터 컨텍스트 압축까지 Claude의 워크플로 전체에 걸쳐 가로채기 지점을 제공합니다.

명령 훅은 로컬 유효성 검사 및 포맷팅을 처리합니다. HTTP 훅은 외부 서비스 및 데이터베이스를 통합합니다. 프롬프트 훅은 컨텍스트 삽입을 통해 동작을 수정합니다. 이들은 팀 정책을 시행하고, 코드 품질을 유지하며, 기존 개발 인프라와 통합되는 자동화 패턴을 가능하게 합니다.

매처 시스템은 훅을 특정 도구 및 파일 패턴으로 필터링합니다. 종료 코드 및 JSON 출력은 결정 흐름을 제어합니다. 비동기 실행은 느린 작업에서 차단을 방지합니다. 완전한 구성 스키마는 간단한 자동 포맷팅부터 복잡한 다단계 유효성 검사까지 모든 것을 지원합니다.

코드 포맷팅을 위한 간단한 PostToolUse 훅으로 시작하십시오. 정책이 등장함에 따라 PreToolUse 유효성 검사를 추가하십시오. 동작 수정을 위해 프롬프트 훅을 실험하십시오. 팀 전체 적용을 위해 HTTP 통합을 구축하십시오.

새로운 기능이 출시됨에 따라 완전한 훅 참조 및 업데이트된 구성 스키마는 공식 Claude Code 문서를 참조하십시오.