verification-before-completion

verification-before-completion 技能概览

verification-before-completion 是做什么用的

verification-before-completion 技能是一套严格的“完成前最终校验”流程，适用于你正准备说某项工作“已完成”“已修复”“已通过”或“可提交评审”的时刻。它的目标很简单：阻止没有证据支撑的成功表述，先拿到最新验证结果再下结论。

它尤其适合 AI 辅助编程、agent 工作流、commit 准备和 PR 交接。如果你经常看到“tests should pass”“bug is fixed”或“build looks good”这类话，却没有真正执行对应命令，这个技能就是专门针对这种失误模式设计的。

哪些人适合安装这个技能

最适合的用户包括：

• 使用 AI agent 修改代码的开发者
• 希望状态更新更干净、且有证据支撑的评审者
• 受够了“乐观但未验证”的完成消息的团队
• 在 Skill Validation 场景下，更看重证明而不是信心的用户

如果你主要需要的是代码生成、方案规划或广义的调试帮助，那它并不能替代这些技能。verification-before-completion 是一道护栏，不是一整套交付流程。

它真正要解决的任务是什么

真正的任务不是“跑一下测试”，而是：

1. 先明确什么证据才能证明这句话成立
2. 现在立刻执行那个精确的验证
3. 阅读真实输出结果
4. 只说证据真正能支持的话

这听起来很理所当然，但很多 AI 辅助工作流恰恰就断在这里。这个技能把这种要求变成了在使用完成类措辞之前必须通过的硬门槛。

这个技能的差异点在哪里

它最核心的特点是“足够窄”。verification-before-completion 不试图理解你整个仓库，也不打算包办所有判断。它只强制执行一条高价值规则：

没有最新验证证据，就不要做完成类声明

正因为聚焦，它非常适合作为收尾层技能使用。相比普通“请谨慎并验证”的提示词，它更容易被稳定触发，因为它给出了一套可重复执行的判断函数：先识别，再执行，再读取，再验证，最后再表述。

什么情况下这个技能特别合适

当你准备说出下面这些话时，就很适合使用 verification-before-completion 技能：

• “tests pass”
• “the bug is fixed”
• “the build succeeds”
• “this is ready to merge”
• “the linter is clean”

这些说法分别需要不同的证据。这个技能能有效避免一种常见错误：只证明了“相关但不等价”的事情，却把结论说得更大。

如何使用 verification-before-completion 技能

verification-before-completion 的安装方式

从 obra/superpowers 仓库安装：

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

由于这个技能只包含一个 SKILL.md，上手成本很低。你不需要先理解辅助脚本，也没有额外资源文件要处理。

先读这个文件

从这里开始：

• skills/verification-before-completion/SKILL.md

这个文件包含了完整的行为约定。由于该技能几乎没有额外的仓库支撑结构，先读 SKILL.md，基本就足以判断它是否适合你的工作流。

这个技能需要你提供什么输入

verification-before-completion 技能在你提供以下三类信息时效果最好：

• 你准备做出的具体声明
• 能真正证明该声明的命令
• 当前有哪些环境限制阻碍了验证

输入示例：

• “I want to say the fix works. The proving command is pytest tests/api/test_login.py -q.”
• “I want to say the build passes. The expected verification is npm run build.”
• “I think lint is clean, but I have not run ruff check . yet.”

如果没有明确的声明和对应命令，这个技能最多只能给出泛泛的提醒，无法提供高质量判断。

把模糊目标改写成可用提示词

弱提示词：

• “Can I say this is done?”

更好的提示词：

• “Before I claim this is complete, apply the verification-before-completion skill. The claim is: ‘the login bug is fixed.’ The best proving command is pytest tests/auth/test_login_bug.py -q. If that is not enough, tell me what additional verification is required.”

为什么这样更好：

• 它明确指出了要说的结论
• 它给出了证明路径
• 它允许技能质疑验证是否力度不足

在实际工作里怎么调用这个技能

把 verification-before-completion 放在任何“完成式消息”、commit 摘要或 PR 说明之前使用。一个实用流程是：

1. 先完成代码修改
2. 明确你到底想对外说什么
3. 找出哪条命令能证明这句话
4. 重新执行完整命令
5. 检查输出和退出状态
6. 如果证据不完整，就降低结论强度或加限定语

这个顺序很关键。人最容易在准备总结的时候变得“乐观表述”，而这个技能在这个节点价值最高。

让结论和证据一一对应

verification-before-completion 技能一个非常实用的价值，是能阻止“证明和结论不匹配”。

例如：

• 结论：“Tests pass”
  证据：相关的完整测试命令，且零失败

• 结论：“Linter is clean”
  证据：linter 命令输出零错误

• 结论：“Build succeeds”
  证据：build 命令成功退出

• 结论：“Bug is fixed”
  证据：能够复现原始失败路径的验证步骤，现在已通过

linter 通过，并不能证明 build 成功。文件改了，也不能证明 bug 已修复。很多质量不高的 agent 输出，问题就出在这里。

什么才算“最新验证证据”

所谓最新，指的是命令是针对当前这次代码状态重新执行得到的，而不是凭之前某次尝试的结果来判断。实际操作里，这意味着：

• 不依赖旧的终端输出
• 不假设“文件没怎么变，结果应该也没变”
• 不根据周边信号去推断成功
• 不拿局部验证去支撑更大的结论

如果你在上次执行后又改了代码，那么对“是否可以宣称完成”来说，那次旧结果就已经过期了。

无法执行验证时该怎么做

