Claude Code 파워 사용자 맞춤화: 후크 구성 방법

원활하게 작동하는 Claude Code 워크플로우조차 시간이 흐르면 마찰 지점이 쌓이게 됩니다. Claude가 파일을 작성할 때마다 Prettier는 수동으로 실행해야 합니다. npm test를 실행할 때마다 동일한 권한 프롬프트가 나타납니다. 모든 세션은 첫 번째 메시지에 동일한 보일러플레이트 프로젝트 컨텍스트를 붙여넣는 것으로 시작합니다.

어떤 이점이 있을까요? 후크는 이러한 마찰 지점을 제거합니다. 후크는 특정 작업 전에 또는 후에 실행되도록 구성할 수 있는 트리거 역할을 하며 후크를 통해 사용자 지정 로직, 스크립트, 명령을 Claude의 작업에 직접 삽입할 수 있습니다. 

이 문서에서는 이미 Claude Code 기본 사항에 익숙한 개발자를 위한 고급 구성을 설명합니다. 이 문서를 끝까지 읽으면 8가지 후크 유형을 이해하고, 각 유형을 언제 사용해야 하는지, 구성 방법, 문제가 발생할 때 디버깅하는 방법을 파악할 수 있습니다.

자세한 내용을 살펴보겠습니다.

후크란 무엇인가요?

후크는 Claude Code 세션에서 Claude가 파일을 작성하려고 할 때나 프롬프트를 제출할 때 등 목표한 이벤트가 발생할 때 자동으로 실행되도록 생성하는 사용자 지정 셸 명령입니다. 후크는 실행 전 작업 가로채기, 에이전트 컨텍스트 주입, 승인 자동화, 작업 발생 전에 차단 등 다양한 작업에 지정할 수 있습니다.

후크는 이벤트 이름, matcher(어떤 도구가 후크를 트리거하는지 필터링), 실행할 명령이 포함된 JSON 구조를 사용하여 설정 파일에서 구성합니다. 후크는 사용자 권한으로 로컬 환경에서 실행되고 stdin을 통해 트리거 이벤트에 대한 정보를 수신하며, 종료 코드와 stdout을 통해 다시 통신합니다. 따라서 도구 자체를 수정하지 않고 Claude Code 동작을 정밀하게 제어할 수 있습니다.

Claude Code에 후크를 사용하는 이유는 무엇인가요?

후크는 3가지 카테고리의 문제를 해결합니다.

첫째, 반복적인 수동 단계를 제거합니다. 파일 변경 후 매번 포맷터를 실행하는 대신, PostToolUse 후크가 이 작업을 자동으로 처리합니다. npm test를 수백 번째 승인하는 대신, PermissionRequest 후크가 자동으로 승인합니다.

둘째, 후크는 프로젝트별 규칙을 자동으로 적용합니다. 위험한 명령을 실행 전에 차단하거나 쓰기 전에 파일 경로를 검증하거나 명명 규칙을 따르는지 확인할 수 있습니다. 이러한 가드레일은 사용자가 확인해야 한다고 기억할 때만 실행되는 것이 아니라, 항상 실행됩니다.

셋째, 후크는 수동으로 작업할 필요 없이 동적 컨텍스트를 주입합니다. SessionStart 후크는 Claude에 현재 git 서비스 상태와 TODO 목록을 제공할 수 있습니다. UserPromptSubmit 후크는 모든 요청에 스프린트 우선순위를 추가할 수 있습니다. 따라서 매번 반복하지 않아도 Claude는 최신 정보를 파악하고 있습니다.

Claude Code 후크 유형과 사용 시점

Claude Code는 시작부터 도구 실행을 거쳐 완료까지, 세션의 전체 라이프사이클을 아우르는 후크 이벤트 8개를 제공합니다. 각 후크 이벤트는 구체적인 순간에 실행되므로 자동화가 실행되는 시점을 정확하게 제어할 수 있습니다. 올바른 후크 선택은 무엇을 달성하고자 하는 목적에 따라 달라집니다.

한눈에 후크 살펴보기

PreToolUse

가장 일반적으로 사용되는 후크로, Claude가 사용할 도구를 선택한 다음 도구가 실제로 실행되기 전에 실행됩니다. 스크립트는 계획된 작업을 검토하고 승인하거나, 차단하거나, 사용자 확인을 요청하거나, 파라미터를 수정할 수 있습니다. matcher를 사용해 어떤 도구가 이 후크를 트리거할지 필터링할 수 있습니다.

다음 PreToolUse 후크 예시는 파일 쓰기가 실행되기 전에 평가합니다. Claude는 계획된 작업을 지정된 기준에 따라 검토하고 프롬프트 로직을 기반으로 승인, 차단하거나 우려 사항을 플래그할 수 있습니다.

