Wink Pings

CLAUDE.md 是许愿清单,hook 才是检查

你写进 CLAUDE.md 的规则,agent 在第 40 步违反了。规则是请求,hook 是检查。拆解 Claude Code 的 hook 机制:六个事件、三种应答、五种类型,以及让“完成”真正代表测试通过的 Stop hook。

你往 CLAUDE.md 里写“永远不要运行 rm -rf”。四十步之后,agent 还是运行了。Claude Code 是 Anthropic 的命令行编程代理。CLAUDE.md 是项目里的说明文件,模型每次会话都会读。所以那句话它看到了。问题不在它没读到。上下文里的一行字只是请求,请求会被模型手里其他信息权衡,然后覆盖。

Valentin 在 X 上把这问题拆得很明白:规则是请求,hook 是检查。CLAUDE.md 适合写项目结构、常用命令、团队风格。它没法让某个动作失败。hook 绑定在 Claude Code 生命周期的事件上,每次事件触发都会运行。模型不需要记得它、同意它,甚至不需要知道它存在。

hook 放在设置文件里。项目级 .claude/settings.json,全局 ~/.claude/settings.json。每个 hook 指定一个事件、一个可选的工具匹配器,以及要运行的命令:

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

hook 通过 stdin 拿到事件 JSON:工具名、工具输入、会话、工作目录。它读输入,做决定,回答。

六个事件先记这些:

  • SessionStart:会话开始、恢复、清空或压缩时运行。加载实时上下文,比如 open issues、当前分支、隔夜变化。
  • UserPromptSubmit:Claude 看到你的消息之前运行。可以给每条 prompt 加上下文,或者直接拒绝。
  • PreToolUse:工具调用前,唯一一道门。可以 allow、ask、deny。
  • PostToolUse:工具返回后。动作已发生,适合格式化、lint、记录日志。
  • Stop:Claude 即将结束时运行。拦下它,Claude 继续干活。
  • PreCompact:上下文被裁剪之前运行。把裁剪后还要用的信息写下来。

PreToolUse 和 Stop 承担大部分工作。PreToolUse 守门,Stop 守“完成”。

hook 有三种应答方式。exit 0 且不输出,表示不做决定,正常权限流程。exit 2 表示阻止,stderr 里的内容作为原因返回给 Claude。一个完整的 rm 守卫:

#!/bin/bash
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm is not allowed, move files to ./trash instead" >&2
  exit 2
fi

exit 0

stderr 那行比看起来重要。光说“不行”,agent 会换个方式再试。给了替代方案,它才切换。

exit 0 带 JSON 是精确版本。在 PreToolUse 上返回权限决定和原因:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep"
  }
}

deny 取消调用并告诉 Claude 原因。ask 走正常确认弹窗。allow 跳过弹窗。每个 hook 选一种风格。

然后是最少有人写的 Stop hook。每个 agent 都会说“完成”。很少被要求证明。Stop hook 在 Claude 准备交回控制权的瞬间运行。返回 decision: "block" 和原因,Claude 读原因,继续干活。把测试套件放进去,“完成”就成了可验证的事。

#!/bin/bash
input=$(cat)

[ "$(jq -r '.stop_hook_active' <<<"$input")" = "true" ] && exit 0

if ! out=$(npm test 2>&1); then
  jq -n --arg r "$(tail -20 <<<"$out")" '{decision: "block", reason: $r}'
fi

内置两个刹车,防止死循环。stop_hook_active 为 true 表示已经开始继续执行。检查它,否则永远跑不过的测试会一直占用会话。连续八次继续后,Claude Code 也会强制结束。reason 字段要具体。发送失败测试和最后几行输出,而不是“tests failed”。agent 只能修它看得见的东西。

五种 hook,四种不涉及模型。command 跑脚本,最便宜最快,每次结果一致。http 把同一份 JSON 发到 URL,一个服务器能给全团队执行统一策略。mcp_tool 调用已连接服务器里的工具。prompt 把输入发给模型做一次判断,返回 JSON。agent 生成子代理,能读文件、搜索再决定。最慢,仍标记实验性。

怎么选:如果规则不需要“判断、评估、决定”这些词,就是 command hook。“不能写到 src/ 外”是 command。“这个改动符合 ticket 吗”是 prompt。把每个检查都做成模型调用,等于为已经有唯一答案的问题支付判断费。

落地方式:找一条你在聊天里重复最多的规则,写成 PreToolUse command hook,exit 2,stderr 给替代方案。再加一个 Stop hook,跑最快的检查:lint、类型检查、改动文件的测试。再加一个 PostToolUse 格式化,再也不用 review 空白。prompt 和 agent hook 放最后,只给脚本说不清的规则。人留在 hook 够不到的地方:merge、deploy、migration。

评论区出现了几个典型反应。有网友说,Stop hook 是最值得先抄的,让“完成”等于测试通过。有人问,测试很 flaky 时,Stop hook 会一直阻塞还是放行。有人直接:hook 硬控,别指望它自律。也有人清醒:hook 只能覆盖脚本能检查的规则,“别像机器人说话”这种要求,仍留在 CLAUDE.md 里。评论区有人配了张图。

网友评论配图

Valentin 有三句话可以带走:

模型能跳过的规则,是建议。
检查不能失败,是装饰。
每个你打了两遍的纠正,都该放进 hook。

发布时间: 2026-11-23 01:51