이 글은 JudyAI Lab의 AI 엔지니어링 시리즈 중 하나입니다 — 100편 이상 발행된 가이드, 60개국 5,000명 이상의 주간 독자가 읽는 콘텐츠로, AI 에이전트·트레이딩 시스템·콘텐츠 파이프라인의 실전 운영에 초점을 둡니다.
Claude Code Hooks 완전 가이드 — AI로 개발 워크플로우를 자동화하는 방법
이미 Claude Code로 프로젝트를 개발하고 계시다면, 이런 생각을 해보셨을 겁니다. AI가 특정 동작을 실행할 때 자동으로 무언가를 할 수 있지 않을까? 예를 들어, 코드를 작성한 후 자동으로 포맷팅하거나, 위험한 명령어를 실행하기 전에 차단한다거나요.
정답은 바로 Hooks입니다.
Hooks는 Claude Code의 .claude/settings.json에 숨겨져 있는 강력한 기능으로, AI의 핵심 동작 시점(도구 실행 전, 도구 실행 후, 대화 종료 전)에 사용자 정의 스크립트를 삽입하여 자동화된 품질 게이트, 보안 검사, 학습 회고까지 구현할 수 있습니다.
2026년 11월 업데이트: 공식 문서(Hooks reference)에 따르면 이 글을 쓴 뒤 Hooks가 크게 확장되었습니다. 아래 사항은 원문과 다르며 이쪽이 우선합니다.
- 이벤트는 3가지가 아니라 33가지입니다.
SessionStart,UserPromptSubmit,PermissionRequest,PostToolUseFailure,SubagentStop,PreCompact,SessionEnd등이 있고, 이 글은 자주 쓰는 PreToolUse / PostToolUse / Stop만 다룹니다.type은command만이 아니라command,http,mcp_tool,prompt,agent를 지원합니다(agent는 실험적 기능으로 표시).- Hook 입력은 JSON이며 command 타입에서는 stdin으로 전달됩니다. 문서화된
$TOOL_INPUT환경 변수는 없으므로 아래 예제를 stdin 읽기 방식으로 바꿨습니다.- 동작을 차단하려면 반드시
exit 2여야 합니다(stderr 내용이 Claude에게 전달됨).exit 1은 비차단 오류라 동작이 그대로 실행됩니다.- command 타입의 기본 타임아웃은 600초입니다(prompt 30초, agent 60초).
Stop은 Claude가 응답을 마칠 때 트리거되며, 세션 종료 시에는SessionEnd가 트리거됩니다.
이 글에서는 Hooks의 기본 개념부터 설정 방법, 그리고 실제 사용 가능한 세 가지 예제까지 안내합니다.
Hooks란 무엇인가요?
Claude Code의 Hooks는 세 가지로 나뉩니다.
1. PreToolUse — 도구 실행 전 트리거
Claude Code가 도구(Read, Bash, Write, Edit 등)를 호출하기 전에 실행됩니다.
주요 용도:
- 위험한 명령어 차단(
rm -rf, 파괴적인 git 작업) - 권한 확인
- 필수 파일 검증
2. PostToolUse — 도구 실행 후 트리거
도구가 실행 완료된 후에 실행됩니다. 이 시점에서 도구의 출력 결과를 확인할 수 있습니다.
주요 용도:
- 코드 포맷팅(black, prettier)
- 문법 검사
- 자동화 테스트
- 배포 후 헬스 체크
3. Stop — 대화 종료 전 트리거
원문은 사용자가 exit를 입력하거나 Claude Code가 대화 종료를 결정할 때 트리거된다고 썼으나, 현재 공식 문서 기준으로 Stop은 Claude가 응답을 마칠 때 트리거되고 세션 종료는 SessionEnd 이벤트가 담당합니다.
주요 용도:
- Session 종료 전 학습 요약
- 비용 추적 통계
- 미완료 의사결정 알림
왜 Hooks가 필요한가요?
Hooks가 가장 큰 가치를 발휘하는 세 가지 시나리오를 소개합니다.
품질 게이트(Quality Gate)
“Commit 전에 매번 자동으로 코드 품질을 검사한다” — 과거에는 CI/CD pipeline이 필요했지만, 이제는 Hook 하나로 가능합니다.
보안 검사
Claude Code는 강력하지만, 위험한 명령어를 실행할 수도 있습니다. PreToolUse Hook을 사용하면 rm -rf 실행 전에 확인 팝업을 띄우거나, DROP TABLE을 직접 차단할 수 있습니다.
자동화 기록 및 학습
매번 Session이 끝날 때 자동으로 비용 통계와 학습 요약을 실행하면, AI 협업을 기억이 있는 시스템으로 만들 수 있습니다.
설정 방법
프로젝트 또는 전역의 .claude/settings.json에 hooks 필드를 추가합니다.
| |
각 Hook은 다음 요소로 구성됩니다.
| 필드 | 설명 |
|---|---|
matcher | 어떤 도구에서 트리거할지 지정. 예: Bash, `Edit |
hooks[].type | command, http, mcp_tool, prompt, agent |
hooks[].command | 실행할 명령어. 입력 JSON은 stdin으로 전달 |
hooks[].statusMessage | 실행 시 Claude Code에 표시되는 안내 텍스트(선택) |
hooks[].timeout | 타임아웃 초(선택, command 타입 기본값 600초) |
실제 예제
예제 1: PostToolUse — Python 파일 작성 후 자동 Black 포맷팅
Edit 또는 Write로 .py 파일을 수정한 후 자동으로 black 포맷팅을 실행합니다.
| |
| |
예제 2: PreToolUse — Bash 명령어 보안 차단
Bash 명령어를 실행하기 전에 위험한 작업인지 확인합니다.
| |
| |
예제 3: Stop — Session 종료 전 자동 학습
대화가 끝나기 전에 이번 Session의 학습 요약과 비용 통계를 자동 생성합니다.
| |
| |
고급 활용법
1. Matcher 와일드카드
| Matcher | 설명 |
|---|---|
* | 모든 도구 |
Bash | Bash만 |
| `Edit | Write` |
| `Read | Glob |
2. statusMessage — 친절한 안내
| |
실행 시 Claude Code 인터페이스에 이 텍스트가 표시되어, 현재 무엇이 진행 중인지 알 수 있습니다.
3. timeout — 무한 대기 방지
| |
command 타입의 기본값은 600초입니다(원문의 30초는 더 이상 맞지 않음). 포맷팅 도구나 네트워크 작업에는 더 짧은 timeout을 명시하는 것이 좋습니다.
4. 여러 Hook 연결
동일한 트리거 포인트에 여러 Hook을 연결할 수 있습니다.
| |
마치며
Hooks는 Claude Code에서 가장 과소평가된 기능 중 하나입니다. Hooks를 통해 AI는 “수동적으로 질문에 답하는 도구"에서 “개발 워크플로우에 능동적으로 참여하는 자동화 파트너"로 변모합니다.
간단한 코드 포맷팅부터 복잡한 보안 게이트와 학습 시스템까지, Hooks의 가능성은 여러분의 개발 워크플로우가 무엇을 필요로 하느냐에 달려 있습니다.
다음 글 예고: Claude Code에서 MCP(Model Context Protocol)를 결합하여 더욱 강력한 AI 워크플로우를 구축하는 방법을 다룰 예정입니다. 기대해 주세요.
참고 자료
- Hooks reference — Claude Code 공식 문서 — PreToolUse, PostToolUse, Stop 세 가지 Hook의 전체 API 레퍼런스 및 매개변수 설명
- Claude Code settings — 공식 설정 문서 —
settings.json설정 형식, 계층 덮어쓰기 규칙 및 환경 변수 구성 - Intercept and control agent behavior with hooks — Claude API Docs — Agent SDK 수준의 Hook 인터셉트 및 제어 동작 문서
- Claude Code Hooks Mastery — GitHub — 커뮤니티에서 정리한 Hooks 실전 예제 및 고급 패턴 모음
핵심 수치
- 3 個 Hooks 유형 (PreToolUse, PostToolUse, Stop)
- command 타입 기본 timeout 600초 (2026년 11월 공식 문서 기준)
- 60 個 국가 독자 분포