PreToolUse를 사용해야 할 때:

• rm -rf나 강제 푸시와 같은 위험한 Bash 명령어 차단
• 안전하고 반복적인 작업을 자동으로 승인하여 프롬프트 피로도 줄이기
• 실수로 덮어쓰기를 방지하기 위해 쓰기 전에 파일 경로 검증
• 프로젝트별 기본값을 주입하도록 도구 입력 수정

PermissionRequest

이 후크는 Claude가 일반적인 상황에서 권한 대화상자를 표시할 때 실행됩니다. 이 후크는 확인 프롬프트가 표시되기 직전의 순간을 가로채어, 스크립트가 사용자를 허용 또는 거부할지, 계속해서 사용자에게 물어볼지 여부를 결정하도록 합니다.

이 예시는 npm test로 시작하는 모든 Bash 명령어를 자동으로 승인합니다. matcher 패턴에는 더 정밀한 제어를 위해 인수를 포함할 수 있습니다.

PermissionRequest를 사용해야 할 때:

• 세션당 수십 회 실행하는 테스트 명령어 자동 승인하는 경우
• 프로덕션 구성 파일에 대한 쓰기 액세스를 차단하는 경우
• 프롬프트 없이 특정 디렉터리에서 읽기 작업을 허용하는 경우
• 위험한 패턴과 일치하는 모든 명령을 거부하는 경우

PostToolUse

도구가 성공적으로 완료된 후 즉시 실행됩니다. 사용자 스크립트는 도구 출력을 포함해 어떤 상황이 발생했는지에 대한 정보를 받으며, matcher를 활용해 어떤 도구가 이 후크를 트리거하는지 필터링합니다.

이 PostToolUse 예시는 Claude가 작성하거나 편집하는 모든 파일에서 Prettier를 실행합니다. matcher의 파이프 구문은 이 후크가 Write와 Edit 도구 둘 다에서 트리거됨을 의미합니다.

PostToolUse를 사용해야 할 때:

• 파일이 작성될 때마다 서식 적용을 위해 Prettier, Black 또는 gofmt 실행하는 경우
• 모든 파일 수정 사항을 감사 추적에 기록하는 경우
• 코드 변경 후 linter 트리거 및 경고 표시하는 경우
• 특정 작업이 완료될 때 알림 전송하는 경우

PreCompact

Claude가 공간을 확보하기 위해 대화 컨텍스트를 압축하기 전에 실행됩니다. 압축은 대화의 이전 부분을 요약하므로 일부 세부 사항이 손실됩니다. 이 후크는 손실이 발생하기 전에 정보를 보존할 수 있는 기회를 제공합니다.

이 PreCompact 예시는 자동 압축 전에 전사 기록을 백업합니다. matcher는 'auto' 또는 'manual'이 될 수 있으므로 자동 압축 이벤트와 사용자 트리거 압축 이벤트를 구분할 수 있습니다.

PreCompact를 사용해야 할 때:

• 요약하기 전 전체 전사 기록을 파일로 백업하는 경우
• 중요한 결정이나 코드 스니펫을 추출 및 저장하는 경우
• 나중에 검토할 수 있도록 세션 마일스톤을 기록하는 경우

SessionStart

Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 스크립트가 출력하는 모든 내용이 대화 컨텍스트에 추가되므로 Claude는 해당 정보가 이미 로드된 상태로 시작합니다.

Claude가 현재 git 서비스 상태와 TODO 목록을 알고 있는 상태에서 모든 세션이 시작합니다. Stdout은 자동으로 컨텍스트가 됩니다.

SessionStart를 사용해야 할 때:

• Claude에 현재 git 브랜치와 최근 커밋 정보를 제공하는 경우
• TODO 목록 또는 스프린트 백로그의 내용을 로드하는 경우
• 환경별 구성 세부 정보를 주입하는 경우

Stop

Claude가 응답을 완료하고 일반적으로 사용자의 다음 입력을 기다릴 때 실행됩니다. 사용자의 스크립트는 Claude가 생성한 내용을 검토하고 작업이 실제로 완료되었는지 여부를 결정할 수 있습니다.

스크립트는 "continue": true가 포함된 JSON을 반환해 Claude가 계속 작동하도록 할 수 있으며 이는 다단계 워크플로우에 유용합니다.

Stop을 사용해야 할 때:

• 체크리스트의 모든 항목이 완료될 때까지 Claude가 계속 진행하도록 강제하는 경우
• 작업 완료로 간주하기 전에 테스트가 통과했는지 검증하는 경우
• 세션 종료 시 요약 생성을 트리거하는 경우
• 정지 전에 생성된 코드가 컴파일되는지 확인하는 경우

