Hook Engineering — Deterministic Automation

Claude Code에는 30개의 훅 이벤트가 있다. 6개 범주로 분류된다:

세션 레벨: SessionStart, Setup, SessionEnd 턴 레벨: UserPromptSubmit, UserPromptExpansion, Stop, StopFailure 도구 레벨: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied 에이전트 레벨: SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle 파일/설정: FileChanged, CwdChanged, WorktreeCreate, WorktreeRemove, ConfigChange, InstructionsLoaded 컨텍스트: PreCompact, PostCompact UX: Notification, MessageDisplay, Elicitation, ElicitationResult

블로킹 가능한 훅: UserPromptSubmit, PreToolUse, PermissionRequest, PostToolBatch, Stop, SubagentStop, TaskCreated, PreCompact, Elicitation 등

실용적으로 중요한 4개: PreToolUse(안전 게이트), PostToolUse(품질 루프), UserPromptSubmit(컨텍스트 주입), Stop(완료 검증)

가장 흔한 실수: Unix 관례를 따라 exit 1을 쓰면 Claude Code는 이를 무시하고 계속 진행한다. '안전 훅'이라고 작성했지만 실제로는 아무것도 차단하지 않는다.

올바른 차단 훅 패턴:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import json,sys; print(json.loads(sys.stdin.read()).get('tool_input',{}).get('command',''))" 2>/dev/null)

if echo "$COMMAND" | grep -qE 'git push --force|rm -rf /|sudo'; then
  echo "위험한 명령어 차단: $COMMAND" >&2
  exit 2  # 반드시 2, 1이 아님!
fi

exit 0

stderr의 역할: exit 2와 함께 stderr에 쓴 내용이 Claude의 컨텍스트에 피드백으로 들어간다. 에러 메시지를 잘 작성하면 Claude가 스스로 수정한다.

훅은 단순히 블로킹만 하는 것이 아니다. JSON 출력으로 Claude의 컨텍스트에 정보를 주입하거나, 도구 입력을 수정하거나, 권한 결정을 내릴 수 있다.

전체 JSON 출력 스키마:

{
  "continue": true,
  "stopReason": "빌드 실패",
  "suppressOutput": false,
  "systemMessage": "경고 메시지",
  "decision": "block",
  "reason": "이유 설명",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny|allow|ask|defer",
    "permissionDecisionReason": "설명",
    "additionalContext": "Claude 컨텍스트에 주입할 추가 정보",
    "updatedInput": { "수정된": "도구 입력" }
  }
}

additionalContext의 활용: PostToolUse 훅에서 린터 결과를 additionalContext로 반환하면, Claude가 그것을 보고 스스로 수정한다.

updatedInput의 활용: PreToolUse 훅에서 도구 입력을 수정할 수 있다. 예: git commit 명령에 자동으로 서명을 추가.

패턴 1: 민감 파일 보호 (PreToolUse, 블로킹)

# .claude/hooks/block-sensitive-files.sh
FILE=$(cat | python3 -c "import json,sys; print(json.loads(sys.stdin.read()).get('tool_input',{}).get('file_path',''))" 2>/dev/null)
for pattern in '.env' '.ssh' 'credentials' 'secrets'; do
  case "$FILE" in *"$pattern"*) echo "민감 파일 보호: $FILE" >&2; exit 2;; esac
done

패턴 2: 린터 설정 보호 (PreToolUse)

FILE=$(cat | python3 -c "import json,sys; print(json.loads(sys.stdin.read()).get('tool_input',{}).get('file_path',''))" 2>/dev/null)
for p in '.eslintrc' 'biome.json' 'pyproject.toml' 'tsconfig.json'; do
  case "$FILE" in *"$p"*) echo "린터 설정 보호: 코드를 고치세요, 린터가 아니라." >&2; exit 2;; esac
done

패턴 3: 자동 포맷 (PostToolUse)

# .claude/hooks/auto-format.sh
FILE=$(cat | python3 -c "import json,sys; d=json.loads(sys.stdin.read()); print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null)
case "$FILE" in
  *.ts|*.tsx) npx prettier --write "$FILE" 2>/dev/null;;
  *.py) ruff format "$FILE" 2>/dev/null;;
  *.go) gofmt -w "$FILE" 2>/dev/null;;
esac

패턴 4: JSONL 감사 로그 (PostToolUse, 모든 이벤트)

LOG_DIR="$HOME/.claude/audit"
mkdir -p "$LOG_DIR"
printf '{"ts":"%s","event":%s}\n' "$(date -u +$(cat)" >> "$LOG_DIR/$(date -u +%Y-%m-%d).jsonl"

패턴 5: 컨텍스트 자동 주입 (UserPromptSubmit)

DATE=$(date +%Y-%m-%d)
BRANCH=$(git branch --show-current 2>/dev/null || echo 'not-in-git')
DIRTY=$(git status --short 2>/dev/null | wc -l | tr -d ' ')
echo "{\"additionalSystemPrompt\": \"[date=$DATE branch=$BRANCH dirty_files=$DIRTY]\"}"

패턴 6: 완료 전 테스트 검증 (Stop 훅)

if ! npm test --silent 2>/dev/null; then
  echo '테스트 실패: 완료 전 테스트를 통과하세요' >&2
  exit 2
fi