verification-before-completion

概览

verification-before-completion 技能是什么？

verification-before-completion 技能为开发者和代理（agents）定义了一条严格的工作流规则：除非你刚刚运行过相关验证命令并检查了其输出，否则绝不能说工作已完成、测试已通过或 Bug 已修复。其核心原则是：

先有证据，再下结论，且必须是最新证据。

在实际工作中，这意味着，在你写下「tests are passing」「the build is green」或「the bug is fixed」之前，必须先：

• 找到能够支撑该结论的命令
• 重新执行该命令（不能依赖旧的执行结果或主观假设）
• 阅读命令输出和退出状态
• 只有在此之后，才能给出结论，并明确是由这份证据支撑

适合哪些人使用？

在以下情况中，你应该考虑使用 verification-before-completion 技能：

• 你所在的代码库经常出现测试未通过、构建损坏或修复未验证就被合入的情况
• 你依赖 agents 或自动化工具，而它们可能在未实际执行检查的情况下就声称成功
• 你希望在开发工作流中建立一种有纪律、可重复的测试与验证实践

它尤其适用于：

• 测试自动化：确保测试集确实被执行，并且结果被正确解读
• 工作流自动化：强制要求所有「完成」步骤必须包含验证命令
• 实行代码评审（code review）、持续集成（CI）、持续交付（CD）并希望在标记为「done」之后减少意外的团队。

verification-before-completion 解决了什么问题？

如果没有这道防护，很容易出现：

• 认为改动「很小」，就想当然地觉得测试会通过
• 改了代码就宣称 Bug 已修复，却没有重新运行之前失败的场景
• 依赖之前一次成功的构建，而不是在变更后重新构建

verification-before-completion 技能在仓库中将这定义为一条 Iron Law（铁律）：

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

采用该技能后，你会把这条铁律转化为自己、团队或代理的具体工作流规则，从而减少：

• 在 pull request 中虚假的「绿灯」声明
• 从未真正测试过的隐藏回归问题
• 开发者、评审者与自动化系统之间的误解和信息不对称

什么时候适合使用这个技能？

在以下情况下，verification-before-completion 是一个很好的选择：

• 你的项目已经有可用的 test、lint 或 build 命令，并希望确保它们总是被执行
• 你使用 agents 或脚本辅助开发任务，并需要它们在验证上足够严格
• 比起节省几秒钟，你更在意状态报告的可靠性

在这些情况下它可能价值有限：

• 你的项目目前还没有有意义的自动化检查（没有 tests、没有 lints、没有 build 命令）
• 你正在进行探索性开发，还没有准备好给出「通过」或「已修复」这类结论
• 你只是把这个仓库当作概念参考，而不是用来严格约束工作流

即便如此，你仍然可以把这个技能作为设计未来测试和检查机制时的参考指南。

使用方式

安装与配置

通过 npx 安装 verification-before-completion 技能：

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

安装完成后：

1. 打开 obra/superpowers 仓库中的 skills/verification-before-completion 目录。
2. 先阅读 SKILL.md，了解完整规则及其背后的理由。
3. 将这套规则整合进自己的项目文档、agent 配置或开发规范中。

你不必完全照搬该仓库的目录结构。更推荐的做法是，把它作为参考，借鉴如何在你的环境中描述并落实这条规则。

核心工作流：Gate Function

该技能定义了一个必须在任何「完成」声明之前执行的 Gate Function。在日常工作中，可以这样应用：

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

跳过任意一步，都意味着你已经不再遵循 verification-before-completion。

常见命令示例：

• Tests：npm test、pytest、go test ./...、mvn test
• Lint：eslint .、flake8、golangci-lint run
• Build：npm run build、make、cargo build --release
• 针对 Bug 的验证：重现原始问题的特定脚本、测试或手动检查

示例：在开发工作流中使用该技能

场景： 你更新了代码，希望宣称「All tests pass」。

应用 verification-before-completion：

1. IDENTIFY 所需命令：例如 pytest。
2. 在修改后 RUN 该命令：

   pytest
   

