开源 Coding Agent 如何通过工程工作流约束代码质量？
开源 Coding Agent 约束代码质量，不能只在任务末尾补一次测试，而应把需求澄清、设计批准、实施计划、测试驱动开发、任务审查和完成前验证串成强制工作流。Superpowers 的做法是用可组合 Skill 改变 Agent 的执行顺序，让它在写代码前先形成可审查的意图，在每个小任务后取得反馈。
把质量门禁放在写代码之前
很多 Agent 失败不是因为模型不会写语法，而是未经确认就假设需求、跨越设计决策并一次修改过多文件。Superpowers 首先触发 brainstorming，也就是需求与设计澄清流程：根据任务规模探索现有项目，提出关键问题，展示设计并等待批准。
这一步的产物应包含目标、范围、约束、受影响模块、失败行为和验收标准。批准的是可执行设计，不是模糊方向。若实现中发现新的架构影响，应回到设计门禁，而不是让 Agent 靠已有授权继续扩大修改范围。
把设计拆成可验证的小任务
设计批准后，writing-plans 将工作拆成独立任务，并为每项列出具体文件、接口、测试和验证命令。计划的颗粒度应让审查者可以单独接受或拒绝一项，而不是把脚手架、核心逻辑、迁移和文档混在一个无法定位失败的大步骤中。
| 阶段 | 必须产生的证据 | 不满足时的动作 |
|---|---|---|
| 需求与设计 | 边界、方案和用户批准 | 停止实现并补齐决策 |
| 任务计划 | 文件、接口、测试和验收命令 | 继续拆分模糊任务 |
| 编码 | 先失败后通过的行为测试 | 不得把实现结果当作正确 |
| 任务审查 | 需求符合性与代码质量结论 | 修复重要问题后重审 |
| 完成验证 | 新鲜、完整的命令输出 | 保持未完成状态 |
用红绿重构约束实现顺序
测试驱动开发（Test-Driven Development，TDD）要求先写一个描述真实行为的最小测试，运行并确认它以预期原因失败，再实现使其通过的最小代码，最后在保持测试通过的前提下重构。关键证据不是“存在测试文件”，而是确实观察到了红灯与绿灯。
RED：写行为测试并确认失败原因正确
GREEN：只实现让当前测试通过的代码
REFACTOR：清理结构，再运行完整相关测试测试应优先调用真实代码，名称明确表达行为。只有外部网络、时间或不可控系统无法稳定复现时才使用替身。若测试一开始就通过，应检查它是否覆盖旧行为、断言是否过弱，或实现是否已经存在，不能直接把绿灯视为新功能验证。
让子 Agent 任务自带审查闭环
较大的计划可以由不同子 Agent 逐项执行，但每项都要有清晰输入、输出和工具范围。实现者完成后先自检，再由独立审查流程分别检查是否符合规格以及代码质量是否达标；发现重要问题后回到实现者修复，并对修改范围重新审查。
这种流程的价值不是增加角色数量，而是避免同一个上下文同时承担实现和自我确认。父 Agent 仍负责最终整合，不能让子 Agent 绕过写入权限、测试门禁或分支边界。强耦合任务也不应为了并行而强行拆开。
完成声明必须绑定新鲜证据
verification-before-completion 要求在声称完成之前，先识别能够证明结论的命令，运行完整命令，读取退出状态和失败数量，再决定是否可以报告成功。之前运行过、局部测试通过或实现者声称完成，都不能代替当前证据。
验证范围要匹配声明范围。修复一个函数可以运行精确回归测试，但声称整个包可发布还需要完整测试、静态检查和构建。命令失败时应报告真实状态与输出摘要，不使用“应该已经修好”掩盖未验证结果。
在工作流中保留人工决策点
工程工作流不是让 Agent 无限自治。需求取舍、架构方案、破坏性操作、敏感数据和外部发布仍应由人确认。自动化适合执行已经批准的计划、运行测试、生成差异和组织审查证据，而不应替用户决定业务范围或接受风险。
门禁也要与任务规模匹配。小修改可以使用简短设计与单个测试循环，架构变更则需要书面规格和分阶段批准。无论规模大小，开始实现前的意图确认与完成前的证据检查不能省略。
为自己的 Agent 落地最小版本
- 新增一个设计状态，未批准时禁止进入文件写入工具。
- 让每个计划任务声明修改文件、行为测试和完成命令。
- 在工具层记录测试的红灯与绿灯结果，而不是只保存最终输出。
- 每个任务完成后执行规格审查和质量审查，重要问题必须回流。
- 完成消息只能引用本轮刚运行的验证结果。
上线前用三个场景检验流程：需求含糊时 Agent 是否停止提问，已有错误实现时测试能否先失败，以及验证命令失败时 Agent 是否拒绝宣布完成。工作流真正有效的标志不是步骤数量，而是错误能够在更早阶段被发现，并留下可复核的证据。
防止流程本身变成负担
严格流程也可能带来过度文档、重复审查和上下文膨胀。应按任务风险调整设计篇幅与审查深度，复用稳定模板，并把长日志保存为产物，只向 Agent 返回结果摘要。对同类任务持续记录返工原因，再删除没有拦截任何真实问题的门禁。
最可靠的质量约束仍是清晰意图、短反馈循环和可验证证据。Superpowers 提供的是这些原则的可组合执行框架；将其用于自己的开源 Coding Agent 时，应保留门禁语义，并根据项目工具链替换具体命令，而不是机械复制所有仪式。
