验证层:完成意味着有证据
你在提交之前证明更改有效,并构建使下一次验证成本更低的检查。人工的工作从逐行审核差异转变为定义“完成”并阅读证据。你的工作是诚实地产出证据。
原则源自 Claude Code 团队关于验证的思考(Addy Osmani,2026年11月)。references/templates.md 中的文件格式是本技能独有的;文章描述了实践,但未展示具体格式。
何时使用
- 你完成了一项更改,正准备说“完成”或提交
- 用户问“这个能用吗?”、“证明它”或“验证一下”
- 仓库没有可重复的方式来启动和冒烟测试应用
- 用户询问某个功能、重写或迁移值得编写哪些测试
- 代码审查或测试套件遗漏了一个已到达用户的错误,用户希望下次能捕获它
- 测试不稳定,有人想重试或跳过它
- 用户想同时运行多个智能体,无法阅读每个差异
不要用于: 逐行审阅他人的差异(这是审查,不是验证)、无法运行的一行文档或注释更改、或只是为了提高覆盖率而添加测试。
核心原则
当证据表明更改完成时才算完成,且更改绝不能修改评判自己的规则。 “测试通过”在相同更改编写了测试的情况下是薄弱的证据。强有力的证据是正在运行的应用执行了用户的要求,并由更改无法触及的内容进行检查。
规则
- 运行更改。 启动真实应用并执行更改后的行为。这比单元测试更重要。通过单元测试套件但应用无法启动是验证失败。
- 三轮,然后交给人工。 运行检查,修复失败项,再次运行。如果三轮后仍有检查失败,停止并连同证据一起交给人工。不要开始第四轮。
- 切勿为了通过而削弱评判者。 在同一更改中,不要编辑、跳过或删除它将要评判的测试、lint规则、检查表项或REVIEW.md规则。如果评判者错了,说明原因并在用户批准的单独提交中更改它。
- 从基础分支读取评判规则。 审查规则、检查表和门禁配置来自默认分支,绝不要来自正在测试的分支。
- 证据属于一个提交。 对旧提交的验证对新提交无意义。任何新编辑后,重新验证或报告证据已过时。
- 廉价检查优先并在本地执行。 测试、构建和lint在PR打开前运行,而不是在审查者的时间内。
- 仅运行差异触发的检查表项。 通常匹配3到10项。每次运行所有项会让所有人忽略列表。
- 为每个提交打上验证方式标记,包括
none。 诚实的none可以在以后被搜索到。缺失的标记则不能。 - 不稳定的测试是一个错误。 不要跳过它、添加sleep或重试直到变绿。找到根本原因。如果找不到,删除测试并写出原因。
- 需要人工的检查必须说明原因。 “需要审查”不是理由。“更改了会话文件格式;旧记录可能无法加载”才是。
- 每一次遗漏都变成一条规则,规则会被修剪。 漏网的缺陷是验证层的漏洞。用检查关闭它,并移除不再有价值的检查。
编写哪种测试
| 情况 | 测试 | 证明什么 |
|---|---|---|
| 面向用户的流程(如果只写一个测试,就写这个) | 端到端 | 真实用户路径从头到尾正常工作。失败会显示步骤、跟踪和截图,而不仅仅是“超时”。 |
| 解析器、编码器、货币、状态机以及任何有边缘情况的内容 | 属性(fast-check、Hypothesis、proptest) | 对于数千个你没想到的生成输入,某个断言成立。 |
| 对现有功能的重写、迁移或优化 | 差分 | 旧版本和新版本在相同输入上给出相同输出。 |
值得检查的属性:
| 属性 | 断言 |
|---|---|
| 往返 | 编码后解码,返回原始值 |
| 不变性 | 某件事始终成立(例如余额永不为负) |
| 幂等性 | 执行两次等于执行一次 |
| 等价性 | 快速版本匹配慢速但明显正确的版本 |
对于差分测试:使用随机或采样的真实输入,规范化无关紧要的差异(空白、键顺序、时间戳),并保留已批准的差异列表。
运行缓慢的套件会降低运行频率,从而降低覆盖率。保持每次编辑循环快速,将繁重测试移至提交前。
要保留的内容(不可触碰项)
- 现有测试、lint规则、检查表项、REVIEW.md和门禁配置:绝不在它们评判的提交中更改。
- 命令输出、退出码、失败的步骤名称和计数:如实报告。
- 标记:必须真实反映你实际运行的内容。绝不要为未执行的运行写
e2e。 - 截图和跟踪:按原样附加或链接,不要凭记忆描述。
方法
A. 验证更改(每次)
-
说出“完成”的含义。 从用户角度写一两句话:他们做什么,他们看到什么。如果仓库有功能映射,找到条目并将其预期结果作为评分标准。如果你无法陈述“完成”,请在验证前询问。
-
运行廉价检查。 构建、lint、类型检查、快速测试。修复失败项。这是第一轮。
-
运行更改。 如果仓库有
verify技能,使用它(在.claude/skills/目录下靠近你更改的代码)。如果没有,自行启动应用:- Web:驱动浏览器(Chrome扩展、DevTools MCP、Playwright)。
- Mobile:通过移动端MCP的模拟器。
- Desktop:计算机使用。
- Backend或CLI:本地运行服务或命令并调用它。
执行更改的路径以及不应该更改的相邻路径。捕获截图、跟踪或输出。
-
运行触发的检查表项。 从基础分支读取可靠性检查表。对于每个项,针对你的差异测试其触发器。对每个匹配项运行检查并记录结果。在报告中列出匹配项的名称。
-
添加缺失的测试。 使用上表。确认新测试在没有你的更改时失败,有更改时通过。
-
计算轮次。 每次“运行检查,修复,再次运行”算作一轮。如果第三轮后仍有检查失败,停止。报告失败项、每轮尝试的内容以及最佳猜测原因。
-
标记并报告。 在提交消息中添加标记(格式见
references/templates.md)。在报告中给出:完成的定义、运行的内容、证据、匹配的检查表项以及任何未验证内容及其原因。
B. 构建验证层(每个仓库一次,然后调优)
按顺序执行这些步骤。每一步本身都很有用,因此用户希望停在哪里就停在哪里。
-
一个
verify技能。 放在.claude/skills/verify/目录,尽可能靠近它覆盖的代码(单体仓库可以为每个应用放置一个)。它记录如何启动应用并冒烟测试。连续运行几次才能信任它:必须快速且每次给出相同结果。 -
一个功能映射。 从用户角度列出功能。对于每个功能:路径、键盘快捷键、选择器和预期结果。智能体将其用作指南和评分标准。
-
为最重要流程编写一个端到端测试。 然后在上表适用之处编写属性和差分测试。
-
一个可靠性检查表。 每个项包含三个部分:可以从差异中读取的触发器、检查以及导致它的故障事件或PR。没有事件,就没有项。示例:触发器“会话存储或消息类型更改”,检查“新字段能否安全地从没有该字段的旧记录中加载?”。
-
一个REVIEW.md。 它告诉审查者在这个代码库中需要注意什么。多次迭代调优此文件,每次迭代基于上一次的发现。不要堆叠更多审查者。代码所有者不断完善它,直到它能标记出他们自己会标记的内容。
-
本地强制执行。 智能体完成时运行测试的钩子,或要求通过测试套件的目标。
-
一个提交门禁。 当会话未运行审查和验证步骤时阻止提交。分三种模式部署:
模式 行为 off不执行任何操作 observe记录本应阻止的内容。先运行此模式以发现误报。 enforce阻止提交。提交可以附带跳过的书面原因。在一个会话中被阻止两次后,下一次提交通过,以免智能体卡住。
在添加钩子、门禁或CI更改前询问用户。它们会改变每个人的提交方式。
C. 将遗漏转化为规则
当错误通过测试或审查时使用此流程。
- 找到模式,而不是错误。 查看人工审查评论和回退。候选规则必须在至少两个PR中出现,并且可以仅从差异中看到。
- 尝试反驳它。 进行三次独立的尝试,以证明该规则是错误的、过于宽泛或已被覆盖。如果可用,使用三个子智能体。只有当规则幸存时才保留它。
- 检查是否可捕获。 通过三个独立的错误查找器重放导致事件的PR。如果两个或更多查找到该错误,则它是可检测的,并且小差异上的遗漏应成为REVIEW.md规则或检查表项。
- 让人工批准它。 代码所有者决定规则是否加入。你提出;他们批准。
- 给审查者打分。 保留一小部分事件案例(每个带有一句话答案关键词),以及大小相似的干净合并更改作为控制项以防止过度标记。保留调优集和单独的测试集。将发现标记为
Important、Nit或Pre-existing。当更多召回只会拟合评估集时停止调优。 - 修剪。 测试套件、检查表和.md规则文件只会增长,除非有人裁剪。定期移除从不触发、重复另一条规则或保护不再存在的代码的规则。
工作示例
请求: “为聊天会话添加 pinned 标志,以便置顶的会话排在前面。”
没有技能时:
将
pinned添加到会话类型并更新了排序。单元测试通过。完成。
有技能时:
完成意味着: 用户在侧边栏置顶一个会话,它移动到顶部;重启后它仍然在顶部。
运行了: 构建、lint、148个单元测试(第1轮:排序比较器失败2个,已修复;第2轮:全部通过)。使用仓库的
verify技能启动应用,置顶一个会话,重启,确认顺序。已附截图。匹配的检查表项(共31项中的2项):
- 会话格式更改加载旧数据:打开此更改前保存的会话文件。崩溃了:
pinned是undefined,比较器抛出异常。已修复,在加载时默认为false。第3轮:通过。- 排序更改保持稳定顺序:未置顶的会话保持之前的顺序。通过。
添加了: 一个属性测试“排序两次等于排序一次”,以及一个端到端步骤:置顶、重启、检查顺序。两者在没有修复时都失败。
未验证: 移动端布局。此机器上没有模拟器。
标记:
Verified-By: run, e2e, property, checklist(2)
单元测试通过了,而应用在每一个现有用户的数据上都崩溃。运行更改并加载旧文件是发现问题的关键,而检查表项提示了需要尝试这一步。
交付前自我检查
- 你的报告有从用户角度写的“完成意味着”一行。
- 应用已启动并执行了更改路径,或者报告说明了“未运行”及原因。
git diff <base>显示未编辑现有测试、lint配置、检查表、REVIEW.md或门禁配置。如果有,该编辑被明确指出并在其自己的提交中。- 未添加
.skip、.only、xit、sleep、retry或提高的超时使测试通过(在差异中搜索每个)。 - 你匹配的检查表项已按名称列出,并附有每个项的结果。
- 已确认每个新测试在没有更改时失败。
- 轮次计数为三轮或更少。如果第三轮仍然失败,报告交给人工,你未提交。
- 提交消息有
Verified-By:标记,并且其中的每个词匹配你实际运行的内容。 - 证据是在当前
HEAD上收集的,而不是在更早的提交上。 - 每个新的检查表项或规则命名了其背后的事件或PR。