多代理开发
通过为每个任务派发新鲜子代理执行实现计划,并在每步后进行两阶段评审(先规格合规,后代码质量),实现高质量快速迭代。
核心原则: 每任务新鲜子代理 + 两阶段评审(规格→质量) = 高质量、快迭代
何时使用
有实现计划? ──否──→ 手动执行或先头脑风暴
│是
任务相对独立? ──否(紧耦合)──→ 手动执行或先头脑风暴
│是
留在当前会话? ──否──→ 使用并行会话执行(execute-elsewhere)
│是
▼
使用多代理开发(本技能)
与并行会话执行的对比:
- 同一会话(无上下文切换)
- 每任务新鲜子代理(无上下文污染)
- 每任务后两阶段评审:先规格合规,后代码质量
- 更快迭代(任务间无需人工介入)
执行流程
读取计划,提取所有任务全文,记录上下文,创建TodoWrite
│
▼
┌─── 每个任务 ────────────────────────────────────┐
│ │
│ 派发实现子代理(提供完整任务文本+上下文) │
│ │ │
│ 子代理有疑问? ──是──→ 回答问题,提供上下文──→重新派发│
│ │否 │
│ 子代理实现、测试、提交、自评审 │
│ │ │
│ 派发规格评审子代理 │
│ │ │
│ 规格合规? ──否──→ 实现子代理修复规格差距──→重新评审│
│ │是 │
│ 派发代码质量评审子代理 │
│ │ │
│ 质量通过? ──否──→ 实现子代理修复质量问题──→重新评审│
│ │是 │
│ 在TodoWrite中标记任务完成 │
│ │
└─────────────────────────────────────────────────┘
│
▼
还有更多任务? ──是──→ 派发下一个任务实现子代理
│否
▼
派发最终全局代码评审子代理
│
▼
使用"完成开发分支"流程
提示模板
./implementer-prompt.md- 派发实现子代理./spec-reviewer-prompt.md- 派发规格合规评审子代理./code-quality-reviewer-prompt.md- 派发代码质量评审子代理
选择性并行执行策略(差异化)
并非所有任务都必须串行。根据任务依赖关系选择执行策略:
任务依赖分析
在提取任务后,构建依赖图:
任务A(独立) ──┐
任务B(独立) ──┼──→ 任务D(依赖A+B)
任务C(独立) ──┘ │
▼
任务E(依赖D)
执行策略选择
| 任务关系 | 策略 | 说明 |
|---|---|---|
| 完全独立(无共享文件) | 可并行派发实现子代理 | 加速开发,但评审仍串行 |
| 共享文件但无逻辑依赖 | 串行实现,可并行评审 | 避免文件冲突 |
| 有逻辑依赖 | 严格串行 | 等依赖任务完成后再开始 |
| 不确定 | 默认串行 | 安全优先 |
并行安全规则:
- 永远不要并行派发操作同一文件的实现子代理(冲突)
- 并行实现完成后,评审必须串行进行
- 如并行任务出现冲突,回退到串行模式
分层评审机制(差异化)
评审层级
| 层级 | 触发条件 | 评审深度 | 成本 |
|---|---|---|---|
| L0 自评审 | 每次实现后 | 实现子代理自检 | 低 |
| L1 规格合规 | L0通过后 | 对照规格检查完整性 | 中 |
| L2 代码质量 | L1通过后 | 检查代码质量、最佳实践 | 中 |
| L3 全局评审 | 所有任务完成后 | 整体一致性、集成问题 | 高 |
评审顺序(严格遵守)
L0自评审 → L1规格合规 → L2代码质量 → (所有任务完成) → L3全局评审
绝不能在L1规格合规通过前开始L2代码质量评审(错误顺序)。
示例工作流
你: 我正在使用多代理开发来执行这个计划。
[读取计划文件一次: docs/plans/feature-plan.md]
[提取所有5个任务的完整文本和上下文]
[创建TodoWrite包含所有任务]
任务1: 钩子安装脚本
[获取任务1文本和上下文(已提取)]
[派发实现子代理,提供完整任务文本+上下文]
实现者: "开始前 - 钩子应安装在用户级还是系统级?"
你: "用户级(~/.config/hooks/)"
实现者: "明白。开始实现..."
[稍后] 实现者:
- 实现了install-hook命令
- 添加了测试,5/5通过
- 自评审:发现漏了--force标志,已添加
- 已提交
[派发规格合规评审]
规格评审: ✅ 规格合规 - 所有要求满足,无多余内容
[获取git SHA,派发代码质量评审]
代码评审: 优点:测试覆盖好,代码整洁。问题:无。通过。
[标记任务1完成]
任务2: 恢复模式
[获取任务2文本和上下文(已提取)]
[派发实现子代理,提供完整任务文本+上下文]
实现者: [无问题,继续]
实现者:
- 添加了verify/repair模式
- 8/8测试通过
- 自评审:一切正常
- 已提交
[派发规格合规评审]
规格评审: ❌ 问题:
- 缺失:进度报告(规格说"每100项报告")
- 多余:添加了--json标志(未要求)
[实现者修复问题]
实现者: 移除--json标志,添加进度报告
[规格评审重新评审]
规格评审: ✅ 现在规格合规
[派发代码质量评审]
代码评审: 优点:扎实。问题(重要):魔术数字(100)
[实现者修复]
实现者: 提取PROGRESS_INTERVAL常量
[代码评审重新评审]
代码评审: ✅ 通过
[标记任务2完成]
...
[所有任务完成后]
[派发最终代码评审]
最终评审: 所有要求满足,可合并
完成!
优势对比
相比手动执行:
- 子代理自然遵循TDD
- 每任务新鲜上下文(无混淆)
- 并行安全(子代理不互相干扰)
- 子代理可提问(工作前和工作期间)
相比并行会话执行:
- 同一会话(无交接)
- 持续进展(无需等待)
- 评审检查点自动化
效率提升:
- 无文件读取开销(控制器提供完整文本)
- 控制器精确策展所需上下文
- 子代理预先获得完整信息
- 问题在工作开始前浮现(而非之后)
质量门禁:
- 自评审在交接前捕获问题
- 两阶段评审:规格合规,然后代码质量
- 评审循环确保修复实际有效
- 规格合规防止过度/不足构建
- 代码质量确保实现质量优良
成本:
- 更多子代理调用(每任务implementer + 2 reviewers)
- 控制器更多准备工作(预先提取所有任务)
- 评审循环增加迭代
- 但早期捕获问题(比后期调试更便宜)
红旗清单(绝不做)
永远不要:
- 未经用户明确同意在main/master分支开始实现
- 跳过评审(规格合规或代码质量)
- 带着未修复的问题继续
- 并行派发操作同一文件的实现子代理(冲突)
- 让子代理读取计划文件(提供完整文本)
- 跳过场景设定上下文(子代理需要理解任务位置)
- 忽略子代理问题(让其继续前回答)
- 接受规格合规"差不多"(评审发现问题=未完成)
- 跳过评审循环(评审发现问题=实现者修复=重新评审)
- 让实现者自评审替代实际评审(两者都需要)
- 在规格合规通过前开始代码质量评审(错误顺序)
- 在任一评审有未解决问题时进入下一任务
应急流程
子代理提问时
- 清晰完整地回答
- 必要时提供额外上下文
- 不要催促他们进入实现
评审发现问题
- 实现者(同一子代理)修复
- 评审者重新评审
- 重复直到通过
- 不要跳过重新评审
子代理任务失败
- 派发修复子代理并附带具体指令
- 不要手动修复(上下文污染)
子代理上下文不足
- 控制器补充缺失上下文
- 重新派发带完整上下文的子代理
- 记录为学习条目供未来参考
并行任务冲突
- 立即停止冲突任务
- 回退到串行执行
- 记录冲突文件以便未来避免
集成
必需的工作流技能:
- git-worktrees - 必需:开始前设置隔离工作空间
- writing-plans - 创建本技能执行的计划
- requesting-code-review - 评审子代理的代码评审模板
- finishing-a-development-branch - 所有任务完成后完成开发
子代理应使用:
- test-driven-development - 子代理每任务遵循TDD
替代工作流:
- executing-plans - 用于并行会话而非同会话执行
常见问题FAQ
Q: 任务之间有依赖怎么办?
A: 严格串行执行依赖任务。使用依赖图识别哪些任务可并行(完全独立)、哪些必须串行(有逻辑依赖)。不确定时默认串行。
Q: 评审循环太多导致成本过高?
A: 使用分层评审。L0自评审可过滤明显问题,减少L1/L2评审循环。确保实现子代理在提交前充分自检。规格清晰的计划能减少规格合规循环。
Q: 子代理反复提问影响效率?
A: 确保控制器在派发时提供完整上下文(任务全文+场景设定+相关文件内容)。如子代理仍反复提问,可能是计划不够详细,应先完善计划。
Q: 如何判断任务是否"相对独立"?
A: 检查任务是否操作相同文件、是否有数据依赖、是否需要前序任务的输出。如都不涉及,则独立。不确定时按串行处理。
Q: 并行执行真的安全吗?
A: 仅当任务操作完全不同的文件且无逻辑依赖时安全。并行实现完成后评审仍需串行。出现任何冲突立即回退串行。
故障排查
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 子代理产出与规格不符 | 上下文不足或规格模糊 | 补充完整任务文本+场景设定,重新派发 |
| 评审循环超过3次 | 实现质量低或规格不清晰 | 检查规格明确性,考虑重新分解任务 |
| 子代理上下文污染 | 复用了非新鲜子代理 | 确保每任务派发全新子代理 |
| 并行任务文件冲突 | 操作了相同文件 | 立即停止,回退串行执行 |
| TodoWrite状态不同步 | 未及时更新任务状态 | 每完成一个任务立即更新TodoWrite |
| 最终评审发现集成问题 | 任务间接口未对齐 | 在计划阶段明确接口契约 |
依赖说明
运行环境
- Agent平台: 支持子代理派发能力的AI Agent(Claude Code / Cursor / Codex等)
- 操作系统: Windows / macOS / Linux
- Git: 必需(分支管理、提交、worktree)
第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
| Git | 工具 | 必需 | 系统自带或从git-scm.com安装 |
| 子代理能力 | 平台功能 | 必需 | Agent平台需支持子代理派发 |
API Key 配置
- 本技能基于Markdown指令,无需额外API Key
可用性分类
- 分类: MD+EXEC(纯Markdown指令,需要子代理派发与命令行执行能力)
- 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent编排子代理执行开发任务。需要Agent平台支持子代理派发功能。
