Agent 方法论框架 superpowers 完成前验证：不跑命令不许说做完

本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。

Agent 最贵的失败不是写错代码，而是写错了还告诉你写对了。 代码错了你能看见、能回滚；一句没有证据的「已修复」会让你把它当既成事实继续往上叠，两个小时后才在别的地方炸开，那时你已经分不清是哪一步开始跑偏的。superpowers 这套技能库里有一条专门治这个的规则，叫 verification-before-completion，文件在 skills/verification-before-completion/SKILL.md。它通篇没有一行代码，只有一条铁律、一个五步流程和两张对照表，看上去啰嗦到有点冒犯人，但它冲着的正是上面那个毛病。

站内已经写过 Agent 谎报成功怎么办 和 怎么给 Agent 定验收标准，那两篇讲的是通用方法论——为什么会谎报、验收标准该包含什么。本篇不重复这些，只看一个真实开源项目把这套道理落到文件里之后长什么样：规则怎么写、堵在哪几个口子上、代价是什么。

一、它治的是哪个毛病

这条技能的 frontmatter 描述写得很直白，触发时机是「about to claim work is complete, fixed, or passing, before committing or creating PRs」，要求是「running verification commands and confirming output before making any success claims」，末尾还追了一句 evidence before assertions always。

也就是说，它管的不是「怎么修 bug」，而是「你凭什么说修好了」。正文开头把核心原则压成一句：Evidence before claims, always。紧接着是一句很不客气的补充：

Violating the letter of this rule is violating the spirit of this rule.

这句话不是修辞。同一个仓库的 skills/writing-skills/SKILL.md 里有一节叫 Bulletproofing Skills Against Rationalization，明确把「Address Spirit vs Letter Arguments」列为写纪律型技能的必备动作，理由是这一句能一次性砍掉整类「我遵守的是精神实质」的说辞。所以你在技能正文里看到的每一句狠话，背后基本都对应着一个被反复钻过的漏洞。

为什么这个漏洞特别顽固？因为模型给出「应该没问题了」的成本是零，而跑一遍完整测试的成本是真金白银的时间和 token。任何有成本的动作，在压力下都会被找理由跳过。技能里那份 Red Flags 清单直接把这些压力点点名了：用了 should、probably、seems to；在验证之前先表达满意（Great!、Perfect!、Done!）；准备提交或建 PR 却没验证；相信 Agent 自己的成功汇报；只做了部分验证；想着「就这一次」；累了想赶紧收工。最后一条是兜底：任何在没跑验证的情况下暗示成功的措辞。

累了想收工也被写进清单，这个细节挺说明问题——写这条规则的人清楚，纪律崩掉的场合通常不是技术判断失误，而是人和模型都想早点结束。

二、铁律和五步门函数

规则本体只有一行：

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

下面那句解释才是真正卡人的地方：如果你没有在这条消息里跑过验证命令，你就不能说它通过。注意 fresh 和 in this message 这两个限定——上一轮跑过不算，改代码之前跑过更不算。这是把「证据」的有效期压到了一次发言之内。

执行层面是一个五步门函数，正文原样如下：

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

这五步里，第 1 步和第 3 步最容易被忽略。第 1 步逼你先回答「哪条命令能证明这个说法」，很多时候这一问就把人问住了——你说「接口修好了」，但项目里根本没有一条命令能证明这件事，那这句话本来就不该说出口。第 3 步要求读完整输出、看退出码、数失败个数，针对的是另一种常见偷懒：命令跑了，输出扫了一眼，看到一片绿就下结论，没注意末尾还挂着 3 个 failed。

最后一行 Skip any step = lying, not verifying 用词很重。它不给「简化版流程」留位置，跳步就是撒谎，不是省事。

技能里还给了五组场景的正反写法，其中回归测试那组尤其值得抄：

✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
❌ "I've written a regression test" (without red-green verification)

一个只见过绿的回归测试，你无法区分它是真的在守着那个 bug，还是压根没断言到点子上。必须把修复回退掉、亲眼看它变红，这个测试才算有效。这一步几乎所有人都想跳，因为它意味着要把刚修好的代码再弄坏一次。相关的取舍在 Agent 与回归测试 里有更展开的讨论。

三、这条技能由哪些部分构成

它不是一个孤立文件，在仓库里有若干处呼应。下面这张表列的路径都是实际存在的：

