01-개념
01. 개념 — 결정적 자동화 지점
섹션 제목: “01. 개념 — 결정적 자동화 지점”hook은 “if-this-then-that”
섹션 제목: “hook은 “if-this-then-that””eesel의 정의가 가장 직관적이다:
“Hooks in Claude Code are custom, automated triggers that run shell commands at specific points during its operation. Think of them as ‘if this, then that’ rules for your coding assistant.”
의역: “Claude Code의 hook은 동작 중 특정 시점에 셸 명령을 자동 실행하는 커스텀 트리거다. 코딩 어시스턴트를 위한 ‘if this, then that’ 규칙으로 생각하라.”
여기서 핵심 단어는 **결정적(Deterministic)**이다. 모델 출력은 확률적이고 잊는다. hook은 매번 같은 시점에 같은 코드를 돌린다. 그래서 hook을 거는 곳은 “잊으면 사고 나는 곳”이다.
4가지 hook 종류 (공식 문서)
섹션 제목: “4가지 hook 종류 (공식 문서)”“There are four types of hook handlers: Command hooks, HTTP hooks, Prompt hooks, Agent hooks.”
- Command — 셸 명령 실행. 가장 일반적.
- HTTP — POST 엔드포인트 호출. 외부 시스템 통합.
- Prompt — Claude 자신에게 평가를 요청. 결정 보조.
- Agent — 검증용 서브에이전트 spawn.
대부분의 경우 Command면 충분하다. Prompt/Agent는 “조건이 모호하지만 자동으로 판단해야 할 때” 쓴다.
라이프사이클 이벤트
섹션 제목: “라이프사이클 이벤트”공식 문서가 나열하는 주요 이벤트:
| 이벤트 | 발화 시점 | 주된 용도 |
|---|---|---|
SessionStart | 새 세션 시작 | 컨텍스트 사전 주입 (이슈, 최근 커밋) |
UserPromptSubmit | 사용자 입력 직후 | 입력에 컨텍스트 추가, 위험 패턴 차단 |
PreToolUse | 도구 호출 직전 | 위험 명령 차단, 백업 |
PermissionRequest | 권한 요청 시 | 정책 자동화 |
PostToolUse | 도구 호출 성공 후 | 포맷팅, lint, 테스트, 알림 |
Stop | 응답 끝 | 자동 commit, 요약, 알림 |
PreCompact / PostCompact | /compact 전후 | 메모리 백업/복구 |
SessionEnd | 세션 종료 | 정리, 보존 |
SubagentStart / SubagentStop | 서브에이전트 라이프사이클 | 격리된 모니터링 |
Notification | 알림 발화 | Slack, OS 알림 |
FileChanged | 파일 변경 감지 | 외부 도구 트리거 |
eesel의 표는 이 중 가장 자주 쓰는 6개를 묶어 보여준다.
한계도 정확히 알기
섹션 제목: “한계도 정확히 알기”hook은 만능이 아니다. eesel이 정직하게 짚은 4가지:
- 기술 진입장벽 — 셸/Python을 모르면 못 쓴다.
- 개발 라이프사이클에 한정 — 비-개발 자동화에는 부적합.
- 유지·보안 부담 — 임의 명령 실행의 책임은 사용자.
- GUI 없음 — JSON과 코드.