Claude Code Harness 08: Verify：从感觉走到证据

Plan确定的是整体方向，TDD锁定的是具体行为。然而，仅锁定局部行为并不足以确保整个系统能够顺利交付。

在实际项目开发中，Claude Code最常见的瓶颈并非“能力不足”，而是“过早停止”。局部测试虽然通过，代码看起来也无明显缺陷，甚至能提供一个自洽的解释——但系统因此形成了“任务大致完成”的错误判断。而工程领域从不接受“差不多”，它只认可“已通过验证”。

本章的目标非常明确：将Verify从“最后才想起执行”的临时动作，转变为系统默认的闭环步骤。

一、Plan和TDD之后，究竟还缺什么

举个例子：修正了一个接口层的bug。问题复现明确，编写了失败测试，进行了最小修复，局部测试也顺利通过。整套流程看起来非常完整。

但若此时直接收工，仍然可能遗漏：typecheck未通过、某个lint规则被触发、其他测试因本次改动而失败、甚至该接口对应的前端调用链也受到波及。

三者的分工实际上是这样的：

Plan = 定地图，TDD = 锁局部行为，Verify = 看系统是否真的到站

缺少Verify这道关卡，Claude Code很容易卡在“局部逻辑看起来没问题，所以任务差不多完成了”这个位置。而工程事故，恰恰最喜欢隐藏在这个“差不多”的背后。

二、为什么Claude Code特别容易缺Verify

这背后有三个结构性的原因。

偏向完成叙事。 强推理模型天生擅长把当前已有的信息组织成看起来完整的结论。一旦bug修复了、测试至少通过了一部分、代码读起来没问题，它就会快速形成“任务大致完成”的内部判断。这并非低级错误，而是生成式系统的结构特征。

偏向推理而非检查。 它更擅长分析、解释和生成，而不是枯燥地执行一串命令、再逐个查看结果。因此，Verify必须设计成系统层面的机制，仅靠一句“记得验证”的提示几乎毫无效果。

没有固定顺序时，验证会退化。 先跑了test觉得没问题，就没再跑typecheck；build通过了，就没回头看lint。问题不在于会不会验证，而在于缺乏固定顺序时，验证最终会变成“跑了哪个算哪个”。

三、给Verify设定一个固定顺序

很多团队声称“有验证”，但实际做法是“想起来跑一下，看到哪里顺手跑到哪里”。要让Verify变得稳定可靠，必须赋予它一个固定顺序：

Targeted behavior locked（TDD阶段完成）↓ Build ↓ Typecheck ↓ Lint ↓ Tests ↓ Review / Security Review（按需）↓ Ready or Not Ready

顺序的意义在于：让“完成”从一种主观感觉，变为流程的必然结果。

这里蕴含一个更深层的设计原则——将“做”和“判”分离开来。生成者天然对自己的成果偏乐观，Claude很擅长把当前实现解释得非常合理，将局部成功组织成“任务完成了”的叙事。更稳妥的方式，是让生成任务与评估任务在明确的阶段中分开执行。

四、任务清晰度 × 验证清晰度

这里用一张四象限图来判断Claude Code适合深入推进的场景：

验证清晰 低 高 任务清晰 +----------------------+ 低 | 高效跑偏 | 可探索 | 高 | 卡在人工验收 | 最适合Agent | +----------------------+

当任务清晰且验证清晰时，Claude Code最能发挥其价值。任务清晰但验证不清晰，吞吐量通常卡在人工验收环节。验证清晰但任务不清晰，系统则可能高效跑偏。两者都不清晰时，不应扩大agent的自主度。

五、Verify在整个工作流中的位置

Task → Plan → Confirm → TDD / Minimal Implementation → Targeted test passes ↓ Verify ├── Build ├── Typecheck ├── Lint ├── Tests ├── Review └── Security Review（when needed） ↓ Ready / Not Ready

Verify并非收尾动作，而是“完成状态”的裁判。没有它，Claude Code所谓的“完成”，不过是一种语言输出。

六、一个真实案例

上一章锁住的结算逻辑测试通过了。如果此时没有Verify，Claude很可能说“问题已经修复”。但开发者还需要关心：本次改动是否影响了payout ledger的其他路径？类型定义有没有被连带破坏？通知逻辑是否正常？有没有引入新的lint错误？

TDD证明的是“这个行为现在正确了”，而Verify证明的是“这个改动放回系统里依然能够站稳”。局部胜利，是最容易被误判为“整体完成”的陷阱。

七、/verify命令模板

直接固定为.claude/commands/verify.md，内容如下：

# /verify 运行验证时遵守以下顺序： 1. Build 2. Typecheck 3. Lint 4. Tests 5. Review / Security checks（当相关时） 输出格式： ## 验证报告 - Build： - Typecheck： - Lint： - Tests： - Review： - Security： ## 结果 - Ready for delivery / Not ready ## 剩余问题 - ... 规则： - 验证完成前，不要说任务完成了。 - 任何步骤失败，立即停止并清晰报告。 - 不要把局部成功当作最终完成。

这个模板固定了三件事：顺序、输出结构、失败时的行为。一旦缺少这三样约束，Claude Code特别容易先跑最容易通过的步骤、只汇报好的部分、失败时还继续硬跑。

八、Verify分层：基础版和扩展版

并非每个任务都需要重型审查。

基础Verify 适用于小功能、局部bugfix、低风险重构，包含build / typecheck / lint / tests。

扩展Verify 适用于鉴权、权限、支付、数据删除、涉及secret或PII的变更，额外包含review和security review。

同样，局部验证和全局验证也应该分层。开发过程中先做局部收敛（targeted test、受影响模块的typecheck、相关路径的lint），在交付节点做全局确认（全量build、全量test、完整review）。先局部、再全局，既不会一上来太重，也不会让交付边界越来越模糊。

九、怎么让Verify真正成为默认路径

仅在CLAUDE.md里写一句“完成前请先验证”，远远不够。需要三层配合：

Rules里立底线。 未验证前不要宣称完成；不要用解释替代验证证据。

Commands里立入口。 /verify作为固定触发点。

Hooks里做拦截。 Stop时提醒当前会话还没verify；高风险变更前强提醒。

这一套组合下来，Verify才会从“好习惯”变成系统行为。

十、本章交付

Verify清单：

• 当前任务的targeted behavior是否已经被锁住？
• Build是否通过？
• Typecheck是否通过？
• Lint是否通过？
• Relevant tests是否通过？
• 本次改动是否需要code review？
• 本次改动是否需要security review？
• 是否还有未解释的失败或跳过项？
• 是否可以明确判断为Ready / Not Ready？

社区参考方案：everything-claude-code仓库提供了三个相关命令——/verify（基础四项）、/quality-gate（将验证提升为门禁）、/eval（承接Generator/Evaluator分离）。先明确自己的项目缺少的是基础Verify，还是更成熟的评估闭环，再决定如何借鉴。

最小落地动作：创建.claude/commands/verify.md，先固化基础四项，将review / security review作为第二层补进去。

十一、小结

Plan锁定方向，TDD锁定行为，Verify锁定交付。至此，工作系统开始具备“知道什么时候才算做完”的能力。

但一套系统只要还在靠人工记忆执行，就一定会退化。下一章进入Hooks：把高频、机械、容易遗漏的动作自动化。