Hook이 가능하게 하는 것
Hook은 코드를 수정하지 않고 Claude Code의 동작에 자동화 레이어를 덧붙이는 방법입니다. 대표적인 활용:
- 파일 저장 후 자동 포매팅
- 위험한 명령 차단 (
rm -rf,git push --force) - 응답이 끝날 때마다 안내 메시지 표시
- 컴팩션 전 중요 정보 보존
- LLM에게 “이 변경 안전한가?” 물어보고 차단
설정 위치
| 파일 | 범위 |
|---|---|
~/.claude/settings.json | 사용자 전체 |
.claude/settings.json | 프로젝트 (git 커밋) |
.claude/settings.local.json | 개인 로컬 (gitignore) |
기본 구조
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
}
]
}
]
}
}
자주 쓰는 이벤트
| 이벤트 | 시점 | 사용 사례 |
|---|---|---|
| PreToolUse | 도구 실행 전 | 위험 명령 차단, 권한 검증 |
| PostToolUse | 도구 실행 성공 후 | 자동 포매팅, 테스트 자동 실행 |
| PostToolUseFailure | 도구 실패 후 | 에러 로깅, 알림 |
| PermissionRequest | 권한 확인이 필요할 때 | 승인 여부 자동 판단 |
| UserPromptSubmit | 사용자 입력 시 | 프롬프트 분석, 컨텍스트 주입 |
| Stop | Claude가 응답을 마칠 때(매 턴) | 작업 완료 여부 점검, 안내 메시지 |
| PreCompact | 컴팩션 직전 | 중요 정보 별도 저장 |
| SessionStart | 세션 시작 또는 재개 | 환경 점검, 초기 메시지 |
| SessionEnd | 세션 종료 | 정리 작업 (출력 메시지는 표시되지 않음) |
이 밖에도 SubagentStart, SubagentStop, StopFailure, FileChanged, PreModelSwitch 등 많은 이벤트가 있습니다. 전체 목록은 Hooks reference에서 확인할 수 있습니다.
다섯 가지 훅 타입
1. command — 셸 명령 실행
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
}
stdin으로 이벤트 JSON을 받습니다. jq로 필요한 필드를 추출해 사용합니다.
2. http — URL로 POST 요청
{
"type": "http",
"url": "http://localhost:8080/hooks/pre-tool-use",
"headers": { "Authorization": "Bearer $MY_TOKEN" },
"allowedEnvVars": ["MY_TOKEN"]
}
이벤트 JSON을 POST 본문으로 보내고, 응답 본문을 command 훅의 JSON 출력과 같은 형식으로 해석합니다. 헤더에 환경변수를 넣으려면 allowedEnvVars에 이름을 등록해야 합니다.
3. mcp_tool — MCP 도구 호출
{
"type": "mcp_tool",
"server": "my_server",
"tool": "security_scan",
"input": { "file_path": "${tool_input.file_path}" }
}
설정된 MCP 서버의 도구를 직접 호출합니다. 도구의 텍스트 결과는 command 훅의 stdout처럼 처리됩니다.
4. prompt — LLM에 질문
{
"type": "prompt",
"prompt": "이 명령이 시스템에 위험한 변경을 가하는지 판단합니다: $ARGUMENTS. 안전하면 {\"ok\": true}, 위험하면 {\"ok\": false, \"reason\": \"이유\"} 형식의 JSON으로 답합니다."
}
$ARGUMENTS 자리에 훅 입력 JSON이 들어갑니다. 모델은 ok와 reason 필드를 가진 JSON으로 답하고, ok: false일 때의 동작은 이벤트마다 다릅니다. 기본 모델은 Claude Code가 백그라운드 작업에 쓰는 모델이며, model 필드로 바꿀 수 있습니다.
5. agent — 에이전트 실행
{
"type": "agent",
"prompt": "변경된 파일에 대해 단위 테스트가 함께 추가됐는지 검증"
}
Read, Grep, Glob 같은 도구로 조건을 확인한 뒤 판단을 돌려주는 서브에이전트를 실행합니다. 토큰 비용이 더 크고, 공식 문서는 이 타입을 실험적 기능으로 분류합니다.
실전 예: 위험 명령 차단
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "다음 셸 명령이 데이터를 영구 삭제하거나 되돌리기 어려운 변경을 하는지 판단합니다: $ARGUMENTS. 그렇지 않으면 {\"ok\": true}, 그렇다면 {\"ok\": false, \"reason\": \"이유\"}로 답합니다.",
"continueOnBlock": true
}
]
}
]
}
}
PreToolUse에서 ok: false가 나오면 도구 호출이 거부됩니다. 기본값은 그 자리에서 턴을 끝내는 것이고, continueOnBlock: true를 주면 거부 이유를 Claude에게 돌려줘 다른 방법으로 작업을 이어 가게 합니다.
command 훅이나 http 훅으로 차단 규칙을 만들 때는 "onFailure": "block"(v2.1.295 이상)을 함께 지정할 수 있습니다. 훅이 시작되지 않거나 시간 초과로 실패해도 동작을 통과시키지 않고 차단합니다.
실전 예: 파일 저장 후 자동 포매팅
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; case \"$f\" in *.ts|*.tsx|*.js|*.jsx|*.json|*.md) prettier --write \"$f\";; esac; } 2>/dev/null || true"
}
]
}
]
}
}
확장자별로 적용 도구를 다르게 할 수 있습니다.
실전 예: 응답이 끝날 때 안내 메시지
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "echo '{\"systemMessage\": \"응답 완료 — 변경된 파일 확인 권장\"}'"
}
]
}
]
}
}
Stop은 세션이 끝날 때가 아니라 Claude가 응답을 마칠 때마다 실행됩니다. 훅이 systemMessage를 담은 JSON을 출력하면 사용자에게 메시지가 표시됩니다. 세션 종료 시점에 실행되는 SessionEnd는 systemMessage 같은 JSON 출력을 버리므로, 메시지 표시가 아니라 정리 작업에만 씁니다.
디버깅 절차
- JSON 문법 —
jq . settings.json으로 유효성 확인 - 매처 패턴 —
Write|Edit처럼 정확한 도구명 사용 - 명령 직접 테스트 —
echo '{"tool_input":{"file_path":"test.ts"}}' | <훅 명령> - 등록 확인 —
/hooks를 열면 설정된 훅과 정의된 위치(사용자, 프로젝트, 로컬 설정, 플러그인 등)를 볼 수 있습니다. settings 파일을 직접 고치면 file watcher가 자동으로 반영합니다. - debug 모드 —
claude --debug로 훅 실행 로그 확인 - 일시 비활성화 — 훅 때문에 문제가 생기는지 확인하려면 settings에
"disableAllHooks": true를 지정합니다. 개별 훅만 끄는 방법은 없으므로 특정 훅은 설정에서 삭제합니다.
hookify 도구 활용
hookify는 자연어로 훅을 생성해주는 플러그인입니다. 직접 JSON을 작성하기 부담스러우면 hookify로 초안을 만들고 settings.json에 적용하는 방식이 빠릅니다.
다음 단계
- hookify — 자연어로 훅 정의
- Claude Code Setup — 프로젝트에 맞는 훅 자동 추천
- CLAUDE.md 잘 쓰는 법 — 훅과 CLAUDE.md 규칙의 역할 분리
- Hooks reference — 전체 이벤트, 입력 필드, 결정 제어 방식