Superpowers 实战指南 | 第5期 - 子代理驱动开发：AI 管理 AI 写代码的全新范式

🤖 当你让 AI 连续工作几个小时后，它的上下文已经被各种对话填满，输出质量开始急剧下降。Superpowers 的解决方案令人眼前一亮——让一个主代理调度多个"新鲜"的子代理，每个子代理只负责一个原子任务。

为什么需要"AI 管 AI"？

单一 AI 的上下文退化

第 1 个任务：完成质量 ⭐⭐⭐⭐⭐（上下文清洁，精力充沛）
第 2 个任务：完成质量 ⭐⭐⭐⭐ （开始有些累了）
第 3 个任务：完成质量 ⭐⭐⭐  （上下文混杂，偶尔跑偏）
第 5 个任务：完成质量 ⭐⭐   （严重退化，开始犯低级错误）
第 8 个任务：完成质量 ⭐     （上下文爆炸，逻辑混乱）

这是所有 AI 编程助手的通病：上下文窗口是有限的。随着对话越来越长，AI 的"工作记忆"被之前的代码、讨论、修改来回地填满，它对当前任务的专注力和准确度都会下降。

子代理驱动的解决方案

主代理（协调者）：
  持有全局计划，自己不写代码，只做调度和审查

  任务 1 → 派出子代理 A（全新上下文）→ ⭐⭐⭐⭐⭐
  任务 2 → 派出子代理 B（全新上下文）→ ⭐⭐⭐⭐⭐
  任务 3 → 派出子代理 C（全新上下文）→ ⭐⭐⭐⭐⭐
  任务 8 → 派出子代理 H（全新上下文）→ ⭐⭐⭐⭐⭐

每个子代理都像第一次上班一样精力充沛。 因为它们完全没有前面任务的历史包袱。

完整工作流

子代理驱动开发是 Superpowers 执行链中最复杂也最强大的环节。来看它的完整流程：

┌──────────────────────────────────────────────┐
│ 主代理：读取计划文件，提取所有任务             │
└──────────────────┬───────────────────────────┘
                   ↓

┌──────────────────────────────────────────────┐   ─┐
│ Step 1: 派出"实现子代理"                      │    │
│ → 提供完整的任务描述 + 项目上下文              │    │
│ → 子代理遵循 TDD 实现功能并提交代码            │    │
└──────────────────┬───────────────────────────┘    │
                   ↓                                 │
┌──────────────────────────────────────────────┐    │ 每
│ Step 2: 派出"规格审查子代理"                    │    │ 个
│ → 检查实现是否符合原始设计规格                  │    │ 任
│ → 不符合？→ 实现子代理修改 → 重新审查           │    │ 务
└──────────────────┬───────────────────────────┘    │ 循
                   ↓                                 │ 环
┌──────────────────────────────────────────────┐    │
│ Step 3: 派出"代码质量审查子代理"                │    │
│ → 检查代码质量、可维护性、最佳实践              │    │
│ → 质量不过关？→ 实现子代理修改 → 重新审查       │    │
└──────────────────┬───────────────────────────┘    │
                   ↓                                 │
┌──────────────────────────────────────────────┐    │
│ Step 4: 标记任务完成，进入下一个任务             │    │
└──────────────────────────────────────────────┘   ─┘
                   ↓
           所有任务完成后
                   ↓
┌──────────────────────────────────────────────┐
│ 最终全局代码审查 → finishing-a-development-branch│
└──────────────────────────────────────────────┘

三种角色的子代理

1. 实现子代理（Implementer）

职责：按照任务描述编写代码，遵循 TDD。

特点：

收到完整的任务文本和项目上下文（主代理精心准备）
不需要自己去读计划文件——主代理直接把需要的信息喂给它
完成后自我审查一次，然后报告状态

四种状态报告：

状态	含义	主代理的应对
`DONE`	任务完成	进入规格审查
`DONE_WITH_CONCERNS`	完成但有疑虑	评估疑虑后决定
`NEEDS_CONTEXT`	缺少必要信息	补充信息后重新派发
`BLOCKED`	无法完成	升级处理（换模型/拆分任务/上报人类）

实际对话示例：

主代理 → 子代理 A:
  "你的任务是实现搜索 API 路由。
   文件 src/app/api/search/route.ts （新建）
   数据库已有 search_vector 列和 GIN 索引。
   以下是完整的任务步骤……"

子代理 A 回报:
  "DONE. 已实现搜索 API：
   - 写了 3 个测试用例（空查询/正常搜索/无结果）
   - 所有测试通过
   - 自审查：发现缺少查询参数校验，已补充
   - 已提交代码"

2. 规格审查子代理（Spec Reviewer）

职责：检查实现的代码是否完全符合设计规格。

它会检查：

✅ 所有规格中的需求都有对应实现
❌ 有没有多做了设计中没要求的东西
❌ 有没有遗漏了设计中要求的功能

规格审查子代理的典型反馈：

✅ 通过：
  "代码完全符合规格。搜索 API 支持全文搜索，
   返回格式正确，错误处理完善。"

❌ 不通过：
  "发现以下问题：
   - 缺失：规格要求结果按相关度排序，但实现中按时间排序
   - 多余：实现了分页功能，但规格未要求（YAGNI 违规）"

💡 为什么要查"多做"？ 因为 AI 很喜欢"顺手"加东西。没被要求的功能 = 没被测试的功能 = 潜在的 Bug 源。

3. 代码质量审查子代理（Code Quality Reviewer）

职责：审查代码的实现质量，而不是功能正确性。

它会检查：

代码是否清晰可读
命名是否准确
是否有硬编码的魔法数字
是否有性能隐患
测试是否充分

代码质量审查子代理的典型反馈：

