4.1 Hooks란 무엇인가
Hooks는 Claude Code 세션의 특정 시점에 자동으로 실행되는 사용자 정의 핸들러다. CLAUDE.md가 “제안”이라면, Hooks는 “강제 실행”이다. 업데이트: 2026-03-08
핵심 요약
| 구분 | 내용 |
|---|---|
| 📖 정의 | Claude Code 세션의 라이프사이클 시점에 자동 실행되는 셸 명령·HTTP·LLM·서브에이전트 핸들러 |
| 💡 핵심 | LLM의 확률적 동작과 달리 항상 실행이 보장된다. 도구 차단, 자동 린트, 알림 등 규칙 강제에 사용한다 |
| 🎯 대상 | AI 동작에 규칙을 강제 적용하거나 반복 작업을 자동화하려는 개발자 |
| ⚠️ 주의 | Hook 스크립트는 Claude Code와 동일한 권한으로 실행되므로 외부 저장소의 hooks는 반드시 검토 후 사용한다 |
문서 탐색
목차
1. Hooks가 무엇인지 한 줄로 설명하면?
💡 Hooks = Claude Code가 특정 시점에 반드시 실행하는 사용자 규칙
Claude Code에게 “커밋 전에 테스트를 통과시켜줘”라고 CLAUDE.md에 적어두면, Claude가 기억할 수도 있고 잊을 수도 있다. Hooks를 사용하면 Claude가 멈추려 할 때 항상 테스트 스크립트가 실행된다.
프롬프트 지시 → LLM이 기억해야 함 (불확실)
Hooks → 항상 실행됨 (보장)
“If it’s a suggestion, use CLAUDE.md. If it’s a requirement, use hooks.”
Hooks는 네 가지 방식으로 동작할 수 있다:
| 타입 | 동작 방식 |
|---|---|
command | 셸 명령 또는 스크립트 실행 |
http | HTTP 엔드포인트로 이벤트 전송 |
prompt | LLM에게 판단 위임 |
agent | 서브에이전트 생성해 복잡한 검증 수행 |
2. 이벤트 종류
Claude Code는 2026년 기준 21개의 라이프사이클 이벤트를 제공한다.
| 이벤트 | 트리거 시점 | 실행 차단 가능 |
|---|---|---|
SessionStart | 세션 시작 또는 재개 시 | No |
UserPromptSubmit | 사용자 프롬프트 제출 직후, Claude 처리 전 | Yes |
PreToolUse | 도구 호출 실행 직전 | Yes |
PermissionRequest | 권한 요청 다이얼로그 표시 시 | Yes |
PostToolUse | 도구 호출 성공 후 | No (피드백만) |
PostToolUseFailure | 도구 호출 실패 후 | No |
Notification | Claude Code가 알림 전송 시 | No |
SubagentStart | 서브에이전트 생성 시 | No |
SubagentStop | 서브에이전트 완료 시 | Yes |
Stop | Claude가 응답 완료 시 | Yes |
TeammateIdle | 에이전트 팀 팀메이트 유휴 전환 시 | Yes |
TaskCompleted | 태스크 완료 처리 시 | Yes |
InstructionsLoaded | CLAUDE.md 또는 rules 파일 로드 시 | No |
ConfigChange | 설정 파일 변경 시 | Yes |
WorktreeCreate | worktree 생성 시 | Yes |
WorktreeRemove | worktree 제거 시 | No |
PreCompact | 컨텍스트 압축 직전 | No |
PostCompact | 컨텍스트 압축 완료 후 | No |
Elicitation | MCP 서버가 도구 호출 중 사용자 입력 요청 시 | Yes |
ElicitationResult | 사용자가 elicitation에 응답한 후 | No |
SessionEnd | 세션 종료 시 | No |
3. 주요 이벤트 상세
PreToolUse
도구 파라미터 생성 후, 실행 직전에 트리거된다. 유일하게 도구 실행 자체를 차단할 수 있는 이벤트다.
sequenceDiagram participant U as 사용자 participant C as Claude participant H as Hook participant T as 도구(Bash 등) U->>C: "rm -rf /tmp 실행해줘" C->>H: PreToolUse 이벤트 발생 H->>H: validate.sh 실행 H-->>C: exit 2 (차단) C-->>U: "위험한 명령으로 차단됨"
매칭 가능한 도구: Bash, Edit, Write, Read, Glob, Grep, Agent, WebFetch, WebSearch, MCP 도구(mcp__<server>__<tool> 패턴)
PostToolUse
도구가 성공적으로 완료된 직후에 트리거된다. 실행을 차단할 수는 없고, Claude에게 피드백을 전달하는 데 주로 사용한다.
주요 용도: 파일 수정 후 자동 린트, 포맷팅, 테스트 실행
Stop
Claude가 응답을 완료하고 멈추려 할 때 트리거된다. exit 2 또는 "decision": "block" 반환 시 Claude가 작업을 계속한다.
주요 용도: 완료 전 테스트 통과 확인, 데스크톱 알림, Slack 메시지 전송
Notification
알림 유형(permission_prompt, idle_prompt, auth_success, elicitation_dialog)으로 매칭된다. 차단은 불가하며, 데스크톱 알림이나 외부 서비스 연동에 활용한다.
4. 플랫폼별 Hooks 지원 비교
| 기능 | Claude Code | Gemini CLI | OpenAI Codex |
|---|---|---|---|
| 지원 여부 | O | O (v0.26.0+) | X (2026-03 기준) |
| 이벤트 수 | 21개 | 소수 (BeforeTool 등) | - |
| 핸들러 타입 | 4가지 (command/http/prompt/agent) | command 중심 | - |
| 도구 실행 차단 | O (PreToolUse) | O (제한적) | - |
| Agent-Scoped Hooks | O (Skill/Agent 프론트매터) | X | - |
| HTTP Hooks | O | 미확인 | - |
| 인터랙티브 메뉴 | O (/hooks) | X | - |
| 비동기 실행 | O (async: true) | 미확인 | - |
| 조직 관리 Hooks | O (managed policy) | X | - |
💡 Claude Code의 hooks 시스템이 이벤트 수, 핸들러 다양성, 세밀한 제어 면에서 가장 성숙하다.
5. Hooks vs CLAUDE.md vs Skills
| 기능 | 역할 | 실행 보장 | 적용 범위 |
|---|---|---|---|
CLAUDE.md | 프로젝트 전반의 규칙·맥락 저장 | X (LLM이 참고) | 항상 |
| Skills | 지시사항·스크립트·파일을 묶은 재사용 모듈 | X (LLM이 판단) | 선택적 |
| Hooks | 특정 시점에 반드시 실행되는 핸들러 | O (보장) | 이벤트 발생 시 |
세 가지를 함께 사용하는 것이 가장 효과적이다:
CLAUDE.md → 코딩 스타일, 팀 규칙 (AI가 참고)
Skills → 반복 워크플로우 자동화 (AI가 판단해 적용)
Hooks → 보안 차단, 린트, 알림 (반드시 실행)
문서 탐색
참고 자료
- Hooks reference — Claude Code 공식 문서
- Claude Code Hooks Complete Guide (2026) — smartscope.blog
- Claude Code Hooks: 20+ Ready-to-Use Examples (2026) — DEV Community
- Tailor Gemini CLI to your workflow with hooks — Google Developers Blog