执行与 Subagent
每项任务在全新的上下文中运行。无污染。无假设。无继承的混乱。
为什么要使用全新的 Subagent？
当一个 AI agent 处理一项长任务时，它会积累上下文——先前的决策、早期的错误、以及一小时前执行某些步骤时形成的半成品假设。当它执行到计划中的第 15 项任务时，它可能已经（隐约或显著地）受到第 1 到第 14 项任务中所有内容的影响。
这被称为上下文污染，是 AI 辅助开发中导致级联失败的主要原因之一。任务 3 中的误解会悄无声息地传播。任务 7 中做出的错误假设会影响任务 8、9 和 10 中编写的代码。等到有人发现问题时，理清头绪的代价已经很高了。
Superpowers 通过 subagent 来解决这个问题：没有先前任务记忆的全新 AI 实例。每项任务都被分派给一个干净的上下文。之前发生的事情不存在。subagent 读取任务、读取相关代码，然后严格按照任务说明执行——不多也不少。
上下文隔离的三大优势
-
无错误传播 — 任务 3 中的错误不会影响任务 4。每项任务独立成功或失败。
-
无偏见的审查 — 审查已完成任务的 agent 对它正在审查的代码没有任何依附。它没有写这段代码，所以没有理由为问题辩解。
-
并行执行安全 — 互不依赖的任务可以同时分派。全新的上下文不会产生冲突。
控制器流程
控制器是主要的编排 agent——它负责管理计划执行循环。工作方式如下：
┌──────────────────────────────────────────────────────────────┐
│ CONTROLLER LOOP │
│ │
│ 1. Load plan → identify next PENDING task │
│ 2. Dispatch subagent with: task description + relevant code │
│ 3. Subagent completes task → returns result + status │
│ 4. Controller runs TWO-STAGE REVIEW │
│ 5. Handle status: │
│ DONE → mark task complete, continue │
│ DONE_WITH_CONCERNS → log, continue with note │
│ NEEDS_CONTEXT → gather context, re-dispatch │
│ BLOCKED → stop, escalate to user │
└──────────────────────────────────────────────────────────────┘
加载计划
控制器读取完整的计划文档，并找到第一个状态为 Status: PENDING 的任务。它不会跳过步骤，不会重新排序，也不会为了"提高效率"而决定"合并"任务。计划是合约——控制器负责执行合约。
分派 Subagent
控制器创建 subagent 时，只提供该 subagent 所需的信息：
- 任务描述
- 要编写的确切代码（来自计划）
- 要修改的确切文件
- 要运行的确切命令
没有额外内容。没有先前任务的历史记录（除非该任务明确要求将其作为上下文）。subagent 的工作是干净地执行一项任务。
两阶段审查
在 subagent 完成任务后，控制器不会立即接受结果。它会运行两阶段审查：
阶段 1：规格符合性
"subagent 是否构建了任务规格中指定的内容？"
控制器将 subagent 的输出与任务描述进行比较：
- 是否修改了正确的文件？
- 是否使用正确的签名创建了正确的函数？
- 是否编写了所需的测试？
- 是否进行了任何超出范围的更改？
如果输出与规格不匹配，任务就没有完成。控制器记录偏差，然后带有说明重新分派，或升级给用户。
阶段 2：代码质量
"代码是否正确、可读且可维护？"
这与规格符合性独立评估。subagent 可以完美匹配规格，但仍然产出质量糟糕的代码：
- 对明显情况缺少错误处理
- 碰巧通过了指定测试但逻辑不正确
- 命名规范与代码库不匹配
- 安全问题
代码质量问题与符合性问题分开记录。一项任务可以是 DONE_WITH_CONCERNS——技术上完成但有需要审查者关注的备注。
状态协议
每项完成的任务返回以下四种状态之一：
DONE
任务已完成。代码符合规格。质量可接受。无需关注。继续下一项任务。
DONE_WITH_CONCERNS
任务技术上已完成且测试通过，但审查 agent 标记了一些值得人工关注的内容。示例：
- 实现有效但使用了已废弃的 API
- 测试覆盖率技术上通过但较弱
- 引入了轻微的命名不一致
工作继续进行，但关注点被记录下来，供人工在计划结束时或下一个审查检查点进行审查。
NEEDS_CONTEXT
由于 subagent 遇到了无法用所提供信息解决的问题，任务无法完成。这不是失败——这是对需要更多信息的诚实报告。示例：
- 指定的文件不存在，且任务没有说要创建它
- 导入的模块不在代码库中
- 任务引用的函数签名与现有函数不匹配
控制器收集缺少的上下文并重新分派。
BLOCKED
有根本性的问题阻止了进展。示例：
- 一项依赖任务被标记为 DONE，但它本应创建的代码不存在
- 测试以当前任务无法解释的方式失败
- 计划中的设计假设被证明是错误的
当任务返回 BLOCKED 时，控制器停止执行并升级给用户。这是一个强制机制，防止 AI 对计划层面的问题做出单方面决定。
按复杂度选择模型
并非所有任务都需要相同级别的 AI 能力。Superpowers 建议将任务复杂度与模型层级匹配：
| 任务类型 | 示例 | 推荐模型层级 |
|---|---|---|
| 机械性 | 添加 import、重命名变量、更新配置值 | 较小/较快的模型 |
| 集成性 | 将两个现有系统连接起来、添加新的 API 端点 | 中等模型 |
| 架构性 | 设计新的抽象、重构核心数据模型 | 最强模型 |
对机械性任务使用较小的模型可以降低成本和延迟。对架构性任务使用最强模型可确保重要决策获得最佳推理。任务复杂度通常在计划中描述，也可以从任务描述中推断出来。
并行 Agent 分派
计划中的某些任务是相互独立的——完成任务 4 不依赖于任务 5 的完成。在这些情况下，控制器可以同时分派多个 subagent。
并行分派规则
- 无共享状态 — 并行运行的任务不得写入同一文件或修改同一数据库记录
- 无顺序依赖 — 如果任务 B 和任务 A 并行运行，任务 B 不得需要任务 A 的输出
- 明确声明 — 并行任务应在计划中标记（
[PARALLEL_GROUP: A]），这样控制器就知道它们可以安全地一起运行 - 审查仍然适用 — 每个并行任务在完成时独立经过两阶段审查
### Task 6: Write auth middleware test [PARALLEL_GROUP: 1]
### Task 7: Write order validator test [PARALLEL_GROUP: 1]
### Task 8: Write cart service test [PARALLEL_GROUP: 1]
// Tasks 6, 7, and 8 can be dispatched simultaneously.
// Task 9 must wait for all three to complete.
何时不应并行化
- 当任务修改同一文件时（合并冲突代价高昂）
- 当一项任务的输出改变了另一项任务的环境时
- 当不确定时（不确定时默认顺序执行）
备用方案：在没有 Subagent 的情况下执行计划
某些环境不支持 subagent 分派——AI 工具在单一上下文模式下运行，无法生成独立进程。
在这些情况下，使用 executing-plans 技能（而不是 subagent 分派流程）。executing-plans 技能通过以下方式在单一上下文中模拟 subagent 纪律：
- 将每项任务视为一个清晰的单元，并明确重置上下文
- 在每项任务后应用相同的两阶段审查
- 使用相同的状态协议
- 在执行当前任务时绝不提前查看未来任务
结果比真正的 subagent 稍微少一点隔离，但流程纪律提供了大部分相同的好处。
/executing-plans [path to plan document]
常见执行失败及预防方法
| 失败情况 | 原因 | 预防措施 |
|---|---|---|
| 任务完成但测试不通过 | Subagent 验证了文件存在，而不是测试通过 | 审查关卡必须运行测试，而不仅仅是检查文件是否存在 |
| DONE_WITH_CONCERNS 积累 | 控制器尽管有顾虑仍继续运行 | 设定阈值——如果积累了 N 个顾虑，暂停并审查 |
| BLOCKED 任务被跳过 | 控制器尝试绕过被阻塞的任务 | BLOCKED 始终停止执行——没有变通方法 |
| 并行任务冲突 | 两个任务写入同一文件 | 明确标记并行组；在分派前检查是否有共享状态 |
| 执行期间计划偏离 | Subagent "改进"了计划 | Subagent 必须严格遵循计划，不得解读或改进 |
subagent 模型借鉴自优秀的工程管理实践： 给每位工程师一项清晰、自包含的任务，在其代码合并前审查他们的工作，并且绝不让一位工程师的困惑成为整个团队的问题。