SubagentStop

이 후크는 작업 도구를 통해 생성된 서브 에이전트가 완료될 때마다 실행됩니다. Stop과 동일한 방식으로 작동하지만, 메인 에이전트가 아닌 서브 에이전트가 작업을 완료할 때 구체적으로 트리거됩니다. SubagentStop의 구성은 Stop 후크 구조를 미러링합니다.

SubagentStop을 사용해야 할 때:

• 서브 에이전트 결과가 품질 기준을 충족하는지 검증하는 경우
• 서브 에이전트 결과를 기반으로 후속 조치를 트리거하는 경우
• 디버깅 또는 감사를 위해 서브 에이전트 활동을 기록하는 경우

UserPromptSubmit

Claude가 처리하기 전에 프롬프트를 제출하면 실행됩니다. 스크립트가 stdout을 통해 출력하는 모든 내용이 프롬프트와 함께 Claude의 컨텍스트에 추가되므로, UserPromptSubmit는 Claude가 고려해야 할 정보를 동적으로 삽입하는 데 유용합니다.

이 예시에서 Claude는 프롬프트를 제출할 때마다 스프린트 컨텍스트 파일의 내용을 수신합니다. 따라서 현재 우선순위를 다시 설명할 필요 없이 Claude가 현재 우선순위에 대해 계속 파악하고 있습니다.

UserPromptSubmit을 사용해야 할 때:

• 모든 프롬프트에서 현재 스프린트 컨텍스트나 프로젝트 우선순위를 주입하는 경우
• Claude에 도달하기 전에 프롬프트를 검증하는 경우
• 콘텐츠에 기반한 특정 유형의 요청을 차단하는 경우
• 최근 오류 로그나 테스트 결과와 같은 동적 컨텍스트를 추가하는 경우

구성 및 파일 위치

후크는 JSON 설정 파일에서 세 가지 수준으로 존재합니다. 프로젝트 수준 후크는 리포지토리 내 .claude/settings.json에 저장되므로, 팀과 공유할 수 있습니다. 사용자 수준 후크는 ~/.claude/settings.json에 저장되고, 모든 내 프로젝트에 적용됩니다. 커밋하지 않으려는 개인 구성의 경우 로컬 프로젝트 후크는 .claude/settings.local.json에 저장됩니다.

프로젝트 수준 설정은 사용자 수준 설정보다 우선합니다. 또한 조직의 통제에 사용할 수 있는 엔터프라이즈 관리 정책 설정도 있습니다. 전체 세부 정보는 Claude Code 설정 정보를 참조하세요.

프로 팁: 이 파일은 프로젝트, 사용자, 로컬 수준에서 Claude 작업에 대해 세분화된 권한을 설정할 수 있는 동일한 파일입니다. 예를 들어, Claude가 디렉터리의 모든 파일을 읽도록 명시적으로 허용하여 매번 승인할 필요가 없도록 하거나, 민감한 파일의 수정을 차단할 수 있습니다.

Matcher 구문

matcher는 어떤 도구가 후크를 트리거할 수 있는지 필터링하는 방식입니다. PreToolUse, PostToolUse, PermissionRequest 후크에만 적용됩니다.

간단한 문자열 매칭은 기대했던 대로 정확히 작동하여 "Write"는 Write 도구만 매칭합니다.

예:

파이프 구문을 사용하면 여러 도구를 매칭할 수 있어 "Write|Edit"는 둘 중 하나가 매칭되면 트리거됩니다. 와일드카드는 모든 도구를 매칭하여 "*" 또는 빈 문자열은 모든 도구를 매칭합니다.

참고: matcher는 대/소문자를 구분하므로 "bash"는 Bash 도구와 일치하지 않습니다.

더 세밀하게 제어하기 위해 "Bash(npm test*)"와 같은 인수 패턴은 특정 명령 인수와 일치할 수 있습니다. 모델 컨텍스트 프로토콜 도구의 경우 MCP 도구 패턴은 "mcp__memory__.*" 형식을 따릅니다.

입력, 출력, 구조화된 응답

후크가 수신하는 항목

모든 후크는 stdin을 통해 세션 정보와 이벤트별 데이터가 포함된 JSON을 수신합니다. 일반 필드에는 session_id, transcript_path, cwd, permission_mode, hook_event_name이 있습니다.

또한 도구 관련 후크는 tool_name과 tool_input도 수신합니다. 이 데이터를 활용해 스크립트는 정보를 근거로 응답 방법을 결정할 수 있습니다.

후크 응답 방식

종료 코드에 따라 기본 결과가 결정됩니다. 종료 코드 0은 성공을 의미하며, stdout은 JSON으로 처리되거나 컨텍스트에 추가됩니다. 종료 코드 2는 차단 오류를 의미합니다. stderr는 오류 메시지로 전환되고, 작업이 차단됩니다.

