verification-before-completion

概述

完成前验证技能是工具包中每项任务的最终检查点。它强制执行严格的 5 步协议，要求运行最新的验证命令、阅读其完整输出，并确认结果与完成声明相符。没有这项技能，Agent 会做出未经验证的声明，导致代码在生产环境中出问题；有了它，每项完成声明都有证据支撑。

---

铁律

没有最新的验证证据，就不要声明任务已完成。

如果没有在当前会话中运行验证命令并阅读其输出，就不能说“它能正常工作”“已经完成”“Bug 已修复”或“功能已完成”。缓存结果、之前的运行记录和假设都不算数。

---

阶段 1：确定验证命令

开始运行任何命令之前，明确列出此任务需要通过哪些检查：

验证类型	示例命令	何时需要
单元测试	npm test、pytest、go test ./...、cargo test、php artisan test	始终需要
集成测试	npm run test:integration、pytest tests/integration/	适用时
类型检查	tsc --noEmit、mypy .、pyright、phpstan analyse	项目使用类型检查时
代码检查	eslint .、ruff check .、golint ./...、php-cs-fixer fix --dry-run	始终需要
构建	npm run build、cargo build、go build ./...	始终需要
格式检查	prettier --check .、black --check .、gofmt -l .、pint --test	项目使用格式化工具时

**操作：**列出当前项目适用的检查。并非所有项目都包含所有类型的检查。明确说明要运行哪些检查以及原因。

停止：确定所有适用的验证类型之前，不要运行命令。

---

阶段 2：重新运行命令

执行阶段 1 中确定的每一条验证命令。

规则	原因
在最近一次代码修改后运行	修改前的结果已经过时
运行完整测试套件，不要只运行部分测试	只运行部分测试会漏掉回归问题
不要依赖缓存结果	上次运行后代码已发生变化
不要因为“之前通过了”就跳过命令	之前不等于现在
如果命令耗时超过 5 分钟，注明这一点	说明实际运行了什么

停止：所有命令都完成后，才能进入阶段 3。

---

阶段 3：阅读完整输出

阅读每条验证命令的完整输出。重点关注：

输出要素	关注点	重要原因
退出代码	非零表示失败	即使输出看起来正常，非零也表示有失败
测试数量	运行的测试数量是否符合预期？是否有跳过的测试？	跳过的测试意味着代码未经测试
警告消息	是否出现之前没有的新警告	警告可能会变成错误；它们表明质量有所下降
弃用提示	是否使用了已弃用的 API	存在未来出现故障的风险
性能指标	测试是否异常缓慢	可能表明性能出现回归
错误消息	是否出现任何错误，即使测试“通过”也是如此	有些框架会在报告测试通过的同时报告错误

停止：阅读每条命令的完整输出后，才能继续。

---

阶段 4：验证输出是否符合声明

问自己以下问题。所有问题的答案都必须是“是”，才能继续：

问题	如果答案为“否”或“不确定”
所有测试都通过了吗（不只是我编写的测试）？	修复失败的测试后再声称已完成
构建是否成功且没有错误？	修复构建错误
类型检查器是否未发现错误？	修复类型错误
代码检查是否通过？	修复代码检查错误
是否出现了之前没有的新警告？	调查并修复，或明确说明理由
是否运行了完整测试套件（而不只是子集）？	运行完整测试套件
测试数量是否符合预期？	调查被跳过或缺失的测试

停止：如果任何一个答案是“否”或“不确定”，请返回修复，并从阶段 1 重新开始。不要继续到阶段 5。

---

阶段 5：提供证据并声明完成

现在才可以说任务已完成。请提供以下证据：

VERIFICATION EVIDENCE
=====================
Task: [what was being done]
Date: [timestamp]

Commands Run:
  [x] Tests:      [command] -> [result: X passed, Y failed, Z skipped]
  [x] Build:      [command] -> [result: success/failure]
  [x] Lint:       [command] -> [result: X errors, Y warnings]
  [x] Type-check: [command] -> [result: X errors]
  [x] Format:     [command] -> [result: clean/X files to format]

All Green?  [x] YES  [ ] NO
New warnings introduced?  [ ] YES  [x] NO

Completion claim: [specific claim, e.g., "Feature X is implemented and all tests pass"]

停止：验证协议到此结束。只有提供了这些证据的声明才有效。

---

决策表：什么算作“新鲜”的证据

算作新鲜	不算作新鲜
在最近一次代码更改后运行了命令	在最近一次代码更改前运行
执行了完整测试套件	仅执行了部分测试
阅读并分析了输出	粗略浏览或忽略了输出
运行了所有验证类型	只运行了测试（没有代码检查或构建）
在当前会话中运行了命令	凭记忆回想之前某个会话的结果
有实际的命令输出	“我记得它通过了”

---

决策表：特殊情况

