AI 讲明白 · 系列细讲 1 / 3
验证闭环四档
官方最佳实践第一条:给 Claude 一个它能自己跑的检查。原话是 It's the difference between a session you watch and one you walk away from.
有没有这个检查,决定了你得一直盯着,还是可以走开。这篇讲四种做法分别怎么配、能拦住什么、拦不住什么,并附上同一个任务四档各跑 3 次的本机实测。
没有检查时,“看起来做完了”就是唯一的信号
官方文档对这件事的描述很直白:Claude 在工作“看起来做完了”的时候停下。如果没有一个它能跑的检查,“看起来做完了”就是它唯一能用的信号,于是你成了那道验证,每个错误都要等你发现。给它一个能返回“通过 / 不通过”的东西,这个循环就能自己闭合:做事、跑检查、读结果、再改,直到通过。官方
检查可以是任何能把信号送回对话里的东西:测试、构建的退出码、lint、把输出和样例做比对的脚本、和设计稿对比的截图。真正的区别在于由谁来判断“做完了”。下面四档,判断者一档比一档独立。
四档一览
越往下,判断者离干活的模型越远,越不容易被它的误解带偏;配置也越多。
-
第 1 档
在提示词里要求它跑检查
- 谁判断
- 干活的同一个模型
- 看什么
- 它自己选择跑的检查
- 范围
- 这一条消息
- 成本
- 零,多写一句话
-
第 2 档
/goal完成条件- 谁判断
- 另一个小模型,每轮结束后评估
- 看什么
- 对话里已经出现的输出。它不会自己跑命令、读文件
- 范围
- 当前会话
- 成本
- 一行命令
-
第 3 档
Stop hook 闸门
- 谁判断
- 你的脚本
- 看什么
- 真实的退出码,脚本自己跑的
- 范围
- 设置文件覆盖的所有会话
- 成本
- 一个脚本 + 一段配置
-
第 4 档
独立审查
- 谁判断
- 新上下文里的另一个模型
- 看什么
- diff 和你给的标准,看不到写代码时的推理
- 范围
- 你叫它时
- 成本
- 一条命令,或一个子代理定义
说明/goal 本质上是一个会话级的、用模型判断的 Stop hook,官方文档原话是 a wrapper around a session-scoped prompt-based Stop hook
。所以第 2、3 档的区别不在触发时机,而在判断者:一个读对话的小模型,还是你写的、会真跑检查的脚本。官方
实测:同一个任务,四档各跑 3 次
想知道这四档在实际中差多少,我在本机搭了一个小实验。实测
- 任务:实现
parseDuration,把1h30m、1.5h、1_000ms这样的字符串转成毫秒数。README 写了 9 条规则,其中有几个容易漏的:5ms和5m的区分、小数只能出现在最后一段、四舍五入要按写出来的十进制精确计算、结果超过Number.MAX_SAFE_INTEGER要报错。 - 验收:46 个测试用例,放在项目目录之外,AI 看不到。先用一个参考实现确认 46 个全过,说明规则是自洽的。
- 四档的提示词:A 只说“按 README 实现”。B 加一句“为 README 每条规则写测试,用
node --test跑到全过”。C 用/goal,条件是“按 README 实现,写覆盖每条规则的测试并证明node --test退出码为 0,或 15 轮后停止”。D 的提示词和 A 一样,但项目里配了一个 Stop hook,跑那 46 个验收用例,不过就以退出码 2 拦下。 - 运行:
claude -p非交互模式,Haiku 模型,每档 3 次,每次都是全新的目录和会话。权限用 bypassPermissions,同时禁止rm、curl、git push等命令和联网工具。Claude Code v2.1.293。
| 档位 | 3 次的外部验收 | 平均轮数 | 平均耗时 | 平均花费 | 停下时被要求继续 |
|---|---|---|---|---|---|
| A · 不提检查只说“按 README 实现” | 45/4645/4645/46 | 7.0 | 41 秒 | $0.010 | 0、0、0 次 |
| B · 提示词里要求自测为每条规则写测试并跑到全过 | 45/4645/4645/46 | 10.0 | 59 秒 | $0.015 | 0、0、0 次 |
| C · /goal证明 node --test 退出码为 0 | 45/4645/4645/46 | 11.0 | 83 秒 | $0.023 | 0、0、0 次 |
| D · Stop hook项目外的 46 个验收用例当闸门 | 46/4646/4646/46 | 12.3 | 56 秒 | $0.014 | 1、1、1 次 |
结论 1只有 D 档 3 次全部通过 46 个验收用例。A、B、C 九次漏的都是同一条:“结果超过 Number.MAX_SAFE_INTEGER 要报错”。
结论 2B、C 自己写的测试全部通过(B 写了 34、60、68 个,C 写了 52、34、53 个),C 档的评估者每次在第一次检查时就判了“已达成”。它们证明的是“我写的测试都过了”,可没有一个测试覆盖那条规则。检查和实现出自同一个模型的理解,就绕不开同一个盲区。
结论 3D 档 3 次都是同一个过程:第一次想停,闸门拦下,失败用例的名字 invalid "104249992d" throws TypeError 回到对话里;它补上判断后再停,第二次检查全部通过。
代价D 比 A 平均多 5 轮、多 15 秒、多花约 $0.004。C 最贵,平均 $0.023,因为它要写一大堆测试来证明自己。
稳健性我前后跑了三轮,前两轮的权限设置把 C 档卡住了(见下文 /goal 一节)。三轮共 36 次:A、B、C 的 27 次全部漏了这一条,D 的 9 次全部 46/46。上表是第三轮的数据。
只有一个任务、一个模型、每档 3 次。它能说明的是机制:没有外部检查时,大家会漏掉同一个“没想到”的点;Stop hook 把这个点用失败用例的形式送回给了模型。它不能说明哪一档在你的项目里能快多少。推断
每一档怎么配
在提示词里要求它跑检查
官方官方给的几组前后对比,差别都在“验收标准写没写进提示词”:
| 之前 | 之后 |
|---|---|
| 写一个校验邮箱地址的函数 | 写 validateEmail。用例:user@example.com 为真,invalid 为假,user@.com 为假。实现后跑测试 |
| 把仪表盘做得好看点 | [贴截图] 按这个设计实现。截图对比结果和原图,列出差异并修掉 |
| 构建失败了 | 构建报这个错:[贴错误]。修好并确认构建通过。解决根本原因,不要把错误压下去 |
| 修一下登录的 bug | 会话超时后登录会失败。看 src/auth/ 的 token 刷新。先写一个能复现问题的失败测试,再修 |
拦得住
它“忘了跑测试”、改完没构建、UI 和设计稿对不上这类问题。只要检查存在,它通常会照做。
拦不住
它理解错了需求,又按自己的理解写了测试。实测 B 档就是这样:自己写的测试全过,外部验收还是漏了同一条。
另外两点。让它拿出证据:跑了什么命令、输出是什么、截图长什么样。审证据比你自己重跑一遍快,也适用于你没盯着的会话。修 bug 时让它先写一个会失败的测试,确认测试能抓到问题,再去修,这样测试至少证明了它在测对的东西。官方
/goal:让另一个模型判断有没有达成
官方设一个完成条件,Claude 会一直干下去,不用你每一步都开口。每轮结束后,Claude Code 把条件和到目前为止的对话交给一个小而快的模型,它给出三种判定之一:还没达成(Claude 接着干,并把理由当作下一步的方向)、已达成(目标清除)、不可能达成(目标清除并记录原因)。
/goal test/auth 下的测试全部通过,lint 干净;不许改其他测试文件;或 20 轮后停止
/goal # 查看状态:条件、跑了多久、评估了几轮、花了多少 token、最近一次判定的理由
/goal clear # 提前清除,stop、off、reset、cancel 也行
claude -p "/goal CHANGELOG.md 里有本周合并的每个 PR 的条目" \
--output-format stream-json --verbose # 默认文本输出要等跑完才打印,看起来像卡住
条件怎么写:评估者不会自己跑命令、也不会读文件,只能根据 Claude 在对话里展示出来的东西判断。所以条件要写成 Claude 的输出能证明的形式。官方建议包含三样:一个可测量的终点(测试结果、退出码、文件数、清空的队列),一个写明的检查方式(比如“npm test 退出码为 0”),以及路上不能变的约束(比如“不许改其他测试文件”)。条件最长 4000 字符。想限制时长,就在条件里加“或 20 轮后停止”。
拦得住
干到一半就宣布完成;长任务里忘了最初的目标。判断交给另一个模型,不由干活的模型自己说了算。
拦不住
对话里展示的证据本身有问题,比如测试写错了、只跑了一部分。评估者看不到对话之外的真实状态。
前两轮实验,权限给得比较紧:dontAsk 模式加一份命令白名单。C 档为了“证明退出码为 0”,会写更复杂的命令,比如 node --test; echo "exit=$?"、把输出写到项目外的 /tmp、用 $(pwd) 切目录。第一轮白名单漏了 echo,3 次都有命令被拒,都跑到 15 到 17 轮才结束;第二轮补上后仍有命令超出白名单,3 次都空转到触发上限。A、B、D 的命令简单,几乎没受影响。第一轮我补跑了一次并保留完整记录,过程是这样的:
- 写完代码Claude 写好实现和测试,用上面那条命令跑测试,被拒绝。它没有绕过权限,回复“测试没能运行,目标还没达成,需要你允许 Bash”。
- 评估者判“未达成”:对话里没有
node --test退出码为 0 的证据。Claude 被要求继续。 - 反复 9 次它没有能用的工具,只能把同样的话再说一遍;评估者每次都判“未达成”。
- 触发上限系统提示
A hook blocked the turn from ending 9 consecutive times — overriding and ending turn,运行结束。
结束时目标没有达成,它自己写的测试 49 个通过、9 个失败。这是官方文档写明的两条规则在起作用:/goal 不改权限模式;连续几轮不调用工具,循环就会停下。教训是:条件里要求的证据,先确认它有权限拿到。第三轮改用 bypassPermissions 并禁止危险命令,C 档就正常结束了,上面“实测”一节用的是第三轮的数据。实测
- 什么时候自动停:达成或判定不可能时清除目标。认证失败、额度用尽、上下文压缩后仍然溢出、模型不可用这四类错误也会清除目标。如果 Claude 连续几轮没调用任何工具、只是在回应评估者,循环会停下,目标仍然保留。
- 不改权限模式:
/goal不会替你批准工具调用。想让它无人值守地跑,需要预先放行要用的命令,或者在 auto 模式下用。 - 评估很便宜:评估用的是小而快的模型,官方说这部分 token 和主任务相比通常可以忽略。
- 有前提:它属于 hook 系统,所以受工作区信任规则约束;设置里
disableAllHooks为真时用不了,命令会告诉你原因。
Stop hook:检查不过就不让它停
官方实测Stop 事件在 Claude 答完一轮时触发。hook 以退出码 2 退出,或者输出 {"decision": "block", "reason": "…"},Claude 就不会停,而是把 stderr 或 reason 当作要继续处理的问题。和 /goal 不同,检查是你的脚本真跑出来的,不依赖对话里展示了什么。
#!/bin/bash
# Stop hook:测试不过,就不让 Claude 结束这一轮
cd "$CLAUDE_PROJECT_DIR" || exit 0
OUT=$(npm test --silent 2>&1)
if [ $? -ne 0 ]; then
printf '%s\n' "$OUT" | tail -n 30 >&2 # 失败的用例回给 Claude
echo "测试没通过。修实现让测试通过,不要改测试文件。" >&2
exit 2
fi
exit 0
{
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/test-gate.sh" } ] }
]
}
}
拦得住
它没想到的情况,只要你的检查覆盖了。失败的用例名和期望值会原样回给它。实测 D 档 3 次都靠这个补上了超大数值那条规则。
拦不住
你的检查本身没覆盖的情况。还有,它可能去改测试来让测试通过,需要另外拦(见下面的“常见的坑”)。
防死循环:上限,以及一个容易抄错的写法
官方的保护机制是:Stop hook 连续让 Claude 继续 8 次,第 9 次就不再拦,强制结束这一轮。Claude 每调用一次工具,这个计数就清零。也就是说,只要它还在改代码、跑命令,闸门可以一直拦下去;真正被上限拦住的,是它光说话不干活的情况。上限可以用 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 调高。官方
Stop hook 的输入里有一个 stop_hook_active 字段,表示“这次已经是因为 Stop hook 才继续的”。官方排障文档给的示例是:这个字段为 true 就直接放行。这个写法适合“提醒一次就够”的 hook,拿来做测试闸门就只拦一次:第二次检查还不过,也会放它走。实测 D 档第 1 次运行的闸门日志是:
stop_hook_active=False exit=1 # 第一次想停,验收没过,拦下
stop_hook_active=True exit=0 # 它修完再停,验收全过,放行
这一次第二回就过了,所以两种写法结果一样。但如果第二回还没过,照抄“为 true 就放行”的写法,它就带着失败的测试结束了。我的建议是:测试闸门不看 stop_hook_active,靠官方那个“连续 8 次且没有调用工具”的上限防死循环;实在担心,就在脚本里自己数一下拦了几次。推断
另外两种 Stop hook
"type": "prompt":把 hook 输入和你的提示词交给一个模型,返回{"ok": false, "reason": "…"}就让 Claude 继续。/goal就是这种。适合 hook 的输入本身就够判断的情况。"type": "agent":派一个能读文件、跑命令的子代理去核实,默认超时 60 秒,最多 50 轮工具调用。官方标注为实验性,生产环境建议用 command 型。
项目 .claude/settings.json 里的 hook,在 claude -p 下不需要工作区信任就会执行。在不是你写的仓库里跑 claude -p 之前,加 --setting-sources user 不读项目设置,或者用 --settings '{"disableAllHooks": true}' 关掉 hook。官方
独立审查:换一个没参与写代码的模型来看
官方官方的理由是:新的上下文不会偏向自己刚写的代码。审查者只看到 diff 和你给的标准,看不到写代码时的推理,所以它按结果本身来评判。几种现成的做法:
| 做法 | 做什么 | 备注 |
|---|---|---|
/code-review | 审当前 diff 的正确性问题 | 可选 low 到 max 几档,--fix 直接改;传 PR 号审 PR;/review 是别名 |
/security-review | 审当前分支相对默认分支的安全问题 | 需要 origin 远程 |
/verify | 构建并运行你的应用,看改动是否真的生效 | 不靠测试和类型检查;只在你调用时运行 |
/run-skill-generator | 把“怎么从干净环境启动这个项目”记成 skill | 之后 /run、/verify 都照着做 |
| 自定义审查子代理 | 按你的标准审,比如对照 PLAN.md | 只给只读工具,见经验该沉淀到哪里的 reviewer 示例 |
| 动态 workflow | 让多个代理互相交叉核对发现 | 适合大范围审计;内置的 /deep-research 就是这种 |
用子代理对照 PLAN.md 审查限流器的 diff。检查每条需求是否都实现了、
列出的边界情况是否都有测试、任务范围之外有没有被改动。
只报缺口,不报风格偏好。
官方原话:被要求找缺口的审查者,即使工作没问题也通常会报出一些,因为这就是它被要求做的。照单全改会导致过度设计:多余的抽象层、防御性代码、给不可能发生的情况写的测试。告诉审查者只报影响正确性或需求的问题,其余当作可选。官方
怎么选
四档可以叠加。下面是我的选法。推断
- 还没有任何能跑的检查先造检查
- 一次性的小任务,你就在旁边第 1 档
- 长任务,想走开,终点能在输出里证明第 2 档 /goal
- 团队规则、每个会话都必须满足的门槛第 3 档 Stop hook
- 验收标准在你手里,不想让它照着标准凑答案第 3 档,检查放在项目外
- 改动大、风险高,或担心它误解了需求再加第 4 档
没有检查的时候,第一步永远是造一个:哪怕只是一个把输出和样例对比的小脚本、一个固定的截图对比。官方原话:If you can't verify it, don't ship it.
常见的坑
- 它改测试来让测试通过:在提示词和
/goal条件里写“不许改测试文件”只是请求。要强制,加一个 PreToolUse hook,拒绝对测试目录的 Edit 和 Write,写法和经验该沉淀到哪里的迁移文件保护一样。 - 闸门太慢:Stop hook 每次停下都跑一遍。完整测试要几分钟的话,在 hook 里只跑和改动相关的那部分,完整测试留给 CI。推断
- 测试不稳定:时好时坏的测试会让闸门反复拦,直到触发上限。先把不稳定的测试修好或隔离出去。推断
/goal的条件证明不了:写“代码质量要好”,评估者无从判断。换成能在输出里看到的终点。- 同一个模型自己出题自己考:第 1 档最常见的失效方式。实测 B 档自己写的测试全过,外部验收照样漏。要关键的东西,检查得来自它之外。
- 审查意见照单全收:只改影响正确性和需求的,其余的记下来再说。
来源
- 官方 Best practices for Claude Code(验证、审查、前后对比示例)
https://code.claude.com/docs/en/best-practices - 官方 Keep Claude working toward a goal(/goal)
https://code.claude.com/docs/en/goal - 官方 Hooks reference(Stop 输入、决策、8 次上限)
https://code.claude.com/docs/en/hooks - 官方 Automate workflows with hooks(prompt 型、agent 型 hook,排障)
https://code.claude.com/docs/en/hooks-guide - 官方 Commands、Extend Claude with skills(/code-review、/verify、/run-skill-generator)
https://code.claude.com/docs/en/commands - 官方 Configure permissions(未信任目录下 -p 会执行什么)
https://code.claude.com/docs/en/permissions - 官方 Orchestrate subagents at scale with dynamic workflows
https://code.claude.com/docs/en/workflows
整理于 2026 年 10 月 8 日。实测在 macOS、Claude Code v2.1.293 上进行,用的是独立的临时目录和 Haiku 模型,实验目录和验收用例在发布前已删除。