多代理开发

通过为每个任务派发新鲜子代理执行实现计划,并在每步后进行两阶段评审(先规格合规,后代码质量),实现高质量快速迭代。

核心原则: 每任务新鲜子代理 + 两阶段评审(规格→质量) = 高质量、快迭代

何时使用

有实现计划? ──否──→ 手动执行或先头脑风暴
     │是
任务相对独立? ──否(紧耦合)──→ 手动执行或先头脑风暴
     │是
留在当前会话? ──否──→ 使用并行会话执行(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规格合规 → 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: 仅当任务操作完全不同的文件且无逻辑依赖时安全。并行实现完成后评审仍需串行。出现任何冲突立即回退串行。

故障排查

依赖说明

运行环境

• Agent平台: 支持子代理派发能力的AI Agent(Claude Code / Cursor / Codex等)
• 操作系统: Windows / macOS / Linux
• Git: 必需(分支管理、提交、worktree)

第三方依赖

API Key 配置

• 本技能基于Markdown指令,无需额外API Key

可用性分类

• 分类: MD+EXEC(纯Markdown指令,需要子代理派发与命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent编排子代理执行开发任务。需要Agent平台支持子代理派发功能。