✅ 通过：
  "代码质量优秀。结构清晰，命名准确，测试覆盖充分。"

❌ 不通过（Important 级别）：
  "发现问题：
   - 魔法数字：搜索结果限制 20 条，应提取为常量 MAX_SEARCH_RESULTS
   - 缺少 JSDoc：公开 API 函数缺少文档注释"

智能模型选择

Superpowers 不会对所有子代理使用同一个模型。它根据任务复杂度选择最合适的模型：

任务类型	推荐模型	原因
简单机械实现（1-2 个文件，规格明确）	💨 快速便宜模型	省钱省时间
多文件集成	🔄 标准模型	需要理解多文件间的关系
架构设计、审查	🧠 最强模型	需要最强的判断力

信号判断：

markdown

任务涉及 1-2 个文件 + 规格完整 → 💨 便宜模型就够了
任务涉及多文件联动 → 🔄 标准模型
任务需要设计判断或深度代码审查 → 🧠 最强模型

实战演示：子代理驱动实现搜索功能

假设 writing-plans 已经为搜索功能生成了 5 个任务：

全流程展示

主代理: 开始执行搜索功能实施计划。共 5 个任务。

═══════════════════════════════════════════
Task 1: 数据库迁移（添加 search_vector 列）
═══════════════════════════════════════════

[派出实现子代理 → 💨 快速模型]
子代理 A: DONE.
  - 创建了迁移文件 001_add_search_vector.sql
  - 测试：验证列和索引创建成功 ✅
  - 已提交

[派出规格审查子代理]
规格审查: ✅ 通过 — 迁移完全符合规格

[派出代码审查子代理]
代码审查: ✅ 通过 — SQL 语法正确，索引类型适当

✅ Task 1 完成

═══════════════════════════════════════════
Task 2: 搜索 API 路由
═══════════════════════════════════════════

[派出实现子代理 → 💨 快速模型]
子代理 B: DONE_WITH_CONCERNS.
  - 实现了 /api/search 路由
  - 测试通过 ✅
  - 疑虑：对中文内容搜索效果可能不佳

主代理: 疑虑已记录。规格明确 MVP 先支持英文，继续。

[派出规格审查子代理]
规格审查: ❌ 不通过
  - 缺失：规格要求返回字段包含 publishedAt，但实现只返回了 title 和 url

[实现子代理继续修复]
子代理 B: 已补充 publishedAt 字段。

[规格审查子代理重新审查]
规格审查: ✅ 通过

[代码审查子代理]
代码审查: ❌ 不通过
  - 魔法数字：结果限制硬编码为 20

[实现子代理修复]
子代理 B: 已提取为 MAX_SEARCH_RESULTS 常量。

[代码审查重新审查]
代码审查: ✅ 通过

✅ Task 2 完成

═══════════════════════════════════════════
Task 3-5: ...（类似流程）
═══════════════════════════════════════════

所有 5 个任务完成 ✅

[最终全局代码审查]
全局审查: ✅ 所有需求已满足，代码质量达标

[finishing-a-development-branch]
主代理: 所有任务完成。选项：
  1. 本地合并到 main
  2. 推送并创建 PR
  3. 保持分支
  4. 丢弃

你选择: 2. 创建 PR
→ PR #15 已创建 ✅

与人工的交互点

虽然子代理驱动开发可以长时间自主运行，但有几个关键节点需要人类介入：

场景	主代理行为
子代理报告 `BLOCKED`	停下来，向人类求助
3+ 次修复失败	可能是架构问题，上报人类
计划有关键遗漏	暂停执行，与人类讨论
所有任务完成	4 选项让人类决定如何收尾

💡 关键原则：AI 可以自主执行几个小时，但遇到无法独立解决的问题时必须停下来问人，而不是硬猜着继续。

与 GStack 执行方式的对比

维度	GStack 方式	Superpowers 子代理
执行模式	在同一个会话中执行所有代码	每个任务派一个新子代理
上下文管理	越到后面越混乱	每个任务上下文都是干净的
质量保证	最后统一 `/review`	每个任务双重审查（规格 + 质量）
失败处理	人工干预	自动升级模型 / 拆分任务
成本	Token 全在一个会话中	审查子代理增加开销，但早发现问题更省钱
自主时长	需要频繁人工引导	可连续自主运行数小时

小结

▪️ 子代理驱动开发解决了 AI 编程中"上下文退化"的核心痛点 ▪️ 三种子代理分工明确：实现 → 规格审查 → 代码质量审查 ▪️ 每个任务都有全新上下文，确保第 8 个任务与第 1 个一样高质量 ▪️ 智能模型选择在保质量的同时节省成本 ▪️ 主代理只做协调调度，自身上下文保持清洁

在下一篇文章中，我们将进行一次完整的实战演练：用 Superpowers 全流程从零构建一个 Markdown 笔记应用——从头脑风暴到 PR 合并的全过程。

好了，本期的内容到这里就结束了，如果你觉得对你有帮助的话，欢迎点赞、在看、转发，我们下期见！Bye~

📝 作者：NIHoa ｜系列：Superpowers实战指南系列｜更新日期：2025-04-24

Superpowers 实战指南 | 第5期 - 子代理驱动开发：AI 管理 AI 写代码的全新范式 ​

为什么需要"AI 管 AI"？ ​

单一 AI 的上下文退化 ​

子代理驱动的解决方案 ​

完整工作流 ​

三种角色的子代理 ​

1. 实现子代理（Implementer） ​

2. 规格审查子代理（Spec Reviewer） ​

3. 代码质量审查子代理（Code Quality Reviewer） ​

智能模型选择 ​

实战演示：子代理驱动实现搜索功能 ​

全流程展示 ​

与人工的交互点 ​

与 GStack 执行方式的对比 ​

小结 ​