跳至内容

AI 讲明白 · 系列细讲 1 / 3

验证闭环四档

官方最佳实践第一条:给 Claude 一个它能自己跑的检查。原话是 It's the difference between a session you watch and one you walk away from. 有没有这个检查,决定了你得一直盯着,还是可以走开。这篇讲四种做法分别怎么配、能拦住什么、拦不住什么,并附上同一个任务四档各跑 3 次的本机实测。

官方Claude Code 官方文档(v2.1.293 时) 实测本机跑过 推断我的判断

没有检查时,“看起来做完了”就是唯一的信号

官方文档对这件事的描述很直白:Claude 在工作“看起来做完了”的时候停下。如果没有一个它能跑的检查,“看起来做完了”就是它唯一能用的信号,于是你成了那道验证,每个错误都要等你发现。给它一个能返回“通过 / 不通过”的东西,这个循环就能自己闭合:做事、跑检查、读结果、再改,直到通过。官方

检查可以是任何能把信号送回对话里的东西:测试、构建的退出码、lint、把输出和样例做比对的脚本、和设计稿对比的截图。真正的区别在于由谁来判断“做完了”。下面四档,判断者一档比一档独立。

四档一览

越往下,判断者离干活的模型越远,越不容易被它的误解带偏;配置也越多。

  1. 第 1 档
    在提示词里要求它跑检查
    谁判断
    干活的同一个模型
    看什么
    它自己选择跑的检查
    范围
    这一条消息
    成本
    零,多写一句话
  2. 第 2 档
    /goal 完成条件
    谁判断
    另一个小模型,每轮结束后评估
    看什么
    对话里已经出现的输出。它不会自己跑命令、读文件
    范围
    当前会话
    成本
    一行命令
  3. 第 3 档
    Stop hook 闸门
    谁判断
    你的脚本
    看什么
    真实的退出码,脚本自己跑的
    范围
    设置文件覆盖的所有会话
    成本
    一个脚本 + 一段配置
  4. 第 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。
46/46全部通过45/46漏了用例
档位3 次的外部验收平均轮数平均耗时平均花费停下时被要求继续
A · 不提检查只说“按 README 实现”
45/4645/4645/46
7.041 秒$0.0100、0、0 次
B · 提示词里要求自测为每条规则写测试并跑到全过
45/4645/4645/46
10.059 秒$0.0150、0、0 次
C · /goal证明 node --test 退出码为 0
45/4645/4645/46
11.083 秒$0.0230、0、0 次
D · Stop hook项目外的 46 个验收用例当闸门
46/4646/4646/46
12.356 秒$0.0141、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 把这个点用失败用例的形式送回给了模型。它不能说明哪一档在你的项目里能快多少。推断

每一档怎么配

第 1 档

在提示词里要求它跑检查

官方

官方给的几组前后对比,差别都在“验收标准写没写进提示词”:

之前之后
写一个校验邮箱地址的函数写 validateEmail。用例:user@example.com 为真,invalid 为假,user@.com 为假。实现后跑测试
把仪表盘做得好看点[贴截图] 按这个设计实现。截图对比结果和原图,列出差异并修掉
构建失败了构建报这个错:[贴错误]。修好并确认构建通过。解决根本原因,不要把错误压下去
修一下登录的 bug会话超时后登录会失败。看 src/auth/ 的 token 刷新。先写一个能复现问题的失败测试,再修

拦得住

它“忘了跑测试”、改完没构建、UI 和设计稿对不上这类问题。只要检查存在,它通常会照做。

拦不住

它理解错了需求,又按自己的理解写了测试。实测 B 档就是这样:自己写的测试全过,外部验收还是漏了同一条。

另外两点。让它拿出证据:跑了什么命令、输出是什么、截图长什么样。审证据比你自己重跑一遍快,也适用于你没盯着的会话。修 bug 时让它先写一个会失败的测试,确认测试能抓到问题,再去修,这样测试至少证明了它在测对的东西。官方

第 2 档

/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 轮后停止”。

拦得住

干到一半就宣布完成;长任务里忘了最初的目标。判断交给另一个模型,不由干活的模型自己说了算。

拦不住

对话里展示的证据本身有问题,比如测试写错了、只跑了一部分。评估者看不到对话之外的真实状态。

实测里撞上的坑:证据拿不到,/goal 会空转到上限

前两轮实验,权限给得比较紧:dontAsk 模式加一份命令白名单。C 档为了“证明退出码为 0”,会写更复杂的命令,比如 node --test; echo "exit=$?"、把输出写到项目外的 /tmp、用 $(pwd) 切目录。第一轮白名单漏了 echo,3 次都有命令被拒,都跑到 15 到 17 轮才结束;第二轮补上后仍有命令超出白名单,3 次都空转到触发上限。A、B、D 的命令简单,几乎没受影响。第一轮我补跑了一次并保留完整记录,过程是这样的:

  1. 写完代码Claude 写好实现和测试,用上面那条命令跑测试,被拒绝。它没有绕过权限,回复“测试没能运行,目标还没达成,需要你允许 Bash”。
  2. 评估者判“未达成”:对话里没有 node --test 退出码为 0 的证据。Claude 被要求继续。
  3. 反复 9 次它没有能用的工具,只能把同样的话再说一遍;评估者每次都判“未达成”。
  4. 触发上限系统提示 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 为真时用不了,命令会告诉你原因。
第 3 档

Stop hook:检查不过就不让它停

官方实测

Stop 事件在 Claude 答完一轮时触发。hook 以退出码 2 退出,或者输出 {"decision": "block", "reason": "…"},Claude 就不会停,而是把 stderr 或 reason 当作要继续处理的问题。和 /goal 不同,检查是你的脚本真跑出来的,不依赖对话里展示了什么。

.claude/hooks/test-gate.sh
#!/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
.claude/settings.json
{
  "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 次运行的闸门日志是:

gate.log(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。官方

第 4 档

独立审查:换一个没参与写代码的模型来看

官方

官方的理由是:新的上下文不会偏向自己刚写的代码。审查者只看到 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 模型,实验目录和验收用例在发布前已删除。