2.4.2 Hooks 만들기

4.2 Hooks 만드는 방법

settings.json의 hooks 키에 이벤트별 핸들러를 정의하면 즉시 적용된다. /hooks 메뉴로 UI에서 관리할 수도 있다. 업데이트: 2026-03-08

---

핵심 요약

구분	내용
📖 정의	settings.json의 hooks 키에 이벤트→매처→핸들러 순서로 정의하면 Claude Code가 즉시 인식한다
💡 핵심	파일 저장 위치(글로벌/프로젝트/로컬)에 따라 적용 범위가 달라진다
🎯 대상	Hooks를 직접 작성하고 설정하려는 개발자
⚠️ 주의	Hook 스크립트는 Claude Code와 동일한 권한으로 실행된다. 외부 저장소의 hooks는 반드시 검토 후 사용한다

---

문서 탐색

이전	다음
2.4.1 Hooks란?	2.4.3 Hooks 예제

---

목차

1. 설정 파일 위치와 범위
2. 기본 설정 구조
3. 핸들러 타입 4가지
4. 매처(Matcher) 패턴
5. /hooks 인터랙티브 메뉴
6. Agent-Scoped Hooks (Skills 2.0)
7. 보안 설정

---

1. 설정 파일 위치와 범위

위치	범위	Git 공유 가능
~/.claude/settings.json	모든 프로젝트 (글로벌)	No
.claude/settings.json	단일 프로젝트	Yes (커밋 가능)
.claude/settings.local.json	단일 프로젝트	No (gitignore 권장)
Managed policy	조직 전체	Yes (관리자만)
Skill/Agent 프론트매터	해당 컴포넌트 활성 시	Yes

💡 팀 전체에 적용할 hooks는 .claude/settings.json에, 개인 설정은 ~/.claude/settings.json에 저장한다.

---

2. 기본 설정 구조

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "매처 패턴",
        "hooks": [
          {
            "type": "핸들러 타입",
            "command": "실행할 명령어"
          }
        ]
      }
    ]
  }
}

실제 예시

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/lint-on-save.sh",
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

exit 코드 의미

Hook 스크립트의 종료 코드에 따라 Claude Code의 동작이 달라진다.

exit 코드	의미	동작
0	성공	stdout의 JSON 파싱, 실행 계속
2	차단	stderr를 Claude에게 전달, 이벤트별 차단 효과 적용
기타	비차단 오류	stderr를 verbose 모드에 표시, 실행 계속

---

3. 핸들러 타입 4가지

Command Hook

가장 범용적인 타입이다. 셸 명령이나 스크립트를 실행하고, stdin으로 이벤트 JSON을 수신한다.

{
  "type": "command",
  "command": ".claude/hooks/validate.sh",
  "async": false,
  "timeout": 600
}

• async: true — 백그라운드 실행 (로깅·알림 등 결과를 기다릴 필요 없는 작업에 사용)
• timeout — 초 단위 타임아웃 (기본값 600초)
• stdin으로 이벤트 JSON 수신: jq -r '.tool_input.command' < /dev/stdin

HTTP Hook

이벤트 JSON을 HTTP POST로 외부 서버에 전송한다. CI/CD 연동, 감사 로그 서버에 적합하다.

{
  "type": "http",
  "url": "http://localhost:8080/hooks/validate",
  "headers": { "Authorization": "Bearer $MY_TOKEN" },
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 30
}

• allowedEnvVars — 명시된 환경변수만 헤더에서 참조 가능 (보안)
• 비-2xx 응답은 비차단 오류 (실행 계속)
• 차단하려면 2xx 응답 + JSON body에 decision 필드 포함

Prompt Hook

LLM에게 판단을 위임한다. 맥락 의존적인 복잡한 검증에 적합하다.

{
  "type": "prompt",
  "prompt": "Is this operation safe? Check $ARGUMENTS",
  "model": "claude-haiku-4"
}

