AI 编码代理防坑指南：先澄清意图再动手

AI 编程代理最容易制造昂贵工作的方式，就是太快开始写代码。请求一来，代理就推断出缺失的需求、选择架构、修改多个文件，然后生成一个看似合理的补丁。这个补丁可能能编译通过，甚至可能通过一个狭义的测试。但它仍然可能解决的是错误的问题。

Superpowers 是一套方法论和可组合的技能集合，旨在改变这种默认行为。它不会把代码生成当作第一步，而是要求代理先明确预期结果，制定并获得批准的设计方案，拟定实施计划，使用真正的红/绿测试驱动开发，以小任务的方式执行工作，并审查所构建的内容。

这不是为了走流程而走流程。这是针对 AI 代理非常擅长用看似合理的假设来填补空白这一事实而提出的应对方案。

核心思想：生成之前设置关卡

Superpowers 描述了一个编程代理的工作流程，当代理意识到自己在构建某些东西时就开始启动。它不会直接跳入实现，而是退后一步，询问用户真正想要完成什么。然后它制定规范，以可读的块状形式展示设计，并在生成详细计划之前等待确认。

只有在获得批准后，工作流程才会进入实现阶段。该仓库强调红/绿 TDD、YAGNI（只构建所需）、DRY（避免无谓重复）。它还描述了子代理驱动的开发方式，用于执行和审查任务。

每个关卡的设立都是因为某种特定的失败在早期发现成本更低：

澄清环节捕获误解的结果。

澄清环节捕获误解的结果。

设计审查捕获错误的结构和缺失的约束。

设计审查捕获错误的结构和缺失的约束。

计划捕获隐藏的依赖关系和排序错误。

计划捕获隐藏的依赖关系和排序错误。

测试捕获行为回归。

测试捕获行为回归。

审查捕获预期变更与实际 diff 之间的不匹配。

审查捕获预期变更与实际 diff 之间的不匹配。

为什么模糊的请求是危险的

考虑这个请求："添加团队邀请。"这听起来可以执行，但它留下了大量尚未回答的产品和系统决策。邀请是基于邮箱的吗？邀请会过期吗？可以撤销吗？被邀请的人会获得什么角色？如果他们已经有账户会发生什么？如果他们属于另一个组织呢？该操作是否可审计？管理员可以重新发送邀请吗？哪些失败状态应对用户可见？

一个立即创建邀请表的编程代理已经做了决策。结构化的工作流程使这些决策在变得昂贵且难以回滚的数据库迁移、端点和 UI 状态之前变得可见。

第一阶段：明确结果

良好的澄清聚焦于可观察的成功、约束和非目标。询问用户故事、受影响的角色、必须保持稳定的现有行为，以及将表明任务完成的验收检查。

对于邀请示例，一个有用的结果描述可能是："组织所有者可以邀请一个邮箱地址加入工作空间。邀请在七天后过期，可以被撤销，在接受时授予选定的角色，并且不得向未认证用户暴露工作空间的存在。"这比"添加邀请"有用得多，因为它为设计和测试提供了目标。

第二阶段：达成设计共识

Superpowers README 描述了以足够小的块状形式展示设计材料，以便人类可以阅读和批准。这是一个代理协作的实用设计原则。一堵巨大的架构文本墙很难审查；而一系列聚焦的决策更容易挑战。

设计应覆盖最可能产生不可逆工作的部分：

领域实体和所有权边界

领域实体和所有权边界

API 契约和错误行为

API 契约和错误行为

状态转换和生命周期规则

状态转换和生命周期规则

数据迁移和向后兼容性

数据迁移和向后兼容性

可观察性和操作失败模式

可观察性和操作失败模式

批准不是一种仪式。它是一个人表示"是的，这就是我们想要拥有的产品行为"的时刻。

第三阶段：编写可执行的计划

在设计获得批准后，计划应将工作分解为小的、有序的任务。每个任务应识别相关的文件或组件、变更和验证方法。计划应足够具体，以便另一个称职的开发者或另一个代理可以执行它，而无需重新解释原始请求。

例如，邀请功能可以细分为：定义领域规则和测试；添加持久化和迁移；添加服务层授权；暴露 API 路由；实现邮件发送抽象；添加 UI 状态；添加集成测试；记录发布和监控。确切的顺序取决于代码库，但原则是稳定的：以可垂直验证的增量方式构建。

与代理一起做真正的红/绿 TDD

Superpowers 强调真正的红/绿 TDD。重要的区别是时间上的：测试应在实现被接受之前表达预期行为。在代码之后编写测试仍然可能有用，但它通常记录的是实现恰好做了什么，而不是系统应该做什么。

对于邀请流程，红色测试可能断言被撤销的邀请不能被接受、过期的邀请产生特定错误、或者非所有者不能创建邀请。然后实现将测试变为绿色。这使得行为以比对话声明更持久的形式可供审查。

TDD 不能保证正确的产品决策。它保证选定的行为被检查。这就是为什么澄清和设计必须先于它。

该方法论描述了子代理驱动的开发：代理可以处理特定任务、检查工作和审查结果。并行性只在任务边界真实时才有用了。独立的代理可以调查独立的模块或审查已完成的变更，但两个代理在未经协调的情况下编辑同一个设计决策只会增加混乱。

使用子代理创建独立证据：一个调查现有约定、一个起草测试、一个根据批准的设计审查 diff。保持决策的单一真实来源，并要求最终审查者将该结果与该来源进行比较。

何时使用 Superpowers

这种方法对于新功能、多文件重构、原因不明确的回归、公共 API 变更，以及错误假设会产生真正返工的任务很有价值。对于修改一个拼写错误、重命名一个局部变量或做一个明显在范围内的配置编辑，它故意不是最快的方法。

问题不是"这个任务大吗？"而是问："如果代理选择了错误的解释，它的代价是什么？"如果答案很高，结构化就会物有所值。

采用工作流程但不要过度

从一个中等风险的功能开始。

从一个中等风险的功能开始。

要求书面陈述成功标准和非目标。

要求书面陈述成功标准和非目标。

在代码变更开始之前审查设计。

在代码变更开始之前审查设计。

要求任务计划，每个行为切片附带测试。

要求任务计划，每个行为切片附带测试。

根据批准的设计而不是仅根据测试审查最终的 diff。

根据批准的设计而不是仅根据测试审查最终的 diff。

记录什么导致了返工，并调整工作流程。

记录什么导致了返工，并调整工作流程。

团队不应根据代理计划的听起来有多完善来评判这个方法。而应根据具体结果来评判它：后期需求变更更少、diff 更清晰、测试更可靠、审查期间更少的重新发现。

Superpowers 不能替代什么

没有任何代理工作流程可以替代产品所有权、安全审查或对生产变更的责任。一个结构良好的计划仍然可能优化错误的指标。一套绿色的测试套件仍然可能遗漏真实的边缘案例。将该框架视为一种使决策和证据可见的方式，而不是正确性的保证。

Superpowers 的有用之处在于，它给予了一个热切的编程代理暂停的许可。它将模糊的请求转化为一致的设计、一个计划、经过测试的行为和可审查的变更。对于有意义的工程工作来说，这种暂停往往是整个过程中最快的部分。

obra/superpowers README