subagent-driven-development 快速入门

让多个 AI 代理同时干活,每个干一件事,完了一起 review。

这是什么?解决什么问题?

单个 AI 代理一次只能处理一个任务,串行效率低。而且任务多了之后,上下文会爆掉(token 上限),质量也会下降(注意力分散)。

subagent-driven-development 是 Obra/superpowers 出品的 Skill,它解决这个问题的方案是子代理派遣:

• 上下文隔离:每个子任务交给一个新 AI 代理,主代理只持有任务清单
• 两阶段审查:子代理完成后,先做合规性审查(是否按 plan 做),再做代码质量审查
• 人工检查点:关键决策点保留人工介入,避免 AI 跑偏后无法挽回
• 并行加速:独立任务可同时跑多个子代理

这种工作流特别适合:

• 实施已经写好的 plan(writing-plans 的输出)
• 重构(每个模块独立重构)
• 迁移(每个文件独立迁移)
• 测试补全(每个文件独立补测试)

准备工作

• 已完成 writing-plans,有可执行 plan
• 支持子代理的 AI 客户端(Claude Code 原生支持)
• 至少 5-10 分钟时间(子代理启动需要时间)
• 监控输出能力(子代理是异步的)

3 步快速上手

第 1 步:克隆仓库

git clone https://github.com/obra/superpowers.git
cd superpowers
ls skills/subagent-driven-development/

你会看到 SKILL.md、子代理 prompt 模板、状态跟踪示例。

第 2 步:加载 Skill

claude --skill subagent-driven-development

第 3 步:派遣子代理执行 plan

把 writing-plans 输出的 plan.md 内容告诉 AI:

“请按 subagent-driven-development 流程,执行以下 plan 的任务。每个任务派遣独立子代理,完成后做合规性 + 代码质量两阶段审查。” “[plan.md 内容]”

AI 会启动多个子代理,每个子代理负责一个任务。你会看到类似输出:

[子代理 #1] 执行任务 1.1: 创建 points 表迁移
  [完成] ✓ 文件已创建
  [合规审查] ✓ 符合 plan 要求
  [质量审查] ⚠️ 建议加 IF NOT EXISTS

[子代理 #2] 执行任务 1.2: 加入索引
  [依赖] 等待 #1 完成

[子代理 #3] 执行任务 2.1: 创建 PointsRepository
  [并行启动] 不依赖 #1, #2

[检查点] 阶段 1 完成后,需要人工 review 后再进入阶段 2

主代理持有整体进度,子代理只关心单个任务。

常见踩坑

1. 子代理过度独立:子代理不知道整体上下文,可能做出和系统其他部分不一致的决策。需要在 prompt 里强调”和其他模块保持一致”。
2. 没有人工检查点:完全自动化听起来很美,但 AI 跑偏时如果没有人工介入,可能浪费更多时间回头修。
3. 并行任务选择错误:有依赖关系的任务被并行,导致后启动的找不到前置产物。要严格按 plan 的依赖图执行。
4. 资源耗尽:同时启动 50 个子代理可能让 API 限流,Skill 建议控制在 5-10 个并行。
5. 错误传播:一个子代理失败没被发现,后续子代理基于错误状态继续工作。要严格做合规性审查。
6. 上下文丢失:子代理之间不共享上下文,如果一个任务的决策影响另一个,会出问题。

初级用法

• 批量执行 plan:每次执行 writing-plans 输出的下一批任务。
• 大重构分模块:每个模块独立重构,互不干扰。
• 测试补全:对 N 个未测试文件,每个派遣一个子代理补测试。

高级玩法

• 动态调度:根据子代理完成速度动态调整下一个任务分配。
• 失败重试:某个子代理失败,自动重新派遣,同时记录失败原因到 memory。
• 进度仪表盘:实时显示所有子代理状态、完成任务数、失败率。
• 跨工作树并行:用 git worktree 给每个子代理独立分支,合并时统一处理冲突。

小技巧

• 子代理的 prompt 要明确、具体、自包含。不要假设它知道上下文。
• 关键检查点(架构变更、跨模块接口)必须人工 review,不能完全自动化。
• 任务之间有共享状态时,使用文件而不是对话传递信息,更可靠。
• 子代理失败时,不要立刻重试,先看错误原因,可能需要修改 prompt。
• 配合 obra-writing-plans Skill 使用,plan 是子代理的输入,质量直接决定子代理输出质量。
• 用 dispatching-parallel-agents Skill 可以做更激进的并行,适合独立任务。

常见问题 FAQ

Q1: 这个 Skill 跟 subagent-driven-development 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: subagent-driven-development 来自 Obra,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 subagent-driven-development 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 subagent-driven-development,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/obra/superpowers
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• 仓库:https://github.com/obra/superpowers
• subagent-driven-development 目录:https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development
• Claude Code 子代理文档:https://docs.anthropic.com/en/docs/claude-code/overview
• 多代理系统设计:https://lilianweng.github.io/posts/2023-06-23-agent/
• Obra superpowers 主项目:https://github.com/obra/superpowers

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。