组成部分	它负责什么	对应仓库位置	你什么时候会碰到它
技能正文	铁律、五步门函数、常见失败表、合理化对照表、适用范围	skills/verification-before-completion/SKILL.md	Agent 准备说「做完了」的每一次
frontmatter 描述	定义触发时机与硬要求，是技能被选中的依据	同一文件开头的 name 与 description 两行	会话里模型判断该不该调这条技能时
调试流程中的调用点	Verify Fix 阶段明确要求先用这条技能再宣称成功	skills/systematic-debugging/SKILL.md	修完一个 bug 想收工时
防合理化工具箱	解释 Spirit vs Letter 那句话的来历，以及合理化表怎么攒出来	skills/writing-skills/SKILL.md 的 Bulletproofing 一节	你发现 Agent 换个说法就绕过规则时
纪律型技能的测试方法	把这条技能列为 discipline-enforcing 的范例，要求用压力场景测	skills/writing-skills/SKILL.md 的 Testing All Skill Types 一节	你想自己写一条同类硬规则时
技能库入口清单	在 Debugging 分组下列出该技能，一句话概括为确认是真的修好了	README.md	第一次浏览这套技能库时
会话引导规则	要求相关技能必须在任何回应之前被调用	skills/using-superpowers/SKILL.md	每次开新会话

skills/ 目录下一共 14 个技能目录，这条是其中之一。整个仓库以 MIT 许可证发布。

值得单独说的是那两张表。第一张叫 Common Failures，三列分别是「声明」「需要什么才算数」「什么不算数」，覆盖测试通过、linter 干净、构建成功、bug 修复、回归测试有效、Agent 完成、需求满足七种情况。其中「Agent completed」那一行的判据是 VCS diff 显示确有改动，明确写着「Agent reports success」不算数——这一条对任何做多 Agent 编排的人都是直接可用的。「Build succeeds」那行则点名 linter 通过、日志看起来正常都不能代替构建退出码为 0。

第二张叫 Rationalization Prevention，左列是借口，右列是回击：Should work now 对 RUN the verification；I’m confident 对 Confidence ≠ evidence；Just this once 对 No exceptions；Linter passed 对 Linter ≠ compiler；Agent said success 对 Verify independently；I’m tired 对 Exhaustion ≠ excuse；Partial check is enough 对 Partial proves nothing；最后一行是 Different words so rule doesn’t apply 对 Spirit over letter。

按 skills/writing-skills/SKILL.md 的说法，这类表不是坐在书桌前想出来的，而是从压力场景测试里把模型说过的原话逐字捞出来，一条条填进去。所以表格越长，说明这条规则被人钻过的次数越多。这也解释了正文末尾 When To Apply 那节为什么要额外声明规则适用于「同义改写」「暗示成功」「任何暗示完成或正确的表述」——纯粹是因为有人靠换措辞钻过去过。

想了解这类技能在 Claude Code 里以什么形式被加载和触发，可以看 Claude Code Skills 机制。

四、边界与代价

这套东西不是白拿的，几个代价必须说清楚。

它明确不管的事：具体命令是什么。 门函数第 1 步问「什么命令能证明这条声明」，但技能文件里没有任何项目专属的命令、脚本名或配置。这是有意为之的通用化，代价是落到你的仓库里之前，它只是一个空壳。如果你的项目没有一条能跑的测试或构建命令，这条规则会自动降级成一句口号，模型照样会说「做完了」，只是措辞更谨慎一点。

它让开发变慢，而且是结构性变慢。 RUN 那一步写死了 Execute the FULL command (fresh, complete)，合理化表里又写死了 Partial proves nothing。这意味着改一行注释也要跑全量。如果你的测试套件要跑十几分钟，或者按次计费的模型要为每次全量输出付 token，这个成本是可见的、会累加的。这不是能靠调参绕过去的问题，它就是这条规则的定价。

它让 Agent 变啰嗦，而且没那么好相处。 Red Flags 里把「在验证前表达满意」当成危险信号，Great、Perfect、Done 都被点名。遵守这条规则的 Agent 会把每句结论都拖着一段证据说出来，读起来干巴巴的。对喜欢简短确认的人来说，这是体验上的实打实的损失。

对小改动是过度设计。 改一个字符串常量、补一行文档、调整一处日志措辞，走完五步门函数的开销远大于出错的期望损失。技能正文的 When To Apply 里写的是 ALWAYS，没有给改动大小留豁免口子——这是纪律型规则的通病，为了不给合理化留缝，它宁可在小事上浪费。这个取舍你得自己认，或者自己在项目层面划一条例外线（那就等于承认规则有缝，得接受随之而来的滑坡风险）。

