subagent-driven-development

Subagent-Driven Development

用途

• 把"一个 agent 从头写到尾"改成"主 agent 编排 + 多个 subagent 分而治之"。
• 适合大型功能实现、跨模块重构、多文件同步修改等场景。
• 配合 wave-execution 使用：wave-execution 规划波次，subagent-driven-development 执行每个子任务。

核心模式

1. Context Brief（上下文简报）

每个 subagent 启动时接收一份独立的上下文简报，包含：

## 任务目标
{一句话描述}

## 约束
- 只修改以下文件/目录：{范围}
- 遵循以下规则：{相关 rules 文件路径}
- 接口契约：{API/类型定义路径}

## 输入
- 上游任务产出：{文件路径或内容摘要}
- 相关测试：{已有测试文件路径}

## 期望产出
- 代码变更：{文件列表}
- 测试：{测试文件列表}
- 验证命令：{如何确认任务完成}

2. 编排策略

| 任务类型 | subagent 分派策略 |

|---------|-----------------|

| 模块实现 | 每个模块一个 subagent，共享接口契约 |

| 测试编写 | 独立 subagent，输入为实现代码的只读快照 |

| 代码审查 | 独立 subagent，审查其他 subagent 的产出 |

| 文档更新 | 独立 subagent，所有代码变更完成后执行 |

| Bug 修复 | 单个 subagent with systematic-debugging 技能 |

3. 两阶段 Review（来自 superpowers）

每个 subagent 产出后经历两阶段审查：

第一阶段：自动验证

• 代码编译/lint/type-check 通过
• 测试通过
• 不超出文件修改范围
• 遵循 conventional commit 格式

第二阶段：cross-review

• 另一个 subagent（或 code-reviewer agent）审查产出
• 检查目标：逻辑正确性、边界处理、与上游/下游的一致性
• 审查结果为 Abort 时，退回原 subagent 修改

默认做法

1. 任务拆分：从 delivery plan 或 wave plan 接收任务列表。

1. Context Brief 生成：为每个子任务生成独立的 context brief。

1. subagent 分派：

• 简单实现任务 → backend-engineer / frontend-engineer agent
• 测试任务 → tdd-guide agent
• 审查任务 → code-reviewer agent
• 架构任务 → architect agent

1. 完成收口：

• 检查所有 subagent 产出的一致性
• 确认无文件冲突
• 运行集成测试
• 合并所有变更

1. 异常处理：

• subagent 执行超时 → 收集当前进度，由主 agent 接管
• subagent 反复失败 → 升级给 tech-lead
• 文件冲突 → 主 agent 解决冲突或回退到顺序执行

触发信号

• 单次改动涉及 5 个以上文件或 3 个以上模块。
• wave-execution 产出的波次中存在可拆分的大任务。
• 用户要求"用多个 agent 并行处理"。
• 任务复杂度导致单个上下文窗口无法有效管理。

配套约束

1. 边界清晰：每个 subagent 的修改范围必须无重叠，避免 merge conflict。
2. 接口先行：涉及多 subagent 协作时，接口定义必须先锁定再分派。
3. 失败隔离：单个 subagent 的失败不应影响其他 subagent 的产出。
4. 上下文独立：每个 subagent 的 context brief 必须自包含，不依赖对话历史。