proof-of-work

“看起来正确”不等于“我已验证它能正常工作。” 工作实证是一种弥合这一差距的准则： 在宣称任务完成之前，先提供可复现的证据。

工作实证

不适用场景

• 实现前的规划（使用 imbue:karpathy-principles）
• 判断工作是否属于范围之内（使用 imbue:scope-guard）

概述

“工作实证”方法要求在宣称任务完成之前进行技术验证，以防止过早宣称完成。例如，不要假定 LSP 配置在重启后能正常工作，而应验证服务是否启动、工具是否能响应查询。这种方法能在用户尝试验证之前，确认解决方案确实有效。

宣称完成之前，必须提供解决方案性能的可复现证据，并处理边缘情况。所有声明都必须有当前环境中实际捕获的命令输出作为依据。

铁律

未先编写失败测试，不得进行任何实现 未先提供证据，不得宣称完成 未先理解，不得编写代码

铁律可防止测试流于形式。如果在编写测试之前就规划好实现，RED 阶段便无法推动设计。在宣称完成之前，先理解所采用方案的技术原理及其局限性。编写代码之前，记录所解决问题的失败证据，并确认测试正在驱动实现。

验证与 TDD 工作流

验证实现的基本原理，以及选择该方案而非其他方案的原因。指出解决方案可能失效的情形，而不是声称它总能奏效。TDD 循环必须遵循以下步骤：

1. RED：在实现之前编写一个失败测试。
2. GREEN：创建通过该测试的最简实现。
3. REFACTOR：在不改变行为的前提下改进代码。

铁律自检

自检问题	回答错误时	行动
我是否有记录在案的失败／需求证据？	否	停止，先记录失败
我是否在测试预先设想的实现？	是	停止，让测试驱动设计
我是否对设计感到不确定？	否	停止——不确定是好事
测试是否驱动了实现？	否	停止——顺序颠倒了

铁律进度跟踪

• proof:iron-law-red：在实现之前编写失败测试。
• proof:iron-law-green：最简实现通过测试。
• proof:iron-law-refactor：改进代码，且不改变行为。
• proof:iron-law-coverage：通过覆盖率门槛（行、分支和变异）。

确认工作通过所有行、分支和变异覆盖率门槛。有关强制执行模式的详细信息，请参阅 iron-law-enforcement.md。

使用标准

在宣称工作“已完成”“已结束”或“已就绪”之前，应用此技能。在推荐解决方案或声称某项配置“应该能用”之前，也应使用此技能。如果发现自己未经测试就假定配置正确，或尚未复现问题就推荐修复方案，请停止。警示信号包括：未经实际验证就认为“这看起来正确”。如果你无法解释配置的每一行，或无法说明某项实践为何适用于当前情境，就说明必要的验证步骤尚未完成。

Agent 的报告是声明，不是证据

无论工作在哪里进行，这一点都成立；在 Workflow 脚本中尤为重要，因为脚本没有文件系统，也没有 shell。它所知的一切都来自 Agent 的告知。某个阶段返回“测试通过”，与某次会话说“应该能用”属于同一类陈述，分量也一样——毫无分量。

因此，工作流可以查找、排序、整理并提出建议。生成证据的运行必须发生在其输出可以被粘贴出来的地方。工作流的返回值可以作为门禁的输入，但它本身不是证据。

验证协议

步骤 1：复现问题（proof:problem-reproduced）

提出解决方案之前，先验证当前状态。使用 ps、echo 和 cat 等工具检查正在运行的进程、环境变量和配置文件。记录命令 输出和错误日志，说明故障情况。

步骤 2：测试解决方案（proof:solution-tested）

声称解决方案有效之前，先在当前环境中执行该方案。捕获实际输出， 并确认其符合预期行为。不要依赖假定的输出。

步骤 3：检查已知问题（proof:edge-cases-checked）

研究与该方法相关的已知缺陷和限制。检查 GitHub 问题、版本兼容性 和官方文档，找出潜在阻碍或常见陷阱。

步骤 4：收集证据（proof:evidence-captured）

使用 imbue:proof-of-work 记录执行的命令、命令输出、时间戳，以及 每个步骤得出的结论。

步骤 5：证明已完成（proof:completion-proven）

定义验收标准并逐项验证。如果发现阻碍，应记录有证据支持的诊断结果， 并提供可行的解决方法，而不是声称已完成。

集成

与改进工作流协作

使用 proof-of-work 验证通过 /update-plugins 或 /fix-workflow 发现的改进机会。记录基线指标（步骤数、失败率、耗时），测试拟议 的更改，并记录改进后的指标，以展示量化效果。

验证清单（声称“完成”之前）

确认已通过证据复现问题，并在实际环境中测试了解决方案。研究已知 问题并考虑边缘情况。以可复现的格式收集证据，并确认满足所有验收 标准。完成声明必须详细说明运行的具体测试及其结果，并为每项主张 引用证据。

危险信号自查

发送完成消息之前，确认已运行建议的命令并捕获其输出。确认已研究 已知问题，并且用户可以复现验证步骤。确保你是在证明，而不是在 假设。

支持模块

• TodoWrite 命名模式：imbue TodoWrite 项目的命名惯例和安全删除规则
• 证据记录：结构化证据收集、审计跟踪和 可复现模式
• 独立验证：对于高风险更改， 说明为什么产出结果的 Agent 不应是唯一的验证者，以及什么才算独立检查
• 验证器完整性：检查本身是否真实有效： 单独验证规范，证明行为出错时检查会失败（变异／还原），优先采用可执行 检查和基于属性的检查，而不是由 LLM 评判

相关技能

• imbue:karpathy-principles：“目标驱动执行”原则将铁律融入四项原则 综合，可用作预检关卡
• 完整的关卡与技能联邦图，请参阅 docs/quality-gates.md#skill-level-quality-gate-composition

退出标准

• 每项实现更改都有对应的 TodoWrite 项目 （proof:iron-law-red、proof:iron-law-green），确认采用先测试后执行的流程。
• 回复中至少包含一个 [E1]／[E2] 证据引用，并由真实的命令调用及其输出支持。
• 明确列出所有验收标准，并通过实际运行而非检查来逐项验证。
• 记录任何阻碍的确切失败输出，以及解除阻碍的下一项具体操作。
• 最终回复不得在没有支持证据的情况下声称“应该有效”、“看起来正确”或“将会有效”。