다른 종료 코드는 비차단 오류를 나타내며 세부 정보 모드에서 stderr이 표시됩니다.

더 정밀한 제어를 위해 후크는 종료 코드 외에 구조화된 JSON을 반환할 수 있습니다. 필드에는 decision(approve, block, allow 또는 deny), reason(Claude에 표시되는 설명), continue(Stop 후크에서 계속 실행을 강제하기 위한 필드), updatedInput(실행 전에 도구 매개변수 수정)이 있습니다.

환경 및 실행

후크는 환경 변수에 액세스할 수 있는데, 여기에는 프로젝트 루트 경로의 경우 CLAUDE_PROJECT_DIR, 웹 환경의 경우 참인 CLAUDE_CODE_REMOTE, 변수를 유지하는 SessionStart 후크의 경우 CLAUDE_ENV_FILE이 있습니다. 셸의 표준 환경 변수에도 액세스할 수 있습니다.

참고: 후크의 기본 초과 시간은 60초이며 이 시간은 각 후크별로 구성할 수 있습니다. 후크 여러 개가 이벤트 하나와 일치하면 후크가 동시에 실행됩니다. 동일한 명령은 자동으로 중복 제거됩니다.

보안 고려 사항

후크는 사용자 권한으로 임의의 셸 명령을 실행합니다. Claude Code에는 안전 장치가 포함되어 있습니다. 후크 구성 파일을 직접 편집하면 적용되기 전에 /hooks 메뉴에서 검토해야 합니다. 이를 통해 악성 코드가 구성에 후크를 몰래 추가하는 것을 방지할 수 있습니다.

그러나 사용자가 후크를 구성하고 승인하면 사용자의 권한 수준에서 실행됩니다.

프로 팁: 환경에서 명령을 실행하기 전에 위험 요소를 고려하세요. 후크를 사용하여 명령을 실행하려는 경우 stdin의 입력값을 검증 및 정제하고, 주입을 방지하기 위해 셸 변수를 따옴표로 묶고, 스크립트에 절대 경로를 사용하며, .env나 자격 증명과 같은 민감한 파일을 처리하지 않도록 하는 것과 같은 모범 사례를 고려하세요.

디버깅 및 테스트

Claude Code는 전사 기록 파일에 모든 내용을 기록하며, 이를 통해 설정 없이도 도구 호출과 응답을 파악할 수 있습니다. 모든 후크는 전체 세션 기록이 포함된 JSONL 파일을 가리키는 transcript_path 필드를 수신합니다. SessionStart 후크를 사용해 각 전사 기록이 있는 위치를 기록할 수 있습니다.

그런 다음 해당 전사 기록을 tail 명령으로 추적하여 Claude가 작업하는 과정을 실시간으로 파악할 수 있습니다. tail -f /path/to/transcript.jsonl | jq .

후크별 디버깅

후크 관련 디버깅을 위해 후크 스크립트에 로깅을 추가합니다. 전가 기록 파일은 Claude가 수행한 작업을 표시하지만, 후크가 어떤 것을 승인 또는 차단하기 위해 작업을 수행한 이유는 표시하지 않습니다.

약간의 작업을 더해 도구를 래핑하고 추가 정보를 기록하는 작은 bash 스크립트를 추가할 수 있습니다. log-wrapper.sh의 예시는 다음과 같습니다.

이 작은 래퍼 스크립트는 stdin을 변수로 캡처하고 타임스탬프와 도구 이름을 기록한 다음 입력을 실제 도구로 전달합니다.

log-wrapper.sh를 작성하면 후크의 도구 호출 앞에 이를 추가합니다.

프로 팁: 더 많은 디버깅 팁을 확인하려면 Claude Code 디버깅 문서를 확인하세요.

나만의 후크 빌드

워크플로우에서 실제 마찰 지점을 해결하는 간단한 후크로 시작해 보세요. 피드백이 즉각적이고 가시적이기 때문에 PostToolUse 포맷터 후크는 처음 선택하기 가장 좋습니다. 이 후크가 잘 작동하면 학습한 내용을 기반으로 확장해 보세요.

사용 가능한 모든 필드와 고급 패턴을 포함한 참조 문서 전체는 공식 후크 문서를 참조하세요.

후크를 사용하면 도구에 맞춰 워크플로우를 조정하는 대신 워크플로우에 맞춰 Claude Code를 구성할 수 있습니다. 후크 구성에 투자하면 세션마다 효과를 얻을 수 있습니다.

지금 바로 후크를 사용해 Claude Code 워크플로우를 사용자 정의해 보세요.