225 lines
7.1 KiB
Markdown
225 lines
7.1 KiB
Markdown
# 훅 (Hooks)
|
|
|
|
> Claude가 도구를 사용하거나 세션 마일스톤에 도달할 때 셸 커맨드, HTTP 요청, 프롬프트를 자동으로 실행합니다.
|
|
|
|
훅은 Claude Code의 도구 라이프사이클에 자동화를 연결합니다. Claude가 파일을 읽거나, bash 커맨드를 실행하거나, 응답을 완료할 때 설정된 훅이 자동으로 실행됩니다. 코드 스타일 강제, 테스트 실행, 도구 사용 로깅, Claude가 할 수 있는 작업 제어에 훅을 사용하세요.
|
|
|
|
## 훅 작동 방식
|
|
|
|
훅은 특정 **이벤트**에 바인딩된 커맨드(셸 스크립트, HTTP 엔드포인트, LLM 프롬프트)입니다. 이벤트가 발생하면 Claude Code가 매칭된 모든 훅을 실행하고 종료 코드와 출력을 사용해 다음 동작을 결정합니다.
|
|
|
|
각 훅의 입력은 무슨 일이 일어났는지 설명하는 JSON 객체입니다.
|
|
|
|
**종료 코드 의미:**
|
|
| 종료 코드 | 의미 |
|
|
|----------|------|
|
|
| `0` | 성공. stdout이 Claude에게 표시될 수 있음(이벤트별 다름) |
|
|
| `2` | 차단 또는 주입. stderr를 Claude에게 표시하고(`PreToolUse`) 도구 호출 방지 |
|
|
| 기타 | stderr를 사용자에게만 표시; 실행 계속 |
|
|
|
|
## 훅 이벤트
|
|
|
|
| 이벤트 | 설명 |
|
|
|--------|------|
|
|
| **PreToolUse** | 모든 도구 호출 직전에 발생. 도구 입력 검사, 승인/차단, 입력 수정 가능. 종료코드 `2` → 도구 호출 차단 |
|
|
| **PostToolUse** | 모든 성공적인 도구 호출 후 발생. 도구 출력 관찰 또는 Claude가 처리할 컨텍스트 주입 가능 |
|
|
| **PostToolUseFailure** | 도구 호출이 오류로 종료될 때 발생 |
|
|
| **Stop** | Claude가 응답을 종료하기 직전에 발생. 종료코드 `2` → stderr를 Claude에게 표시하고 대화 계속 |
|
|
| **SubagentStop** | 서브에이전트가 결론 내리기 직전에 발생 (`Stop`과 동일하지만 서브에이전트용) |
|
|
| **SubagentStart** | 새 서브에이전트가 시작될 때 발생 |
|
|
| **SessionStart** | 세션 시작, 재개, `/clear`, `/compact` 후에 발생 |
|
|
| **UserPromptSubmit** | 사용자가 프롬프트를 제출할 때 발생. 종료코드 `2` → 프롬프트 차단 |
|
|
| **PreCompact** | 컨텍스트 컴팩션 시작 직전에 발생. 종료코드 `2` → 컴팩션 차단 |
|
|
| **PostCompact** | 컴팩션 완료 후 발생 |
|
|
| **Setup** | 저장소 초기화(`init`) 및 주기적 유지보수(`maintenance`) 시 발생 |
|
|
| **PermissionRequest** | 권한 다이얼로그가 표시될 때 발생. 프로그래밍 방식으로 승인/거부 가능 |
|
|
| **PermissionDenied** | 도구 호출이 거부된 후 발생 |
|
|
| **Notification** | 권한 프롬프트, 유휴 프롬프트, 인증 성공 등의 알림 시 발생 |
|
|
| **CwdChanged** | 작업 디렉토리 변경 후 발생 |
|
|
| **FileChanged** | 감시 중인 파일이 변경될 때 발생 |
|
|
| **SessionEnd** | 세션이 종료될 때 발생 |
|
|
| **ConfigChange** | 세션 중 설정 파일이 변경될 때 발생 |
|
|
|
|
## 훅 설정
|
|
|
|
세션 내에서 `/hooks`를 실행해 훅 설정 메뉴를 열 수 있습니다. 훅은 설정 파일의 `hooks` 필드에 저장됩니다:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PostToolUse": [
|
|
{
|
|
"matcher": "Write",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "prettier --write $CLAUDE_FILE_PATH"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"Stop": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "echo 'Session complete' >> ~/.claude-log.txt"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
각 이벤트는 **매처 객체** 배열에 매핑됩니다:
|
|
- `matcher` (선택사항) — 이벤트의 매칭 가능한 필드와 매칭되는 문자열 패턴
|
|
- `hooks` — 매처가 일치할 때 실행할 훅 커맨드 배열
|
|
|
|
빈 또는 없는 `matcher`는 해당 이벤트의 모든 입력과 일치합니다.
|
|
|
|
## 훅 커맨드 타입
|
|
|
|
**셸 커맨드 (`type: "command"`):**
|
|
```json
|
|
{
|
|
"type": "command",
|
|
"command": "npm test",
|
|
"timeout": 60,
|
|
"shell": "bash",
|
|
"async": false
|
|
}
|
|
```
|
|
|
|
필드:
|
|
- `command` — 실행할 셸 커맨드 (필수)
|
|
- `timeout` — 타임아웃(초)
|
|
- `shell` — `"bash"` (기본) 또는 `"powershell"`
|
|
- `async` — 백그라운드에서 실행 (출력 무시)
|
|
- `once` — 한 번 실행 후 자동으로 훅 제거
|
|
- `if` — 조건부로 훅 건너뛰기 위한 권한 규칙 구문
|
|
- `statusMessage` — 훅 실행 중 스피너에 표시되는 커스텀 메시지
|
|
|
|
**HTTP 요청 (`type: "http"`):**
|
|
```json
|
|
{
|
|
"type": "http",
|
|
"url": "https://hooks.example.com/claude-event",
|
|
"headers": {
|
|
"Authorization": "Bearer $MY_TOKEN"
|
|
},
|
|
"allowedEnvVars": ["MY_TOKEN"],
|
|
"timeout": 10
|
|
}
|
|
```
|
|
|
|
Claude Code가 훅 입력 JSON을 URL에 POST합니다.
|
|
|
|
**LLM 프롬프트 (`type: "prompt"`):**
|
|
```json
|
|
{
|
|
"type": "prompt",
|
|
"prompt": "이 bash 커맨드에 보안 문제가 있는지 확인하세요: $ARGUMENTS. 문제가 있으면 설명하고 코드 2로 종료하세요.",
|
|
"model": "claude-haiku-4-5",
|
|
"timeout": 30
|
|
}
|
|
```
|
|
|
|
**에이전트 훅 (`type: "agent"`):**
|
|
```json
|
|
{
|
|
"type": "agent",
|
|
"prompt": "단위 테스트가 실행되고 통과했는지 확인하세요.",
|
|
"timeout": 60
|
|
}
|
|
```
|
|
|
|
도구 접근 권한이 있는 짧은 에이전틱 루프로 실행됩니다. 파일을 읽거나 커맨드를 실행해야 하는 검증 작업에 유용합니다.
|
|
|
|
## 훅 예시
|
|
|
|
**파일 편집 후 자동 포맷:**
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PostToolUse": [
|
|
{
|
|
"matcher": "Write",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**위험한 커맨드 차단:**
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo '차단: rm -rf는 허용되지 않습니다' >&2; exit 2; fi"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**모든 도구 사용 로깅:**
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PostToolUse": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) $CLAUDE_TOOL_NAME\" >> ~/.claude-tool-log.txt",
|
|
"async": true
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**디렉토리 변경 시 환경 변수 주입:**
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"CwdChanged": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "if [ -f .envrc ]; then grep '^export ' .envrc >> \"$CLAUDE_ENV_FILE\"; fi"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## 훅 vs 스킬
|
|
|
|
| 기능 | 훅 | 스킬 |
|
|
|------|-----|------|
|
|
| 실행 시점 | 도구 이벤트에 자동 | Claude나 사용자가 `/skill-name`으로 명시적 호출 |
|
|
| 목적 | 부작용, 게이팅, 관찰 | 온디맨드 워크플로우와 기능 |
|
|
| 설정 | 설정 JSON | `.claude/skills/`의 마크다운 파일 |
|
|
|
|
자동으로 발생해야 하는 것(포맷팅, 로깅, 강제)에는 훅을 사용하고, 의도적으로 트리거하려는 반복 가능한 워크플로우에는 스킬을 사용하세요.
|