Claude Code를 사용하다 보면 "CLAUDE.md에 적어두었는데도 지켜주지 않는다"라는 경험을 한 번쯤은 하게 될 것입니다.

그 근본적인 해결책으로 hooks가 있습니다. 이 기사에서는 실제로 사용할 수 있는 스크립트와 settings.json 설정 예시를 그대로 게재합니다. 설계 방식에 대해서는 원문(Claude Code의 hooks는 왜 CLAUDE.md나 지시문으로 대체할 수 없는가)을 참조해 주세요.

Claude Code가 툴(Tool)을 실행하기 직전·직후에 셸 스크립트(Shell Script)를 자동 실행할 수 있는 메커니즘. LLM을 거치지 않으므로 확정적으로 동작합니다.

.claude/
├── settings.json ← hooks를 여기에 작성 (리포지토리 공유)
└── hooks/
...

.claude/settings.json을 커밋하면, 이 리포지토리를 다루는 모든 에이전트(Agent) 및 멤버에게 자동으로 적용됩니다.

{
"hooks": {
"PreToolUse": [
...

matcher는 툴 이름(Bash / Write / Edit) 또는 *(모든 툴)를 지정합니다.

반환값	동작
exit 0	통과 (툴을 그대로 실행)
exit 2 + stderr 출력	Claude에게 피드백을 전달하며 차단
permissionDecision: "ask"	사용자에게 확인 프롬프트 표시
permissionDecision: "deny"	툴 호출을 취소하고 Claude에게 이유를 전송

hooks 스크립트는 표준 입력(Standard Input)으로부터 JSON을 받아, permissionDecision을 포함한 JSON을 표준 출력(Standard Output)으로 반환하거나 exit code로 반환합니다.

#!/usr/bin/env bash
# PreToolUse: mv 명령어로 이동할 대상 파일이 존재하는 경우 확인 프롬프트를 띄움
set -euo pipefail
...

#!/usr/bin/env bash
# PreToolUse: 백업 없는 sed -i를 감지하여 확인 프롬프트를 띄움
set -euo pipefail
...

#!/usr/bin/env bash
# Stop hook: 진행 파일에 미완료 체크리스트가 남아있으면 종료를 차단
PROGRESS_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/progress"
...

chmod +x .claude/hooks/*.sh

.claude/settings.json을 커밋하는 것만으로도 비서 에이전트, 엔지니어 에이전트, 마케터 에이전트 등 모든 서브 에이전트(Sub-agent)에게 동일한 가드레일(Guardrail)이 적용됩니다. 개별 에이전트 정의에 동일한 규칙을 작성할 필요가 없습니다.

에이전트 A ──┐
에이전트 B ──┼──→ PreToolUse hook ──→ check-mv-overwrite.sh ──→ 차단 또는 통과
에이전트 C ──┘

CLAUDE.md에 작성한 규칙은 에이전트가 "읽고 판단하는" (확률적) 방식인 반면, hooks는 "런타임(Runtime)이 직접 실행하는" (확정적) 방식이라는 점이 본질적인 차이입니다.

설계 방식(왜 CLAUDE.md로는 대체할 수 없는가), 차단(Block) vs 경고(Warning)의 판단 기준, 타임아웃(Timeout) 설계에 대해서는 원문에서 자세히 해설하고 있습니다.