• 단일 턴 yes/no 판단에 LLM 활용
• 비용이 발생하므로 단순한 패턴 매칭은 command hook이 더 적합

Agent Hook

Read, Grep, Glob 등 도구를 사용하는 서브에이전트를 생성한다. 깊은 코드베이스 분석이 필요한 검증에 적합하다.

{
  "type": "agent",
  "prompt": "Verify the codebase is in a valid state after these changes: $ARGUMENTS",
  "timeout": 60
}

---

4. 매처(Matcher) 패턴

매처는 정규식 문자열로 어떤 도구 호출에 hook을 적용할지 지정한다.

패턴	매칭 대상
"Bash"	Bash 도구만
"Edit|Write"	Edit 또는 Write
"mcp__memory__.*"	memory 서버의 모든 도구
"mcp__.*__write.*"	모든 서버에서 write 포함 도구
"*" 또는 "" 또는 생략	모든 발생

⚠️ UserPromptSubmit, Stop 등 일부 이벤트는 매처를 지원하지 않는다.

---

5. /hooks 인터랙티브 메뉴

설정 파일을 직접 편집하지 않고 UI에서 hooks를 관리할 수 있다.

/hooks

flowchart TD
    A["/hooks 입력"] --> B["전체 hooks 목록 표시\n소스: [User] [Project] [Local] [Plugin]"]
    B --> C{"선택"}
    C --> D["새 hook 추가"]
    C --> E["기존 hook 수정"]
    C --> F["hook 삭제"]

⚠️ HTTP hooks는 /hooks 메뉴에서 지원하지 않는다. JSON 직접 편집이 필요하다.

---

6. Agent-Scoped Hooks (Skills 2.0)

Skills 또는 Sub-agents 프론트매터에 직접 hooks를 정의할 수 있다. 해당 컴포넌트가 활성화된 동안만 동작하며, 완료 시 자동으로 정리된다.

Skill 프론트매터 예시

---
name: secure-operations
description: 보안 검증이 포함된 작업 수행
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/format.sh"
          async: true
---

Agent 프론트매터 예시

---
name: code-reviewer
description: 코드 리뷰 에이전트
hooks:
  Stop:
    - hooks:
        - type: command
          command: "./scripts/generate-review-report.sh"
---

Agent-Scoped Hooks 특징

특징	설명
범위 제한	해당 Skill/Agent가 활성화된 동안만 적용
자동 정리	컴포넌트 완료 시 hook 자동 제거
Stop 자동 변환	서브에이전트의 Stop 이벤트는 SubagentStop으로 자동 처리
once 필드	true 설정 시 세션 내 1회만 실행 (Skills 전용)

---

7. 보안 설정

전체 Hooks 비활성화

{
  "disableAllHooks": true
}

모든 hooks를 일시 비활성화한다. 개별 비활성화는 지원하지 않는다.

조직 관리 Hooks만 허용

{
  "allowManagedHooksOnly": true
}

관리자가 이 설정을 적용하면 사용자·프로젝트·플러그인 hooks가 모두 차단되고, managed policy hooks만 실행된다.

보안 권장사항

1. 최소 권한 원칙 — 필요한 최소 기능만 hook으로 구현
2. 외부 hooks 검토 — 저장소에서 가져온 .claude/settings.json의 hooks는 반드시 검토
3. allowedEnvVars 활용 — HTTP hook에서 환경변수 사용 시 명시적 허용 목록 사용
4. 경로 변수 활용 — $CLAUDE_PROJECT_DIR로 절대 경로 지정

---

문서 탐색

이전	다음
2.4.1 Hooks란?	2.4.3 Hooks 예제

---

참고 자료

• Hooks reference — Claude Code 공식 문서
• Claude Code Hooks Complete Guide (2026) — smartscope.blog
• A complete guide to hooks in Claude Code — eesel.ai
• Claude Code Security Best Practices — Backslash

---