3. READ 输出，并确认退出码为 0。
4. VERIFY：
   • 如果测试失败，不要宣称成功。相反，应像这样汇报：「Tests are failing: 3 tests failing in test_user_flow.py. See pytest output.」
   • 如果测试通过，你可以这样说明：「All tests pass (pytest, exit code 0).」
5. ONLY THEN 将任务标记为完成、推送提交或打开 pull request。

同样的模式可以应用于任何状态声明：构建、lint、格式化或 Bug 修复等。

与 agents 和自动化集成

如果你使用 agents 或脚本来辅助开发：

• 配置它们，使任何关于 tests、builds 或 fixes 的声明之前，都必须有一次具体命令的执行和输出摘要。
• 要求 agent 说明它执行的命令及结果，例如：
  • "Ran npm test: exit code 0, 0 failing tests."
  • "Ran npm run build: exit code 1, build failed. Not claiming completion."

在代码评审或 CI 流程中，你可以将任何没有证据支撑的声明视为未完成，不符合 verification-before-completion 的要求。

适配你的工具和环境

该仓库并不限定语言或框架。要将该技能应用到你的环境：

• 为每类常见声明映射一个单一且明确的命令，用于验证它
• 在自己的仓库中记录这些映射（例如写入 CONTRIBUTING.md 或 WORKFLOW.md）
• 鼓励或要求贡献者与 agents 始终：
  • 在说「done」之前先运行相应命令
  • 在给出结论时粘贴或概括相关输出

声明与命令映射示例：

• 「Backend tests pass」 → 在后端测试目录执行 pytest backend/tests
• 「Frontend builds successfully」 → 在 frontend/ 中执行 npm run build
• 「Go module is clean」 → 执行 go test ./... 和 golangci-lint run

常见问题（FAQ）

verification-before-completion 的核心规则是什么？

核心规则就是这条「Iron Law」：

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

如果你没有刚刚运行相关验证命令并检查其输出，就不能诚实地宣称成功。

什么算作「验证证据」？

验证证据是最新的输出结果，来自直接测试你所宣称内容的命令，例如：

• 显示 0 个失败且退出码为 0 的测试集运行结果
• 报告无错误且以成功状态退出的 linter 运行结果
• 成功完成（exit 0）的构建命令
• 针对 Bug 的重现脚本或测试，如今已能通过

在该技能下，旧结果、主观假设或「按理说应该没问题」都不算证据。

如果代码没变，我可以依赖之前的测试结果吗？

在 verification-before-completion 中，默认答案是 不可以。该技能强调，每一次新的「完成」声明之前都应该进行一次最新的验证。如果你想依赖之前的测试结果，就应该明确并谨慎地说明在什么条件下这样是可接受的，同时要意识到这会削弱原本的保证力度。

这个技能是否依赖特定工具或语言？

不依赖。verification-before-completion 是工具无关（tool-agnostic）的。只要你的技术栈可以：

• 定义用于验证行为的命令（tests、linters、builds、scripts）
• 按需运行这些命令
• 解读它们的退出码和输出

你只需填入自己项目中实际使用的命令，并遵循 Gate Function 的步骤即可。

这和「有时跑一下测试」有什么区别？

区别在于纪律性和一致性：

• 你会在每一次宣称完成之前，运行验证命令
• 你总是阅读输出，而不是想当然地认为成功
• 你会把任何没有证据支撑的声明视为无效

这会把测试与构建运行变成一个正式的闸门，而不是可选项。

verification-before-completion 适用于手动测试吗？

可以，只要你能定义一个清晰的流程，使其在逻辑上可以视作针对某个声明的「命令」。例如：

• 记录一套能重现 Bug 的手动测试步骤
• 在修改后再次执行这些步骤
• 记录执行结果，作为证据

不过，该技能在验证过程可通过脚本或测试框架自动化时效果最佳，因为这样结果更可重复，也更方便多次执行。

哪里可以看到该技能的原始定义？

verification-before-completion 技能的权威描述位于 obra/superpowers 仓库的 SKILL.md 文件中：

• Repository: https://github.com/obra/superpowers
• Skill file: skills/verification-before-completion/SKILL.md

如需查看原则的原文描述、Iron Law、Gate Function 以及常见错误示例，请参考该文件。