Claude Code Hooks 완전 가이드 2026 — 라이프사이클 자동화의 모든 것

PostToolUse 훅 하나 설정했더니 Prettier를 수동으로 돌리는 일이 사라졌다. 파일을 편집할 때마다 자동으로 포맷팅이 걸린다. 설정에 3분, 절약한 시간은 하루 20번 이상의 수동 실행.

Claude Code Hooks(훅)란, 코딩 에이전트의 특정 라이프사이클 시점에 사용자가 정의한 셸 명령을 자동 실행하는 시스템이다. Git Hooks와 비슷한 개념이지만, 대상이 Git이 아니라 Claude Code 자체다. LLM의 판단에 의존하지 않고, 결정론적(deterministic)으로 동작한다는 점이 핵심이다.

이 시리즈 Part 1에서 다룬 MCP가 Claude Code의 능력을 확장하는 도구라면, Hooks는 Claude Code의 행동을 통제하는 안전장치에 가깝다. 확장과 통제, 이 둘이 합쳐져야 프로덕션에서 쓸 수 있는 에이전트가 된다.

22개 이벤트, 어디에 훅을 걸 수 있나

Claude Code의 라이프사이클에는 22개 이상의 이벤트가 존재한다. 세션이 시작될 때 발동하는 SessionStart, 사용자 프롬프트가 제출되기 직전의 UserPromptSubmit, 도구 실행 전후의 PreToolUse와 PostToolUse, 권한 요청 시의 PermissionRequest, Claude가 응답을 마칠 때의 Stop까지. 서브에이전트의 생명주기를 관리하는 SubagentStart와 SubagentStop, 컨텍스트 압축 전후의 PreCompact와 PostCompact도 있다.

실무에서 가장 자주 쓰는 건 이 셋이다. PreToolUse는 도구 실행을 사전에 차단할 수 있어서 보안 게이트로 쓴다. PostToolUse는 도구 실행 직후 후처리를 걸 수 있어서 자동 포맷팅에 쓴다. Notification은 Claude가 알림을 보낼 때 데스크톱 알림으로 연결해서, 터미널을 계속 쳐다보지 않아도 되게 만든다.

4가지 훅 타입과 설정법

훅에는 command, http, prompt, agent 네 가지 타입이 있다.

command 타입이 가장 흔하다. 셸 명령을 직접 실행한다. 예를 들어, Edit이나 Write 도구가 실행된 직후 Prettier를 돌리는 설정은 이렇다.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
    }]
  }
}

matcher는 정규식 패턴으로, 특정 도구 이름이 매칭될 때만 훅이 발동한다. 위 예시에서는 Edit 또는 Write 도구가 실행된 후에만 Prettier가 돌아간다.

http 타입은 지정한 URL에 POST 요청을 보낸다. 외부 서비스 연동에 쓴다. prompt 타입은 단일 턴 LLM 평가로, yes/no 판단을 내린다. agent 타입은 멀티턴 서브에이전트를 띄워서 검증 작업을 수행한다. prompt와 agent 타입은 "이 작업이 정말 완료됐는가?"를 확인하는 Stop 훅에서 강력하다.

exit code가 동작을 결정한다. exit 0이면 진행, exit 2이면 해당 액션을 차단하고 stderr 내용을 Claude에게 피드백으로 전달한다. 그 외 코드는 진행하되 stderr를 로그에 남긴다.

실전 사례 — 내가 쓰는 3가지 훅

첫째, .env 파일 보호다. PreToolUse 훅에 간단한 스크립트를 걸었다. 파일 경로에 .env가 포함되면 exit 2를 반환해서 편집 자체를 차단한다. 실수로 시크릿이 수정되거나 커밋될 걱정이 없다.

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path // empty')
if [[ "$FILE" == *".env"* ]]; then
  echo "BLOCKED: .env 파일 편집 금지" >&2
  exit 2
fi
exit 0

둘째, 데스크톱 알림이다. Notification 이벤트에 macOS의 osascript를 연결했다. Claude가 입력을 기다리거나 작업이 끝났을 때 알림이 뜨니까, 다른 작업을 하다가도 바로 돌아올 수 있다.

셋째, 컨텍스트 재주입이다. SessionStart 이벤트에 compact 매처를 걸어서, 컨텍스트 압축이 발생한 후 세션이 재개될 때 핵심 컨텍스트를 자동으로 다시 주입한다. 긴 세션에서 Claude가 맥락을 잃는 문제를 방지한다.

설정 파일은 세 곳에 둘 수 있다. ~/.claude/settings.json은 글로벌 설정으로 모든 프로젝트에 적용된다. .claude/settings.json은 프로젝트별 설정으로 버전 관리에 포함할 수 있다. .claude/settings.local.json은 프로젝트별이지만 gitignore되는 로컬 전용 설정이다.

Git Hooks와 뭐가 다른가

Git Hooks는 커밋, 푸시, 머지 같은 Git 이벤트에 반응한다. Claude Code Hooks는 AI 에이전트의 행동 자체에 반응한다. "파일을 편집하려고 한다", "도구를 실행하려고 한다", "응답을 마치려고 한다" 같은 시점에 개입할 수 있다.

Git Hooks가 코드의 품질 게이트라면, Claude Code Hooks는 AI 에이전트의 행동 게이트다. 둘은 대체 관계가 아니라 보완 관계다. pre-commit 훅으로 린트를 돌리고, PreToolUse 훅으로 .env 편집을 차단하는 식으로 함께 쓴다.

이 시리즈의 다음 편에서는 Claude Code의 Agent 시스템을 다룬다. Hooks로 행동을 통제하고, Agent로 작업을 분배하는 것까지 갖추면, Claude Code는 단순한 코딩 도우미가 아니라 신뢰할 수 있는 자동화 엔진이 된다.

---

가장 좋은 자동화는, 한번 설정하면 존재를 잊어버리는 자동화다.

참고 자료

• Claude Code Hooks Guide
• Claude Code Hooks Reference
• Prettier
• jq