最近在读 Superpowers 里的一个 skill：subagent-driven-development。
这个 skill 很有意思。它并不是教 agent 如何写某一种代码，而是在设计一种开发流程（开发+review）：当我们已经有一个实现计划，并且计划里的任务相对独立时，主 agent 不再亲自完成所有工作，而是把每个任务派发给新的 subAgent，再通过两阶段 review 来控制质量。
它的核心思想可以用一句话概括：
Fresh subagent per task + two-stage review = 可控、高质量、低上下文污染的开发流程。
也就是说，它真正关注的不是「让更多 agent 干活」，而是「如何让多个 agent 在明确边界内协作」。
1. 它解决的不是编码问题，而是协作控制问题
在 SKILL.md 里，开头就定义了这个 skill 的执行方式：
1 | Execute plan by dispatching fresh subagent per task, |
这里有三个关键词：
fresh subagent per taskspec compliance reviewcode quality review
它解决的是 agent 开发里的几个典型问题：
第一，长上下文污染。一个 agent 在同一个会话里持续做很多任务，很容易把前一个任务的判断、假设、实现细节带到后一个任务里。
第二，自己实现、自己检查容易产生确认偏误。implementer 往往会相信自己的实现，报告“已完成”，但实际可能漏需求、多做功能，或者误解了规格。
第三，大任务执行中容易失控。如果没有明确的阶段和状态，主 agent 很难判断什么时候该继续、什么时候该回滚、什么时候该问人。
所以这个 skill 的设计目标不是提升单个 agent 的能力，而是通过流程设计降低 agent 的不可靠性。
2. 整体架构：主 Agent 是 Controller，子 Agent 是角色执行器
这个 skill 的架构可以理解成四个角色：
1 | Controller |
主 agent，也就是 Controller，不直接承担所有实现细节。它负责：
- 读取 plan
- 拆出任务
- 为每个任务准备完整上下文
- 派发 implementer
- 处理 implementer 返回状态
- 派发 reviewer
- 根据 review 结果决定是否返工
- 标记任务完成并进入下一项
源码中的流程图在 SKILL.md 开始，核心流程可以简化成：
flowchart TD
A["Controller 读取计划并拆任务"] --> B["派发 Implementer"]
B --> C{"Implementer 状态"}
C -->|DONE| D["Spec Reviewer 检查规格符合性"]
C -->|NEEDS_CONTEXT| A
C -->|BLOCKED| A
D -->|不通过| B
D -->|通过| E["Code Quality Reviewer 检查代码质量"]
E -->|不通过| B
E -->|通过| F["Controller 标记任务完成"]
F --> G{"还有任务?"}
G -->|有| B
G -->|无| H["最终整体 review"]
这个结构很像一条轻量级 CI 流水线。区别在于，每个阶段不是传统脚本，而是一个有明确职责的 subAgent。
3. 第一个关键设计：每个任务使用新的 subAgent
SKILL.md 明确强调：
1 | They should never inherit your session's context or history — |
这是整个设计里非常关键的一点。
很多人设计多 Agent 系统时，会直觉地让所有 agent 共享尽可能多的上下文。但这个 skill 反过来：子 agent 不继承主会话历史，而是由 Controller 精确构造输入。
这样做的好处是：
- 子 agent 不会被之前任务污染。
- 每个任务边界更清楚。
- reviewer 不会被 implementer 的叙述牵着走。
- 主 agent 可以保留全局协调视角，不被实现细节淹没。
这其实是一种“上下文最小充分原则”：不是给越多越好，而是给刚好完成任务所需的信息。
在 implementer-prompt.md 里，implementer 的输入结构也体现了这一点：
1 | ## Task Description |
注意这里特别说：不要让 subAgent 自己读 plan 文件，而是把任务全文粘进去。
这说明 Controller 要承担“上下文整理者”的职责。subAgent 拿到的是已经被裁剪和组织过的任务包，而不是自己去仓库里乱探索。
4. 第二个关键设计：角色职责非常窄
这个 skill 不是简单地复制多个“全能 agent”，而是把角色拆得很细。
Implementer：只负责实现一个任务
在 implementer-prompt.md 中，implementer 的职责是：
1 | 1. Implement exactly what the task specifies |
它的职责边界非常明确：实现、测试、验证、提交、自查、汇报。
并且 prompt 里反复强调不要猜。如果遇到不清楚的地方，要提问；如果任务超出能力，要停下来报告。
这让 implementer 不再是“尽量完成一切”的 agent，而是一个有明确退出条件的 worker。
Spec Reviewer：只检查是否符合需求
spec-reviewer-prompt.md 定义了它的目的：
1 | Verify implementer built what was requested |
它不主要关心代码优雅不优雅，而是检查三类问题：
- 是否漏做需求
- 是否多做了没要求的东西
- 是否误解了需求
这一步非常重要。因为在真实开发里，“做错方向但代码写得不错”是很常见的失败模式。
Code Quality Reviewer：只检查实现质量
code-quality-reviewer-prompt.md 定义了它的目的：
1 | Verify implementation is well-built |
并且它有一个前置条件：
1 | Only dispatch after spec compliance review passes. |
也就是说，只有确认“做对了”，才进入“做得好不好”的判断。
这体现了一个很重要的编排原则：先验证方向，再优化质量。
5. 第三个关键设计：状态协议让协作可控
Implementer 不是随便返回一段自然语言，而是必须返回结构化状态。状态定义在 SKILL.md：
1 | DONE |
这四个状态就是 Controller 和 Implementer 之间的控制接口。
它们分别表示：
DONE：任务完成，可以进入 spec review。DONE_WITH_CONCERNS：任务完成，但实现者有疑虑，Controller 需要先读 concerns。NEEDS_CONTEXT：缺少上下文，需要 Controller 补充信息后重新派发。BLOCKED：任务无法完成，需要 Controller 判断是拆任务、升级模型、补上下文，还是找人处理。
这让多 Agent 协作从“聊天式协作”变成了“状态机式协作”。
尤其值得注意的是 SKILL.md 的这条规则：
1 | Never ignore an escalation or force the same model to retry without changes. |
这句话很关键。它承认 subAgent 会失败，并且把失败设计进流程里。失败不是异常情况，而是协议的一部分。
6. 第四个关键设计：Reviewer 不信任 Implementer
我认为 spec-reviewer-prompt.md 是整个 skill 里最有学习价值的一段。
它直接告诉 reviewer：
1 | Do Not Trust the Report |
并继续要求：
- 不要相信 implementer 对完整性的声明
- 不要接受 implementer 对需求的解释
- 必须读实际代码
- 必须逐条对照需求
- 必须找 missing、extra 和 misunderstanding
这背后的原则非常适合迁移到其他多 Agent 系统：
前一个 agent 的输出不是事实，而是 claim。Reviewer 的职责不是复述 claim，而是验证 artifact。
如果 reviewer 只是看 implementer 的报告，那么多 Agent 协作只是“多个 agent 相互背书”。但这里 reviewer 必须独立读代码，所以它承担的是验证者角色。
这也是为什么这个 skill 能降低幻觉和乐观报告的问题。
7. 第五个关键设计：两阶段 Review Gate
这个 skill 的 review 不是建议，而是强约束。
在流程中：
1 | Implementer 完成 |
这个顺序也很重要：
1 | Spec Review -> Code Quality Review |
不能反过来。因为如果需求没满足，代码质量再好也没有意义。先过 spec，才能进入 quality。
Red Flags 里也明确禁止跳过这些步骤，比如 SKILL.md：
1 | Skip review loops |
以及
1 | Start code quality review before spec compliance is ✅(wrong order) |
这说明 review loop 是强约束，不是可选优化。
8. 它为什么不并行派多个 Implementer
有趣的是，虽然这个 skill 叫 subagent-driven-development，但它并不鼓励多个 implementer 并行写代码。
Red Flags 中明确禁止：
1 | Dispatch multiple implementation subagents in parallel |
原因很现实：
- 多个 implementer 同时改代码容易冲突。
- commit 边界会变乱。
- review 很难判断问题来自哪个任务。
- 后一个任务可能依赖前一个任务的结果。
所以它采用的是：串行推进任务，每个任务内部使用多角色审查
它追求的不是最大并发，而是最大可控性。
这是一个很重要的启发：多 Agent 不等于并行。很多时候，多 Agent 的价值在于角色隔离和独立验证，而不是同时开工。
9. 实现方式：不是重框架，而是 Prompt Template 编排
从源码结构看，这个 skill 的实现非常轻量：
1 | SKILL.md |
SKILL.md 中把三个 prompt template 明确列出来：
1 | ./implementer-prompt.md |
也就是说，它不是通过复杂的 multi-agent 框架实现的，而是通过：
- 主流程说明
- 角色 prompt
- 状态协议
- review gate
- 红线约束
来实现轻量编排。
可以把它总结成：
1 | Prompt Template + Controller Discipline + Review Gate |
这也是它很值得学习的地方。它没有依赖复杂基础设施，而是把协作规则写进 skill 本身。
10. 对我们写类似 skills 的启发
如果之后要设计类似的多 Agent skill，我觉得可以复用这几个原则。
第一，先设计 Controller，而不是先设计 Worker。
很多人写 skill 时会先想“子 agent 要做什么”。但这个 skill 先定义的是主控流程：什么时候派发、怎么处理返回、什么时候复查、什么时候进入下一任务。
第二，子 Agent 的角色要窄。
Implementer 只实现，Spec Reviewer 只查规格，Code Reviewer 只查质量。角色越窄，prompt 越稳定。
第三，上下文要由 Controller 裁剪。
不要让子 agent 自己读完整计划或探索整个代码库。Controller 应该提供完整任务文本和必要背景。
第四，返回格式要结构化。
DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED 这种状态协议，让主 agent 可以稳定决策，而不是在一大段自然语言里猜。
第五，review 要验证真实产物。
Reviewer 不能相信前一个 agent 的总结。它必须看代码、看 diff、看测试结果，对照需求检查。
第六，失败路径要被明确设计。
好的流程不只定义成功路径，还要定义 subAgent 卡住、缺上下文、有疑虑、发现问题时该怎么办。
第七，不要为了多 Agent 而并行。
在代码修改任务里，可控性往往比并发更重要。这个 skill 的价值不是“同时做很多事”，而是“每一步都有独立角色验证”。
结语
subagent-driven-development 展示的是一种非常务实的多 Agent 编排方式。
它没有复杂框架，也没有让一群 agent 自由讨论，而是把开发过程拆成明确角色：Controller 负责调度，Implementer 负责实现，Spec Reviewer 负责验收需求，Code Quality Reviewer 负责检查质量。
它最大的启发是：
多 Agent 系统的关键不是让更多 agent 参与，而是让每个 agent 在正确的边界内，只做自己该做的事，并让后续 agent 能独立验证它的产物。
从这个角度看，subAgent 编排的核心不是「智能叠加」，而是「责任隔离、状态协议和质量门控」。
这也是我们后续编写类似 skills 时最值得借鉴的地方。