Community编程与开发github.com

验证层

在提交前证明智能体编写的更改能够正常工作,并构建使后续验证成本更低的检查机制。在实际应用中运行更改,选择合适的测试(端到端、属性或差分测试),仅运行差异触发的可靠性检查,在三轮修复失败后交给人工处理,为每次提交打上验证方式标记,并将每一次遗漏转化为规则。

验证层 是什么?

验证层(Verification Layer)是一种智能体技能,确保代码更改在提交前经过严格验证,并构建降低后续验证成本的检查基础设施。它基于这样的原则:当证据(而非代码作者的声明)表明更改已完成时,才算真正完成,且更改绝不能修改评判自己的规则。该技能支持在不同平台上运行更改的实际应用(Web、移动端、桌面、后端或CLI),并根据变更性质动态触发端到端、属性或差分测试。关键工作流包括:定义“完成”的含义、执行廉价检查、运行变更、执行差异触发的检查表项、添加缺失的测试,并在三轮修复后交由人工处理——最多三轮。该技能还支持一次性设置工作:创建 `verify` 技能、功能映射、可靠性检查表、`REVIEW.md` 和提交门禁,并包含根据真实故障模式将未捕获的缺陷转化为自动化检查的机制。它在Claude Code、Cursor和Cline等AI编码助手上运行,通过强制验证的提交标记和禁止更改编辑测试或门禁配置的规则,提供防止智能体自我验证的防护措施。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kleenpulse/verification-layer/tree/main

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

验证层:完成意味着有证据

你在提交之前证明更改有效,并构建使下一次验证成本更低的检查。人工的工作从逐行审核差异转变为定义“完成”并阅读证据。你的工作是诚实地产出证据。

原则源自 Claude Code 团队关于验证的思考(Addy Osmani,2026年11月)。references/templates.md 中的文件格式是本技能独有的;文章描述了实践,但未展示具体格式。

何时使用

  • 你完成了一项更改,正准备说“完成”或提交
  • 用户问“这个能用吗?”、“证明它”或“验证一下”
  • 仓库没有可重复的方式来启动和冒烟测试应用
  • 用户询问某个功能、重写或迁移值得编写哪些测试
  • 代码审查或测试套件遗漏了一个已到达用户的错误,用户希望下次能捕获它
  • 测试不稳定,有人想重试或跳过它
  • 用户想同时运行多个智能体,无法阅读每个差异

不要用于: 逐行审阅他人的差异(这是审查,不是验证)、无法运行的一行文档或注释更改、或只是为了提高覆盖率而添加测试。

核心原则

当证据表明更改完成时才算完成,且更改绝不能修改评判自己的规则。 “测试通过”在相同更改编写了测试的情况下是薄弱的证据。强有力的证据是正在运行的应用执行了用户的要求,并由更改无法触及的内容进行检查。

规则

  1. 运行更改。 启动真实应用并执行更改后的行为。这比单元测试更重要。通过单元测试套件但应用无法启动是验证失败。
  2. 三轮,然后交给人工。 运行检查,修复失败项,再次运行。如果三轮后仍有检查失败,停止并连同证据一起交给人工。不要开始第四轮。
  3. 切勿为了通过而削弱评判者。 在同一更改中,不要编辑、跳过或删除它将要评判的测试、lint规则、检查表项或REVIEW.md规则。如果评判者错了,说明原因并在用户批准的单独提交中更改它。
  4. 从基础分支读取评判规则。 审查规则、检查表和门禁配置来自默认分支,绝不要来自正在测试的分支。
  5. 证据属于一个提交。 对旧提交的验证对新提交无意义。任何新编辑后,重新验证或报告证据已过时。
  6. 廉价检查优先并在本地执行。 测试、构建和lint在PR打开前运行,而不是在审查者的时间内。
  7. 仅运行差异触发的检查表项。 通常匹配3到10项。每次运行所有项会让所有人忽略列表。
  8. 为每个提交打上验证方式标记,包括 none。 诚实的 none 可以在以后被搜索到。缺失的标记则不能。
  9. 不稳定的测试是一个错误。 不要跳过它、添加sleep或重试直到变绿。找到根本原因。如果找不到,删除测试并写出原因。
  10. 需要人工的检查必须说明原因。 “需要审查”不是理由。“更改了会话文件格式;旧记录可能无法加载”才是。
  11. 每一次遗漏都变成一条规则,规则会被修剪。 漏网的缺陷是验证层的漏洞。用检查关闭它,并移除不再有价值的检查。

