Claude Code 훅(hooks) 활용법 — AI에게 부탁하지 말고 규칙으로 거세요

“파일 고치면 꼭 포맷터 돌려줘”라고 AI에게 부탁해 본 적 있으신가요? 처음엔 잘 지키다가 대화가 길어지면 잊습니다. AI의 기억에 맡긴 부탁이기 때문이에요. 훅(hook)은 이걸 부탁이 아니라 규칙으로 바꾸는 장치입니다 — 정해진 시점이 오면 AI의 판단과 무관하게 무조건 실행됩니다.

결론 요약

훅 = Claude Code의 특정 시점(도구 실행 전후, 작업 종료 등)에 자동 실행되는 셸 명령
설정은 /hooks 명령 또는 settings.json 파일 — 프로젝트별·계정 전역 둘 다 가능
대표 용도 3가지: 자동 포맷 · 위험 명령 차단 · 완료 알림
강력한 만큼 조심: 훅은 내 컴퓨터에서 그대로 실행되니 신뢰할 수 있는 명령만

🪝 1. 훅이 뭔가 — “무조건 실행”이라는 게 핵심

Claude Code는 작업 중에 여러 시점을 지납니다. 도구(파일 수정, 터미널 명령)를 실행하기 직전과 직후, 세션이 시작될 때, 응답이 끝날 때. 훅은 이 시점들에 내가 정한 명령을 걸어두는 것입니다.

CLAUDE.md에 적은 지침이나 채팅으로 한 부탁은 AI가 “따르려고 노력”하는 것이고, 훅은 시스템이 “반드시 실행”하는 것 — 이 차이가 전부입니다. 일관성이 생명인 일(포맷, 검사, 기록)은 훅에 맡기는 게 맞습니다.

훅이 끼어드는 시점 — 도구 실행 전·후, 작업 종료 (직접 제작)

📍 2. 어느 시점에 걸 수 있나

자주 쓰는 이벤트만 추리면:

PreToolUse — 도구 실행 직전. 검사하고, 조건에 안 맞으면 차단할 수 있습니다
PostToolUse — 도구 실행 직후. 파일을 고쳤으면 포맷터를 돌리는 식의 후처리
Stop — Claude가 응답을 마쳤을 때. “작업 끝났다” 알림에 제격
SessionStart — 세션 시작 시. 환경 준비나 상태 출력
Notification — Claude가 승인을 기다리거나 알림을 보낼 때

⚙️ 3. 설정하는 법 — 파일 수정 후 자동 포맷 예시

Claude Code 안에서 /hooks를 치면 설정 UI가 열립니다. 직접 파일로 관리하려면 프로젝트의 .claude/settings.json에 이렇게 적습니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write ." }
        ]
      }
    ]
  }
}

읽는 법은 간단합니다. “Edit이나 Write 도구가 실행된 후에(PostToolUse), 이 명령을 돌려라.” 이제 Claude가 파일을 고칠 때마다 포맷터가 무조건 따라 돕니다 — 부탁도, 확인도 필요 없이요.

🧰 4. 실전 레시피 3가지

① 수정 후 자동 포맷·검사 — 위 예시 그대로. 포맷터 대신 린터·테스트를 걸어도 됩니다. “AI가 고친 코드가 규칙에 맞나”를 사람이 아니라 도구가 확인하게 되죠.

② 위험 명령 가드 — PreToolUse에 검사 스크립트를 걸고, 스크립트가 종료 코드 2로 끝나면 그 도구 실행 자체가 차단됩니다. 예를 들어 “프로덕션 DB 주소가 명령에 들어 있으면 무조건 막기” 같은 안전장치를 만들 수 있습니다.

③ 작업 완료 알림 — Stop 이벤트에 알림 명령을 걸면, 긴 작업을 시켜두고 다른 일을 하다가 끝나는 순간을 알 수 있습니다. 저처럼 AI에게 검증 루프를 맡겨두는 사용이라면 체감이 큽니다.

⚠️ 5. 주의 — 강력한 만큼 위험도 같이 옵니다

훅은 내 컴퓨터에서 셸 명령을 그대로 실행합니다. 그래서 두 가지만 기억하세요.

인터넷에서 복사한 훅 설정을 그대로 붙여넣지 마세요. 어떤 명령인지 이해한 것만
훅에 넣는 스크립트는 내가 만들었거나 신뢰하는 것만 — AI 응답을 그대로 훅에 넣는 건 금물

그리고 구분 하나: 매번 실행할 필요가 없는 “필요할 때 부르는 절차”는 훅이 아니라 커스텀 커맨드(스킬)가 맞습니다. 강제해야 하면 훅, 부르고 싶으면 커맨드.

🎯 시작 코스

/hooks를 열어 구조 구경 (1분)
첫 훅은 부담 없는 것부터 — Stop에 완료 알림 걸기
익숙해지면 PostToolUse 자동 포맷 → PreToolUse 가드 순으로 확장

Claude Code 기본 사용법과 MCP 연결까지 되어 있다면, 훅은 여러분의 AI 작업 환경을 “매번 시키는 도구”에서 “알아서 지켜지는 시스템”으로 바꿔주는 마지막 조각입니다.

기준: 2026-09-07. 이벤트 이름·설정 스키마는 버전에 따라 달라질 수 있으니 공식 문서(code.claude.com/docs)를 함께 확인하세요. 다이어그램은 직접 제작했습니다.