情况	协议
完整测试套件耗时超过 5 分钟	运行相关测试和冒烟测试套件。注明未运行完整测试套件。建议合并前运行 CI。
不存在自动化测试	将此视为重大风险。按照有记录的步骤进行手动验证。建议后续补充测试。至少要确认代码可以编译并运行。
测试不稳定	单独重新运行失败的测试。如果单独运行时通过，请注明其不稳定性。确认更改没有引入此问题。不要以测试不稳定为由跳过测试。
仅更改配置	配置更改是导致服务中断的首要原因。必须进行完整验证。
仅更改一行	单行更改也可能导致生产环境中断。必须进行完整验证。
仅进行重构	现有测试仍须通过。运行完整测试套件。

---

常见失败模式

模式	结果	危险之处
测试通过，但代码检查失败	代码可运行，但存在质量问题	代码检查失败通常意味着确实存在问题（未使用的变量、不可达代码）
测试通过，但构建失败	测试环境与构建环境不同	生产部署会失败
测试通过，但类型检查失败	运行时正常，但类型错误	错误可能隐藏在 any 类型或错误接口背后
单独运行测试时通过，但一起运行时失败	测试之间存在共享状态	CI 不稳定，测试套件不可靠
手动测试通过，但自动化测试失败	手动测试遗漏了边界情况	自动化测试的结果是正确的
测试通过，但出现了新警告	某些方面退化了	警告会逐渐变成错误
部分测试通过	只运行了相关测试	其他区域可能存在回归
测试通过，但覆盖率下降	新代码没有经过测试	未测试的代码就未经验证
使用旧测试结果作为证据	结果已过时	自那次测试运行后代码已经更改
“编译通过了，所以能正常工作”	编译是必要条件，但不是充分条件	编译成功的代码仍可能有误

---

反模式 / 常见错误

不要这样做	失败原因	应该怎么做
未运行测试就声称已完成	未经验证的代码会在生产环境中出问题	重新运行所有验证命令
用“之前通过了”作为证据	此后代码已经发生变化	每次更改后都重新运行
因为“只是警告”就跳过 lint	警告表明存在实际问题	修复警告，或明确说明每一条警告的理由
只运行自己编写的测试	会遗漏其他区域的回归问题	运行完整测试套件
只看部分测试输出	输出中可能隐藏着未注意到的失败	阅读输出的每一行
只用手动测试作为证据	手动测试不完整且无法重复	运行自动化验证
验证一次后，又做“很小”的额外更改	这些更改未经验证	每次更改后都重新验证
不加说明就屏蔽警告	会掩盖实际问题	如果确实是误报，添加注释说明屏蔽原因

---

防止自我合理化

借口	事实
“我只改了一行”	一行改动也会导致生产环境中断。请验证。
“测试 5 分钟前通过了”	此后你做了更改。请重新运行。
“我以前测试过这种模式”	这是另一个实例。请验证当前这个实例。
“这个更改显然是正确的”	显而易见的更改更容易出错，因为它们未经验证。
“运行测试太耗时了”	等 Bug 影响生产环境后，不运行测试会花费更多时间。
“我提交后再验证”	你不会这么做。而且如果验证失败，你就得撤销并重做。
“这只是配置更改”	配置更改是导致中断的首要原因。请验证。
“lint 警告是误报”	逐条检查。如果确实是误报，请添加注释并屏蔽。
“类型错误出现在无关代码中”	它们可能会相互影响。请运行完整检查。
“我手动测试过了”	手动测试不完整且无法重复。请运行自动化验证。

没有第 5 阶段的证据，绝对不要声称已完成。没有例外。

---

集成点

技能	何时需要验证
test-driven-development	完成功能的 RED-GREEN-REFACTOR 循环后
systematic-debugging	应用 Bug 修复后
executing-plans	每项任务完成后，以及每批任务完成后
subagent-driven-development	实现者交付后（通过 Agent 工具），审查者批准后
code-review	批准任何代码审查之前
resilient-execution	将任何任务标记为完成之前
autonomous-loop	将 EXIT_SIGNAL 设为 true 之前
finishing-a-development-branch	合并或创建 PR 之前

集成流程

[Do the work using other skills]
    |
    v
[Think you are done?]
    |
    v
[Invoke verification-before-completion]
    |
    +-- All checks pass -> Claim completion with Phase 5 evidence
    |
    +-- Any check fails -> Fix and re-verify (do NOT claim completion)

---

其他技能的强制要求

所有其他技能都会在完成时调用此技能。这不是可选项，而是最终检查点——只在工作结束时调用，绝不在开始时调用。

---

技能类型

严格 — 这套 5 步流程是硬性门槛。必须按顺序执行每一步，不得跳过任何步骤。没有第 5 阶段的证据，任何完成声明都无效。任何情况下都不得放宽这些要求。