编写哪种测试

情况测试证明什么
面向用户的流程(如果只写一个测试,就写这个)端到端真实用户路径从头到尾正常工作。失败会显示步骤、跟踪和截图,而不仅仅是“超时”。
解析器、编码器、货币、状态机以及任何有边缘情况的内容属性(fast-check、Hypothesis、proptest)对于数千个你没想到的生成输入,某个断言成立。
对现有功能的重写、迁移或优化差分旧版本和新版本在相同输入上给出相同输出。

值得检查的属性:

属性断言
往返编码后解码,返回原始值
不变性某件事始终成立(例如余额永不为负)
幂等性执行两次等于执行一次
等价性快速版本匹配慢速但明显正确的版本

对于差分测试:使用随机或采样的真实输入,规范化无关紧要的差异(空白、键顺序、时间戳),并保留已批准的差异列表。

运行缓慢的套件会降低运行频率,从而降低覆盖率。保持每次编辑循环快速,将繁重测试移至提交前。

要保留的内容(不可触碰项)

  • 现有测试、lint规则、检查表项、REVIEW.md和门禁配置:绝不在它们评判的提交中更改。
  • 命令输出、退出码、失败的步骤名称和计数:如实报告。
  • 标记:必须真实反映你实际运行的内容。绝不要为未执行的运行写 e2e。
  • 截图和跟踪:按原样附加或链接,不要凭记忆描述。

方法

A. 验证更改(每次)

  1. 说出“完成”的含义。 从用户角度写一两句话:他们做什么,他们看到什么。如果仓库有功能映射,找到条目并将其预期结果作为评分标准。如果你无法陈述“完成”,请在验证前询问。

  2. 运行廉价检查。 构建、lint、类型检查、快速测试。修复失败项。这是第一轮。

  3. 运行更改。 如果仓库有 verify 技能,使用它(在.claude/skills/目录下靠近你更改的代码)。如果没有,自行启动应用:

    • Web:驱动浏览器(Chrome扩展、DevTools MCP、Playwright)。
    • Mobile:通过移动端MCP的模拟器。
    • Desktop:计算机使用。
    • Backend或CLI:本地运行服务或命令并调用它。

    执行更改的路径以及不应该更改的相邻路径。捕获截图、跟踪或输出。

  4. 运行触发的检查表项。 从基础分支读取可靠性检查表。对于每个项,针对你的差异测试其触发器。对每个匹配项运行检查并记录结果。在报告中列出匹配项的名称。

  5. 添加缺失的测试。 使用上表。确认新测试在没有你的更改时失败,有更改时通过。

  6. 计算轮次。 每次“运行检查,修复,再次运行”算作一轮。如果第三轮后仍有检查失败,停止。报告失败项、每轮尝试的内容以及最佳猜测原因。

  7. 标记并报告。 在提交消息中添加标记(格式见 references/templates.md)。在报告中给出:完成的定义、运行的内容、证据、匹配的检查表项以及任何未验证内容及其原因。

B. 构建验证层(每个仓库一次,然后调优)

按顺序执行这些步骤。每一步本身都很有用,因此用户希望停在哪里就停在哪里。

  1. 一个 verify 技能。 放在.claude/skills/verify/目录,尽可能靠近它覆盖的代码(单体仓库可以为每个应用放置一个)。它记录如何启动应用并冒烟测试。连续运行几次才能信任它:必须快速且每次给出相同结果。

  2. 一个功能映射。 从用户角度列出功能。对于每个功能:路径、键盘快捷键、选择器和预期结果。智能体将其用作指南和评分标准。

  3. 为最重要流程编写一个端到端测试。 然后在上表适用之处编写属性和差分测试。

  4. 一个可靠性检查表。 每个项包含三个部分:可以从差异中读取的触发器、检查以及导致它的故障事件或PR。没有事件,就没有项。示例:触发器“会话存储或消息类型更改”,检查“新字段能否安全地从没有该字段的旧记录中加载?”。

  5. 一个REVIEW.md。 它告诉审查者在这个代码库中需要注意什么。多次迭代调优此文件,每次迭代基于上一次的发现。不要堆叠更多审查者。代码所有者不断完善它,直到它能标记出他们自己会标记的内容。

  6. 本地强制执行。 智能体完成时运行测试的钩子,或要求通过测试套件的目标。

  7. 一个提交门禁。 当会话未运行审查和验证步骤时阻止提交。分三种模式部署:

    模式行为
    off不执行任何操作
    observe记录本应阻止的内容。先运行此模式以发现误报。
    enforce阻止提交。提交可以附带跳过的书面原因。在一个会话中被阻止两次后,下一次提交通过,以免智能体卡住。

