Day 07 只介绍了 PreToolUse 和 PostToolUse—— 它们其实只是钩子家族的两位成员。整套系统覆盖了从会话启动到上下文压缩的完整生命周期， 每一个事件都是一个可以注入自动化的接口点。

完整事件列表

事件在会话中的时间线

所有 hook 都在 settings.json 中声明。 结构是固定的三层嵌套——事件 → matcher → 处理器—— 把这个心智模型刻进脑子，剩下的都是细节。

骨架结构

// .claude/settings.json
{
  "hooks": {
    // 第 1 层：事件名
    "PostToolUse": [
      {
        // 第 2 层：matcher（哪些工具会触发）
        "matcher": "Edit|Write|MultiEdit",

        // 第 3 层：处理器列表
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matcher 写法

stdin/stdout 协议

Hook 脚本通过 stdin 接收一个 JSON 对象（包含工具名、参数、上下文），通过 stdout 返回处理结果，通过 退出码 表达通过/拒绝。

退出码语义

所有 hook 用法中，自动格式化 与 自动测试 是收益最高的两类。 每次 Claude 修改完文件，立刻自动 prettier / black / pytest， 让 Claude 自己看到结果——这是把 LLM 编程从"凑合能跑"提升到"工业级可信"的关键习惯。

Pattern A · 编辑后自动格式化

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh"
      }]
    }]
  }
}

#!/bin/bash  —  .claude/hooks/format.sh
# 读取 stdin 拿到改动文件路径
file=$(jq -r '.tool_input.file_path // empty')
[ -z "$file" ] && exit 0

case "$file" in
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$file" ;;
  *.py)                  black --quiet "$file" ;;
  *.go)                  gofmt -w "$file" ;;
  *.rs)                  rustfmt "$file" ;;
  *.json|*.yml|*.yaml)   npx prettier --write "$file" ;;
esac

# exit 0 —— 静默通过，Claude 看不到，但磁盘上的文件已经被格式化了

Pattern B · 修改源码后自动测试

#!/bin/bash  —  .claude/hooks/auto-test.sh
file=$(jq -r '.tool_input.file_path // empty')
[ -z "$file" ] && exit 0

# 只对 src/ 下的代码触发测试，跳过 docs / config
[[ ! "$file" =~ ^src/ ]] && exit 0

# 只跑相关测试，不是全量——速度优先
test_file="${file//src/test}"
test_file="${test_file%.ts}.test.ts"

if [ -f "$test_file" ]; then
  if ! npx vitest run "$test_file" 2>&1 | tail -20; then
    # 测试失败 → 把失败信息写到 stderr + exit 2 阻断
    echo "⚠ 测试失败:$test_file,请修复后再继续" >&2
    exit 2
  fi
fi

exit 0

何时阻断、何时静默

Pattern C · UserPromptSubmit 注入项目上下文

#!/bin/bash  —  .claude/hooks/inject-context.sh
# 在每次 prompt 提交前自动塞入当前 git 状态
{
  echo "=== 当前 git 状态 ==="
  git status --short
  echo "=== 最近 3 个 commit ==="
  git log --oneline -3
} | jq -Rs '{ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: . } }'

Hook 的处理器有两种形态：本地 shell 命令，或调用远端 HTTP webhook。 前者更快、更私密；后者跨机器、跨团队、能集成 Slack/PagerDuty 这类协作工具。

对比一览

HTTP 钩子配置

// settings.json — HTTP 类型 hook
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "webhook",
        "url": "https://audit.internal.corp/claude-bash",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer ${AUDIT_TOKEN}"
        },
        "timeout": 5
      }]
    }]
  }
}

三种生产模式

Shell + HTTP 组合示例

#!/bin/bash  —  .claude/hooks/audit-with-slack.sh
# 既写本地 audit log,也推 Slack——Shell 钩子里调 HTTP

payload=$(cat)  # 从 stdin 读 JSON
tool=$(echo "$payload" | jq -r '.tool_name')
cmd=$(echo "$payload" | jq -r '.tool_input.command // ""')

# 本地审计 log
echo "[$(date -Iseconds)] $tool: $cmd" >> ~/.claude/audit.log

# 高危命令推 Slack
if [[ "$cmd" =~ (rm -rf|drop table|DELETE FROM) ]]; then
  curl -s -X POST "$SLACK_WEBHOOK" \
    -H "Content-Type: application/json" \
    -d "{\"text\":\"⚠ Claude attempted: $cmd\"}"
fi

exit 0

Hook 不是"写完就忘"——它会在生产环境跑成百上千次。 下面是把 hook 调到稳定可信的几个关键习惯。

调试命令

8 条铁律

常见反模式

四个递进的动手实验——从最简单的格式化 hook 到完整审计流。 预计 45 分钟，建议在一个真实项目里跑通，每个 lab 结束后用 /hooks 命令检查。

1. 列出至少 6 种 Hook 事件名，说明它们各自的触发时机。
2. PostToolUse 的 hook 如何把"测试失败"反馈给 Claude？退出码与 stderr 各扮演什么角色？
3. Matcher 字段的 "Edit|Write" 与 "Edit" 有什么区别？为什么用正则不用 glob？
4. Shell 钩子 与 HTTP 钩子的核心差异是什么？各举一个最合适的场景。
5. 请写出三条"hook 反模式"——并说明它们为什么会让用户体验变糟。