有时环境确实无法执行验证：依赖缺失、没有凭据、服务不可用、OS 不支持，或者时间不允许。这种情况下，不要继续给出更强的结论。

改用基于证据的表述：

• “I made the change, but I could not run npm test in this environment.”
• “The fix is implemented, but build verification remains unconfirmed.”
• “I verified formatting only; full integration tests were not run.”

这样依然算是成功使用了 verification-before-completion，因为它追求的是如实汇报状态，而不是强行制造确定性。

适合 agent 的实用提示词模板

一条强且可复用的提示词：

“Use the verification-before-completion skill before any success claim. For each claim, identify the proving command, run it fresh if possible, read the full output, and only state what the evidence confirms. If verification is blocked, report the limitation instead of implying success.”

这类提示词很适合放进 agent 指令、PR assistant 和 commit 生成流程中。

适用于 Skill Validation 场景的最佳工作流

对于 verification-before-completion for Skill Validation，更适合把它当作最终验证器，而不是主执行者。推荐流程是：

1. 先用其他技能做实现或调试
2. 再切换到 verification-before-completion
3. 验证你准备发布的那条具体结论
4. 用命令和结果证据生成总结

这样把“实现”和“验证”分开，可信度会更高，因为两者不会混在一起。

verification-before-completion 技能 FAQ

verification-before-completion 只是提醒你跑测试吗？

不是。verification-before-completion 技能比“记得跑一下测试”严格得多。它要求的是“声明和证明之间的明确映射”。重点不只是“去跑点什么”，而是“执行那条能够证明你即将说出口那句话的命令”。

这个技能对新手有用吗？

有，尤其适合还在学习“不同检查到底分别能证明什么”的新手。它会强化一个很重要的习惯：不要让结论超出证据范围。这个习惯既能提高技术准确性，也能提升评审对你的信任。

什么情况下不该用 verification-before-completion？

不要把它当成你唯一的编码或调试技能。它不会帮你设计架构、定位根因，也不会替你写出完整测试计划。它更像一个收尾检查点，最好与偏实现导向的技能搭配使用。

它为什么比普通提示词更好？

普通提示词常常只是说一句“回答前先验证”，但 agent 仍然很容易滑向模糊、偏软的成功表述。verification-before-completion skill 更适合需要稳定“完成前闸门”的场景，因为它会对缺乏证据支撑的断言施加明确后果。

它要求特定技术栈或工具链吗？

不要求。这个技能与技术栈无关，因为它关注的是证据逻辑，而不是语言或框架本身。你只需要提供适用于自己环境的证明命令，无论那是 pytest、npm test、go test、cargo test，还是其他验证方式。

如果完整验证成本太高，还能用吗？

可以，但你的结论也必须相应收窄。如果你只跑了一个定向测试，那就只说明这个定向测试通过了。除非你执行了更全面的证明，否则不要把它升级成“everything passes”。

如何改进 verification-before-completion 技能的使用效果

请求验证前，先把要说的结论写清楚

提升输出质量最明显的方法，就是先把你“准备写出去的那句话”明确说出来。例如：

• 弱：“validate this”
• 强：“I want to say: ‘the payment bug is fixed and tests pass’”

这样技能就能把复合型声明拆开，并为每一部分分别匹配证据。

明确写出最合适的证明命令

如果你已经知道仓库里的标准验证方式，就不要让技能去猜。更强的输入方式是：

• “The canonical project check is make test.”
• “The bug is proven by pytest tests/payments/test_refund.py -q plus npm run build.”

这能减少因为检查不完整而产生的虚假信心。

把“已实现”与“已验证”分开

一种非常常见的失误，是把“我改了代码”和“问题已解决”混为一谈。想提升 verification-before-completion usage 的效果，可以直接要求输出分成两部分：

• 改了什么
• 实际验证了什么

即使执行被环境阻断，这也能让总结保持诚实可靠。

不要用窄验证去支撑大结论

如果你只跑了一个聚焦测试，就不要让技能替整个仓库背书。更好的问法是：

• “Can I say the targeted regression test now passes?”
• 而不是 “Can I say the system is fully fixed?”

这是这个技能最值得养成的习惯之一。

证据不完整时，主动要求降级措辞

在真实工作里，提升 verification-before-completion guide 实用性的一个好方法，是直接请求备用表述：

• “If the claim is too strong for the evidence, rewrite it to the strongest accurate version.”

这样它就不只是个拦截器，也能成为提升沟通质量的工具。

有实质改动后要重新验证

如果你在一次成功验证之后又修改了代码，就应该再次使用 verification-before-completion 技能。最新证据只对应当前状态，不对应上一个草稿版本。对高频 agent 循环尤其如此，因为哪怕只是“最后一个小改动”，也可能让之前的验证失效。

在最终总结里直接附上证据

如果想让人更信服，最好在完成说明里直接带上证明信息：

• 执行了什么命令
• 结果是 pass 还是 fail
• 是否存在限制或遗漏

例如：

• “Verified with pytest tests/auth/test_login_bug.py -q: passed, 1 test, 0 failures.”
• “Did not verify full integration suite in this environment.”

这种写法会让这个技能对评审者以及未来回看记录的你都更有价值。

盯住最常见的失败模式

verification-before-completion for Skill Validation 最常见的误用，就是根据意图、代码改动或主观预期来宣称成功，而不是根据输出结果。如果你想得到更稳定的效果，那就在每次输出完成类消息前，最后问自己一句：

“什么样的命令输出，才能让这句话成立？”

如果你没法清楚回答，说明这个结论大概率还没准备好。