Hooks

1. 훅이란?

훅은 정해진 순간(파일을 저장하기 직전, 커밋하기 직전 등)에 자동으로 실행되는 검사입니다. 내가 시키지 않아도, 그 순간이 오면 무조건 실행됩니다.

검사에 그치지 않고 막을 수도 있습니다. 통과하면 그대로 진행하고, 위반이면 멈추고 무엇이 문제인지 알립니다. 그래서 규칙이 "지키면 좋은 권고"가 아니라 "안 지키면 못 지나가는 관문"이 됩니다.

Q. 훅에 막히면 작업을 아예 못 하나요?

A. 막힌 이유가 표시됩니다. 빠진 것(예: 필수 문서)을 채우면 다시 진행됩니다.

훅이란, 정해진 순간에 자동으로 실행돼 규칙을 강제하는 검사.

2. 훅 만들기

훅은 두 부분으로 이뤄집니다. 검사할 내용을 담는 .claude/hooks/ 아래의 스크립트와, 실행 시점을 정하는 .claude/settings.json 입니다.

예를 들어 파일을 지우는 위험한 명령을 실행 직전 PreToolUse 시점에 막는다면, 이렇게 만듭니다.

.claude/
├── hooks/
│   └── block-delete.sh   ← 위험한 삭제를 막는 검사 (새로 만드는 파일)
└── settings.json         ← 실행 시점 등록

#!/bin/bash
# 실행하려는 명령을 읽어, 위험한 삭제가 있으면 막는다.
cmd=$(cat | jq -r '.tool_input.command')
if echo "$cmd" | grep -q "rm -rf"; then
  echo "위험한 삭제 명령이라 막았습니다." >&2
  exit 2      # 0 이 아니면 그 동작을 막는다
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/block-delete.sh" }
        ]
      }
    ]
  }
}

위 settings.json 의 세 항목은 이렇게 읽습니다.

• PreToolUse: 언제 실행할지 정하는 이벤트. 여기선 도구 실행 직전.
• matcher: 어떤 도구를 대상으로 할지. 여기선 명령을 실행하는 Bash.
• command: 그 순간에 실행할 스크립트.

스크립트가 위험을 발견해 실패를 반환하면, 그 동작은 그대로 막힙니다. 이벤트는 PreToolUse 외에도 여러 가지가 있으며, 원하는 시점에 맞는 이벤트를 선택합니다. 자주 쓰는 이벤트는 다음과 같습니다.

검사 코드를 직접 작성할 필요는 없습니다. Claude 에게 "위험한 삭제 명령은 실행 전에 막아 줘"처럼 요청하면, 스크립트 block-delete.sh 작성과 settings.json 등록까지 대신 처리합니다. 위 코드는 그 결과물이므로 형태만 파악하면 충분하며, 자세한 내부 동작은 엔지니어 세션 Hooks 편에서 다룹니다.

3. 훅 사용 방법

훅은 스킬·에이전트처럼 직접 입력해 호출하지 않습니다. settings.json 에 걸어 두면, 저장·커밋 같은 정해진 순간에 Claude 가 matcher 를 보고 알맞은 훅을 자동으로 실행합니다.

주로 이런 순간에 걸어 둡니다.

• 파일을 저장하면 자동으로 서식을 정리합니다.
• 위험한 명령을 실행하기 전에 막습니다.
• 규칙을 어긴 커밋(예: 필수 문서 누락)을 막습니다.
• 특정 순간에 알림을 보냅니다.

4. 팀·도구 공유

훅 설정(.claude/settings.json)과 검사 스크립트(.claude/hooks/)도 git 저장소에 올리면 팀 전체가 같은 규칙을 내려받습니다. 그래서 규칙이 한 사람의 컴퓨터에만 있는 게 아니라, 팀 공통의 관문으로 강제됩니다. 다만 훅은 스킬과 달리 공개 표준이 아니라 Claude Code 전용 형식이라, Codex 같은 다른 AI 도구는 이 설정을 그대로 읽지 못할 수 있습니다.

5. 스킬·에이전트와의 차이

• 스킬·에이전트: Claude 가 상황을 보고 판단해서 실행합니다. 상황에 따라 안 할 수도 있습니다.
• 훅: 판단 없이, 정해진 순간에 무조건 실행되고 막습니다.

그래서 꼭 지켜야 하는 규칙(안전·품질)은 훅으로 박아 둡니다. "이번엔 넘어가자"가 통하지 않아야 하는 것들입니다.

마무리

• 핵심 정리: 훅은 정해진 순간에 자동으로 실행되는 검사입니다. 검사만 하는 게 아니라 규칙 위반 시 막습니다. 실제로는 .claude/settings.json 에 "이벤트 + 검사 명령"으로 겁니다. 스킬·에이전트가 판단으로 "하는 것"이라면, 훅은 판단 없이 "무조건 실행되는 것"입니다.
• 주의 사항: 훅은 권고가 아니라 관문입니다. 막히면 메시지를 읽고 빠진 것을 채워야 지나갑니다.
• 다음 시간: 지금까지 익힌 도구(프롬프팅·스킬·에이전트·훅)를 실제 개발에 굴리는 개발 사이클과 백로그를 봅니다.