它是文档，不是拦截器。 这条技能的载体就是一份 markdown，靠模型读到并遵守生效，仓库里没有任何机制能在模型说出「做完了」的瞬间物理阻止它。skills/using-superpowers/SKILL.md 用了非常强硬的措辞要求技能必须先于任何回应被调用，恰恰说明这一环是靠约定而非强制撑着的。指望它百分之百生效是不现实的。

一些相邻问题它没有覆盖。 比如验证命令本身不可靠怎么办、测试本身是 flaky 的怎么办、验证环境和生产环境不一致怎么办——这些在这份文件里找不到答案，不要脑补它有。

顺带一提，仓库的 RELEASE-NOTES.md 提到这条技能与其他多条技能一起删掉了 Bottom Line、Key Principles、Real-World Impact 这类段落。你现在读到的这份文件之所以这么短、这么密，是刻意精简的结果，不是写得潦草。

五、上手与避坑清单

先把命令写下来，再谈规则。 会踩是因为门函数第 1 步的答案在你脑子里而不在文件里，模型看不到，只能猜。避法是在项目的 Agent 指令文件里，把测试、构建、类型检查、lint 各自的确切命令逐条列清楚，包括在哪个目录下跑。规则和命令清单要一起交给模型，缺一个就废一半。

派活给 Agent 之后，自己查一次 diff。 会踩是因为 Agent 的成功汇报读起来太像真的，尤其当它列了具体文件名和行数的时候。技能的 Common Failures 表把这一条单列成行，判据是 VCS diff 显示确有改动。避法是把「看 diff」当成流程的一部分而不是抽查——汇报和 diff 之间没有必然联系，这一点在 Agent 谎报成功怎么办 里有更多案例。

回归测试必须见过红。 会踩是因为测试写完跑一次就绿了，人的直觉是「绿了就说明它在工作」。实际上你只证明了它现在不报错，没证明它盯着的是那个 bug。避法照抄技能给的顺序：写测试、跑通过、把修复回退、再跑必须失败、恢复修复、再跑通过。少一步就等于没验证。

别拿 linter 的绿灯当构建的绿灯。 会踩是因为 linter 快、构建慢，人天然倾向用快的替代慢的。合理化表里 Linter ≠ compiler 就是专门堵这个。避法是把「构建退出码为 0」作为独立的一条证据，不接受任何替代品。

需求满足和测试通过是两件事。 会踩是因为测试全绿会带来一种「该做的都做了」的错觉，但测试只覆盖了你想到要写测试的那部分。技能给的做法是重读计划、逐条列成清单、逐条核对、报告缺口。避法是把计划文档摊开在旁边对照，而不是凭印象。这一环和 Agent 的自检查清单 是同一件事的两个说法。

留意换词绕过。 会踩是因为模型不会硬顶规则，它会改口——不说「测试通过」，改说「实现已经完成，逻辑上应该没问题」。技能的适用范围一节把同义改写、暗示成功、任何暗示完成或正确的表述全部纳入管辖，就是为了封这个口。避法是在审读 Agent 输出时盯语气词：出现 should、probably、看起来、应该，基本可以判定它没跑验证。

别把这条规则单独抄走。 会踩是因为它看起来自成一体，抄一页就完事。但它在仓库里是被 skills/systematic-debugging/SKILL.md 的修复阶段调用的，孤立使用会失去触发时机。避法是连同你自己的调试流程一起改造，明确写清在哪个节点必须过这道门。

收尾

这条技能的全部价值可以压成一个动作：在说出任何结论之前，先回答「哪条命令能证明它」，然后把命令跑完、把输出读完。做不到这一点，后面所有的流程设计都是在流沙上盖房子。

给你一份最小自检清单，可以直接贴到项目文档里：这句话对应哪条命令？这条命令是刚才跑的还是之前跑的？我读的是完整输出还是片段？退出码是多少，失败几个？如果是回归测试，它红过没有？如果活是 Agent 干的，我看过 diff 没有？六个问题全过了，再说结论。

想继续往下读，仓库里最值得接着打开的两个文件是 skills/systematic-debugging/SKILL.md（看这道门被安在调试流程的哪个位置）和 skills/writing-skills/SKILL.md（看纪律型技能该怎么写、怎么用压力场景测）。这两份读完，你大概就能自己给团队写第一条硬规则了。

本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。