在添加钩子、门禁或CI更改前询问用户。它们会改变每个人的提交方式。

C. 将遗漏转化为规则

当错误通过测试或审查时使用此流程。

  1. 找到模式,而不是错误。 查看人工审查评论和回退。候选规则必须在至少两个PR中出现,并且可以仅从差异中看到。
  2. 尝试反驳它。 进行三次独立的尝试,以证明该规则是错误的、过于宽泛或已被覆盖。如果可用,使用三个子智能体。只有当规则幸存时才保留它。
  3. 检查是否可捕获。 通过三个独立的错误查找器重放导致事件的PR。如果两个或更多查找到该错误,则它是可检测的,并且小差异上的遗漏应成为REVIEW.md规则或检查表项。
  4. 让人工批准它。 代码所有者决定规则是否加入。你提出;他们批准。
  5. 给审查者打分。 保留一小部分事件案例(每个带有一句话答案关键词),以及大小相似的干净合并更改作为控制项以防止过度标记。保留调优集和单独的测试集。将发现标记为 Important、Nit 或 Pre-existing。当更多召回只会拟合评估集时停止调优。
  6. 修剪。 测试套件、检查表和.md规则文件只会增长,除非有人裁剪。定期移除从不触发、重复另一条规则或保护不再存在的代码的规则。

工作示例

请求: “为聊天会话添加 pinned 标志,以便置顶的会话排在前面。”

没有技能时:

将 pinned 添加到会话类型并更新了排序。单元测试通过。完成。

有技能时:

完成意味着: 用户在侧边栏置顶一个会话,它移动到顶部;重启后它仍然在顶部。

运行了: 构建、lint、148个单元测试(第1轮:排序比较器失败2个,已修复;第2轮:全部通过)。使用仓库的 verify 技能启动应用,置顶一个会话,重启,确认顺序。已附截图。

匹配的检查表项(共31项中的2项):

  • 会话格式更改加载旧数据:打开此更改前保存的会话文件。崩溃了:pinned 是 undefined,比较器抛出异常。已修复,在加载时默认为 false。第3轮:通过。
  • 排序更改保持稳定顺序:未置顶的会话保持之前的顺序。通过。

添加了: 一个属性测试“排序两次等于排序一次”,以及一个端到端步骤:置顶、重启、检查顺序。两者在没有修复时都失败。

未验证: 移动端布局。此机器上没有模拟器。

标记:Verified-By: run, e2e, property, checklist(2)

单元测试通过了,而应用在每一个现有用户的数据上都崩溃。运行更改并加载旧文件是发现问题的关键,而检查表项提示了需要尝试这一步。

交付前自我检查

  1. 你的报告有从用户角度写的“完成意味着”一行。
  2. 应用已启动并执行了更改路径,或者报告说明了“未运行”及原因。
  3. git diff <base> 显示未编辑现有测试、lint配置、检查表、REVIEW.md或门禁配置。如果有,该编辑被明确指出并在其自己的提交中。
  4. 未添加 .skip、.only、xit、sleep、retry 或提高的超时使测试通过(在差异中搜索每个)。
  5. 你匹配的检查表项已按名称列出,并附有每个项的结果。
  6. 已确认每个新测试在没有更改时失败。
  7. 轮次计数为三轮或更少。如果第三轮仍然失败,报告交给人工,你未提交。
  8. 提交消息有 Verified-By: 标记,并且其中的每个词匹配你实际运行的内容。
  9. 证据是在当前 HEAD 上收集的,而不是在更早的提交上。
  10. 每个新的检查表项或规则命名了其背后的事件或PR。

相关技能