[Claude Code #11] 훅(Hooks), 부탁 말고 장치로 자동화

CLAUDE.md에 “편집 후엔 꼭 포맷터를 돌려”라고 적어도, AI가 깜빡하는 날이 있습니다. 지시는 어디까지나 부탁이니까요.

반드시 일어나야 하는 일은 부탁이 아니라 장치로 만들어야 합니다. Claude Code에서 그 장치가 훅(hook)입니다.

훅은 사용자가 정의한 셸 명령입니다. Claude Code가 동작하는 특정 시점마다 자동으로 실행되고, 모델이 무엇을 고르든 상관없이 결정적으로 걸려요.

Claude Code 10편까지의 명령이 손으로 거는 것이었다면, 훅은 알아서 걸리는 자동 장치입니다.

첫 훅 5분 만에 만들기

훅은 settings.json의 hooks 블록에 적습니다. Claude가 입력을 기다릴 때 macOS 알림을 띄우는 예시를 볼게요.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"입력이 필요해요\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

저장하고 /hooks를 입력하면 등록된 훅 목록이 보입니다. 이 화면은 읽기 전용이라, 수정은 settings.json에서 직접 하거나 Claude에게 시키면 돼요.

어느 시점에 걸 수 있나

공식 훅 가이드 기준으로 자주 쓰는 이벤트는 이렇습니다.

• SessionStart: 세션이 시작·재개될 때
• UserPromptSubmit: 프롬프트를 보낸 직후, Claude가 처리하기 전
• PreToolUse: 도구 호출 직전. 호출을 차단할 수 있음
• PostToolUse: 도구 호출이 성공한 직후
• Stop: Claude의 턴이 끝날 때
• Notification: Claude가 입력을 기다릴 때

matcher로 대상을 좁힙니다. "matcher": "Edit|Write"라고 적으면 파일 편집 도구가 쓰일 때만 훅이 돕니다.

대표 활용 세 가지

편집 후 자동 포맷. PostToolUse에 Edit|Write matcher를 걸고 prettier를 실행합니다. AI가 어떤 파일을 고치든 포맷이 강제돼요.

보호 파일 차단. PreToolUse 훅이 특정 경로를 검사해 종료 코드 2로 끝나면 그 편집이 막힙니다. 아무 실패 코드가 아니라 꼭 2여야 해요. CLAUDE.md 지시와 달리 모델이 잊어도 뚫리지 않습니다.

끝났을 때 알림. 앞의 Notification 예시처럼, 터미널을 계속 지켜보지 않아도 됩니다.

판단이 필요하면 prompt 훅

셸 스크립트로 판별하기 어려운 조건도 있습니다. “요청한 작업이 다 끝났나?” 같은 것들이요.

이럴 땐 type: "prompt" 훅을 씁니다. 셸 명령 대신 판단 기준을 적어 두면, 기본 Haiku 모델이 yes/no로 판정해요.

Stop 이벤트에 prompt 훅을 걸면 “덜 끝났으면 계속 일해”가 됩니다. 사실 6편에서 다룬 /goal이 바로 이 구조의 세션 한정 래퍼예요.

훅은 셸을 그대로 실행합니다

강력한 만큼 위험도 같이 옵니다. 내 권한으로 임의 셸 명령이 자동 실행되는 구조니까요.

프로젝트 settings.json의 훅은 저장소를 신뢰하겠냐는 확인을 거칩니다. 남의 저장소를 열 때 이 확인을 가볍게 넘기지 마세요.

훅 명령 안에서 변수는 따옴표로 감싸고, 검증 없이 외부 입력을 실행하지 않는 기본기도 그대로 지켜야 합니다.

정리

훅은 “반드시 일어나야 하는 일”을 모델의 기억력에서 떼어 내 시스템에 맡기는 장치입니다.

포맷터 강제, 보호 파일 차단, 완료 알림부터 시작해 보세요. 판단이 필요한 조건은 prompt 훅으로 확장하면 됩니다.

다음 편에서는 정해진 간격으로 프롬프트를 반복 실행하는 /loop를 다룹니다. 훅이 이벤트 자동화라면, /loop는 시간 자동화예요.

출처 및 확인 기준

• Claude Code 공식 문서 — Automate actions with hooks (Anthropic, 2026-08-14 확인)
• Claude Code 공식 문서 — Hooks reference (Anthropic, 2026-08-14 확인)

이어서 읽기

Claude Code 시리즈

• 이전 편: [Claude Code #2] /plan 계획 모드, 수정 전에 설계부터 합의하기
• 이전 편: [Claude Code #1] /init, CLAUDE.md 자동 생성으로 시작하기

관련 주제

• [에이전트 설계 #1] 하네스 엔지니어링이란? 프롬프트 다음에 오는 것