클로드 코드 훅(Hooks) 설정법: 파일 수정할 때마다 자동 포맷·검사 실행

CLAUDE.md에 "파일을 고친 뒤에는 포매터를 실행할 것"이라고 적어 두었는데, 클로드가 가끔 잊어버렸습니다. 대부분은 지키지만 "대부분"으로는 부족한 규칙이 있죠. 이럴 때 쓰는 것이 훅(Hooks)입니다. 훅은 지침이 아니라 자동으로 실행되는 장치입니다.

훅이란?

훅은 클로드 코드가 작업하는 특정 시점에 내가 정한 셸 명령을 자동 실행하는 기능입니다.

주요 훅 이벤트

설정 파일 위치

예시 1. 파일 수정 후 자동 포맷

파이썬 파일을 고칠 때마다 포매터를 실행하는 설정입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff format ."
          }
        ]
      }
    ]
  }
}

• matcher: 어떤 도구에 반응할지 (여기서는 파일 수정·작성)
• command: 실행할 셸 명령

실제로는 수정된 파일만 포맷하는 편이 빠릅니다. 훅 명령은 표준 입력(stdin)으로 어떤 도구가 어떤 파일을 다뤘는지 JSON 정보를 받으므로, 스크립트에서 파일 경로를 읽어 처리할 수 있습니다.

예시 2. 보호 파일 수정 막기

배포 설정이나 빌드 결과물 폴더는 클로드가 건드리지 않게 하고 싶을 때입니다. PreToolUse 훅에서 검사 스크립트를 실행하고, 막아야 하면 종료 코드 2로 끝내면 해당 작업이 차단되고 이유가 클로드에게 전달됩니다.

# .claude/hooks/protect.py
import json, sys

data = json.load(sys.stdin)
path = data.get("tool_input", {}).get("file_path", "")
if "/public/" in path.replace("\\", "/") or path.endswith("deploy.yaml"):
    print("public/ 폴더와 deploy.yaml은 수정할 수 없습니다. 원본 파일을 수정하세요.", file=sys.stderr)
    sys.exit(2)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "python .claude/hooks/protect.py" }]
      }
    ]
  }
}

이 블로그에서 실제로 쓰는 방식입니다. 빌드 결과물인 public/을 직접 고치려는 시도가 차단되고, 클로드가 메시지를 보고 원본 템플릿을 수정하는 쪽으로 방향을 바꿉니다.

예시 3. 작업 완료 알림

긴 작업을 맡겨 두고 다른 일을 할 때, 클로드가 응답을 마치면 알림을 받도록 Stop 훅을 걸 수 있습니다. 운영체제의 알림 명령이나 소리 재생 명령을 등록하면 됩니다.

훅을 쓸 때 주의할 점

1. 직접 이해한 명령만: 훅은 내 권한으로 셸 명령을 자동 실행합니다. 인터넷에서 복사한 설정을 그대로 쓰지 마세요.
2. 빠른 명령으로: 파일을 고칠 때마다 실행되는 훅이 30초씩 걸리면 작업이 느려집니다.
3. 실패 처리: 훅 명령이 실패했을 때 어떻게 되는지 확인하세요. 차단 목적이 아니라면 실패해도 작업이 계속되게 하는 편이 낫습니다.
4. 설정 확인: /hooks 명령으로 현재 적용된 훅을 확인할 수 있습니다.

한 줄씩 정리

1. 훅은 특정 시점에 셸 명령을 자동 실행해 규칙을 강제하는 기능입니다.
2. PostToolUse로 자동 포맷, PreToolUse와 종료 코드 2로 위험한 작업 차단을 구현합니다.
3. 직접 이해한 빠른 명령만 등록하고, /hooks로 적용 상태를 확인하세요.

💬 규칙은 CLAUDE.md, 강제는 훅

훅을 쓰기 전에는 클로드에게 "포맷 실행했어?"라고 확인하는 게 일이었습니다. 지금은 신경 쓸 필요가 없습니다. 제 기준은 이렇습니다. 판단이 필요한 규칙은 CLAUDE.md에, 예외 없이 지켜야 하는 기계적 규칙은 훅에. 특히 보호 파일 차단 훅은 한 번 만들어 두면 마음이 정말 편해집니다.

더 알아보기

• Claude Code 훅 문서 (공식)
• 함께 읽기: CLAUDE.md 작성법