Superpowers 教程 8：subagent-driven-development（多代理并行开发）

教程概述

系列目录：Superpowers 教程系列索引

subagent-driven-development 是 Superpowers 的高效执行技能。它通过创建子代理来并行执行实现计划中的任务，每个子代理独立工作，然后由主代理进行审查和整合。

你将学到

✅ subagent-driven-development 的工作流程
✅ 两阶段审查机制
✅ 任务分发策略
✅ 并行执行的优势与限制
✅ 实际案例分析

为什么需要子代理开发？

单代理执行的局限

flowchart LR
    A[任务 1] --> B[任务 2]
    B --> C[任务 3]
    C --> D[任务 4]
    D --> E[任务 5]
    E --> F[完成]
    
    style A fill:#ffcccb
    style B fill:#ffcccb
    style C fill:#ffcccb
    style D fill:#ffcccb
    style E fill:#ffcccb
    
    Note over A,E: 串行执行，耗时长

子代理并行执行

flowchart TD
    M[主代理 - 协调] --> S1[子代理 1 - 数据库]
    M --> S2[子代理 2 - 后端 API]
    M --> S3[子代理 3 - 前端组件]
    
    S1 --> R1[审查 1]
    S2 --> R2[审查 2]
    S3 --> R3[审查 3]
    
    R1 --> I[整合]
    R2 --> I
    R3 --> I
    
    style M fill:#e1f5ff
    style S1 fill:#e8f5e9
    style S2 fill:#e8f5e9
    style S3 fill:#e8f5e9
    style I fill:#fff3e0
    
    Note over S1,S3: 并行执行，耗时短

效果对比

指标	单代理串行	子代理并行
10 个任务耗时	~50 分钟	~15 分钟
上下文保持	好	优秀（每个子代理专注一个任务）
错误恢复	从头开始	只重试失败任务
代码质量	稳定	更稳定（两阶段审查）

subagent-driven-development 详解

触发时机

subagent-driven-development 在以下场景自动触发：

有书面实现计划时 - writing-plans 完成后
多个独立任务时 - 任务间无依赖或依赖较少
时间敏感任务 - 需要快速完成时

核心架构

flowchart TD
    subgraph "主会话"
        M[主代理]
        C[协调器]
        R[审查器]
    end
    
    subgraph "子代理池"
        S1[子代理 1]
        S2[子代理 2]
        S3[子代理 3]
        S4[子代理 4]
    end
    
    M --> C
    C -->|分发任务 | S1
    C -->|分发任务 | S2
    C -->|分发任务 | S3
    
    S1 -->|完成任务 | R
    S2 -->|完成任务 | R
    S3 -->|完成任务 | R
    
    R -->|审查通过 | M
    R -->|审查失败 | S1
    
    style M fill:#e1f5ff
    style C fill:#e3f2fd
    style R fill:#fff3e0
    style S1 fill:#e8f5e9
    style S2 fill:#e8f5e9
    style S3 fill:#e8f5e9

两阶段审查机制

每个子代理完成的任务都经过两阶段审查：

阶段 1: 规范符合性审查
├── 是否遵循设计规范？
├── 是否完成任务要求？
├── 测试是否通过？
└── 验收标准是否满足？

阶段 2: 代码质量审查
├── 代码是否清晰？
├── 是否有潜在 Bug？
├── 是否符合最佳实践？
└── 有无需优化的地方？

审查流程

flowchart TD
    A[子代理完成任务] --> B[阶段 1: 规范审查]
    B --> C{符合规范？}
    C -->|否 | D[返回子代理重新完成]
    C -->|是 | E[阶段 2: 质量审查]
    E --> F{质量达标？}
    F -->|否 | G[返回优化建议]
    G --> D
    F -->|是 | H[审查通过，提交]
    D --> A
    
    style B fill:#ffebee
    style E fill:#e3f2fd
    style H fill:#e8f5e9

审查示例

阶段 1: 规范审查

## 审查报告 - 阶段 1

**任务**: Task 3 - 创建标签 API 端点

**规范要求**:
- [x] 实现 GET /api/tags 端点
- [x] 返回 JSON 格式
- [x] 支持分页（page, per_page 参数）
- [x] 包含测试用例

**测试结果**:
```bash
$ pytest tests/test_tag_api.py -v
✓ test_get_tags_list
✓ test_get_tags_pagination
✓ test_get_tags_empty

阶段 1 结论: ✅ 通过 - 符合设计规范


**阶段 2: 代码质量审查**

```markdown
## 审查报告 - 阶段 2

**代码质量评估**:

✅ 优点:
- 代码结构清晰
- 函数命名准确
- 测试覆盖完整

⚠️ 改进建议:

1. 🟡 Minor: 提取分页逻辑为独立函数
   
   当前:
   ```python
   def get_tags(request):
       page = request.GET.get('page', 1)
       per_page = request.GET.get('per_page', 20)
       # 30 行分页逻辑...

建议:

def get_tags(request):
    pagination = get_pagination_params(request)
    # 业务逻辑

🟡 Minor: 添加类型提示

def get_tags(request: HttpRequest) -> JsonResponse:

阶段 2 结论: ✅ 通过 - 建议优化但不阻塞


## 任务分发策略

### 任务分组原则

按层次分组: ├── 数据库任务组 │ ├── 创建迁移 │ └── 运行迁移 ├── 后端任务组 │ ├── 创建模型 │ ├── 创建 Repository │ └── 创建 Controller └── 前端任务组 ├── 创建组件 └── 编写样式


### 依赖感知的分发

```mermaid
graph TD
    T1[Task 1: 数据库迁移] --> T2[Task 2: 模型]
    T2 --> T3[Task 3: Repository]
    T3 --> T4[Task 4: Controller]
    T3 --> T5[Task 5: Service]
    
    T4 --> T6[Task 6: API 测试]
    T5 --> T6
    
    subgraph "批次 1 - 可并行"
        T1
    end
    
    subgraph "批次 2 - 可并行"
        T2
    end
    
    subgraph "批次 3 - 可并行"
        T3
    end
    
    subgraph "批次 4 - 可并行"
        T4
        T5
    end
    
    subgraph "批次 5"
        T6
    end
    
    style T1 fill:#e1f5ff
    style T2 fill:#e8f5e9
    style T3 fill:#fff3e0
    style T4 fill:#f3e5f5
    style T5 fill:#f3e5f5

分发配置

subagent:
  # 并发控制
  concurrency:
    max_parallel: 3  # 最多 3 个子代理并行
    max_retries: 2   # 失败重试次数
    timeout_minutes: 30  # 单个任务超时
  
  # 任务分配策略
  assignment:
    # 按依赖关系分组
    group_by_dependencies: true
    
    # 相似任务分给同一子代理（保持上下文）
    sticky_assignment: true
  
  # 资源限制
  resources:
    max_memory_mb: 512
    max_tokens: 50000

实际工作流程

完整示例：标签系统开发

步骤 1: 准备计划

# 实现计划 - 标签系统

## Phase 1: 数据库
- Task 1: 创建 tags 表迁移
- Task 2: 创建 article_tags 表迁移
- Task 3: 运行迁移

## Phase 2: 后端
- Task 4: 创建 Tag 模型
- Task 5: 创建 TagRepository
- Task 6: 创建 TagController
- Task 7: 定义 API 路由

## Phase 3: 前端
- Task 8: 创建 TagList 组件
- Task 9: 创建 TagSelect 组件
- Task 10: 集成到文章编辑页

## Phase 4: 测试
- Task 11: 单元测试
- Task 12: 集成测试
- Task 13: E2E 测试

步骤 2: 分发任务

主代理分析依赖关系后分发：

批次 1:
└── 子代理 A: Task 1, Task 2 (数据库迁移，可并行)

批次 2:
└── 子代理 B: Task 3 (运行迁移，依赖 Task 1,2)

批次 3:
├── 子代理 A: Task 4, Task 5 (模型和 Repository)
└── 子代理 B: Task 11 (单元测试，可提前准备)

批次 4:
├── 子代理 A: Task 6, Task 7 (Controller 和路由)
└── 子代理 C: Task 8, Task 9 (前端组件)

批次 5:
├── 子代理 A: Task 12 (集成测试)
├── 子代理 C: Task 10 (前端集成)
└── 子代理 B: Task 13 (E2E 测试准备)

步骤 3: 子代理执行

子代理 A 执行 Task 1:

## 子代理执行报告

**代理**: Agent-A
**任务**: Task 1 - 创建 tags 表迁移
**开始时间**: 10:00
**结束时间**: 10:03

**执行内容**:

1. 创建迁移文件
   - 路径：`database/migrations/20260228_create_tags_table.sql`
   - 内容：CREATE TABLE tags (...)

2. 验证
   - SQL 语法检查通过
   - 文件存在确认

**提交审查**:
- 文件：`database/migrations/20260228_create_tags_table.sql`
- 测试：`sqlint migrations/20260228_create_tags_table.sql`

审查器审查 Task 1:

## 审查结果

**Task 1**: ✅ 通过

阶段 1 - 规范审查:
- [x] 迁移文件创建
- [x] SQL 语法正确
- [x] 包含所有字段

阶段 2 - 代码审查:
- [x] 命名规范
- [x] 包含注释
- [x] 索引合理

**状态**: 已提交到 Git

步骤 4: 并行推进

时间线:

10:00 - 子代理 A 开始 Task 1
10:00 - 子代理 B 开始 Task 2
10:03 - 子代理 A 完成 Task 1，通过审查
10:04 - 子代理 B 完成 Task 2，通过审查
10:04 - 子代理 A 开始 Task 4
10:05 - 子代理 B 开始 Task 3
10:07 - 子代理 A 完成 Task 4，审查中...
10:08 - 子代理 B 完成 Task 3，审查中...
...

步骤 5: 整合完成

所有任务完成后：

✅ Phase 1: 数据库 - 完成
✅ Phase 2: 后端 - 完成
✅ Phase 3: 前端 - 完成
✅ Phase 4: 测试 - 完成

主代理整合:
- 合并所有提交
- 运行完整测试套件
- 准备 finishing-a-development-branch

错误处理与恢复

子代理失败处理

flowchart TD
    A[子代理执行任务] --> B{成功？}
    B -->|是 | C[审查]
    B -->|否 | D{重试次数？}
    D -->|< 最大 | E[重试]
    E --> A
    D -->|>= 最大 | F[标记失败]
    F --> G[主代理介入]
    G --> H{关键任务？}
    H -->|是 | I[主代理亲自完成]
    H -->|否 | J[跳过或延后]
    
    style A fill:#e8f5e9
    style C fill:#e8f5e9
    style F fill:#ffebee
    style I fill:#e3f2fd

失败示例

## 子代理执行失败

**任务**: Task 7 - 定义 API 路由

**失败原因**:
- 路由文件被其他进程锁定
- 重试 2 次后仍然失败

**主代理介入**:
1. 检查文件锁状态
2. 发现是 IDE 预览导致
3. 关闭预览后重试
4. Task 7 完成

**经验记录**:
- 路由文件编辑前检查文件锁
- 与 IDE 集成时需要注意

部分失败处理

场景：10 个任务中 8 个成功，2 个失败

处理策略:
1. 成功的 8 个任务继续审查流程
2. 2 个失败任务重试或主代理介入
3. 不阻塞整体进度
4. 最后统一整合

性能优化

优化 1: 智能批处理

subagent:
  batching:
    # 小任务合并执行
    merge_small_tasks: true
    merge_threshold_minutes: 2
    
    # 示例:
    # Task 1: 创建文件 A (1 分钟)
    # Task 2: 创建文件 B (1 分钟)
    # → 合并给一个子代理执行

优化 2: 上下文缓存

subagent:
  context:
    # 共享上下文，减少重复加载
    shared_context:
      - design_document
      - coding_standards
      - project_structure
    
    # 子代理特定上下文
    per_agent_context:
      - current_task
      - related_files

优化 3: 结果预测

主代理预测任务耗时:
- 数据库迁移：3 分钟
- 模型创建：5 分钟
- 测试编写：10 分钟

根据预测优化分发:
- 长任务优先分发
- 短任务合并执行
- 关键路径任务优先

与其他技能配合

with writing-plans

writing-plans 输出结构化计划
    ↓
subagent-driven-development 解析计划
    ↓
按依赖关系分发任务

with TDD

子代理开始任务
    ↓
test-driven-development 触发
    ↓
子代理先写测试再实现
    ↓
审查包括测试覆盖率检查

with code-review

子代理完成任务
    ↓
requesting-code-review 触发
    ↓
两阶段审查
    ↓
审查通过后提交

最佳实践

1. 任务独立性

✅ 好：任务间无共享状态
❌ 坏：任务需要互相等待

示例:
✅ Task 1: 创建模型 (独立)
   Task 2: 创建组件 (独立)

❌ Task 1: 写入文件 A 的第 1-10 行
   Task 2: 写入文件 A 的第 11-20 行 (会冲突)

2. 合理的并发数

根据资源调整:
- 本地开发：2-3 个子代理
- 云服务器：5-10 个子代理
- 受限时：1 个子代理（退化为串行）

3. 明确的验收标准

✅ 好：具体的验收标准
❌ 坏：模糊的完成定义

示例:
✅ "测试通过率 100%"
   "API 响应时间 < 100ms"
   "覆盖率 >= 85%"

❌ "功能正常工作"
   "代码质量良好"

小结

subagent-driven-development 通过并行执行和两阶段审查提升效率：

并行执行 - 多个子代理同时工作
两阶段审查 - 规范 + 质量双重保障
依赖感知 - 智能任务分发
错误恢复 - 失败任务自动重试

关键要点

✅ 任务独立性是并行的前提
✅ 两阶段审查保证质量
✅ 依赖关系决定执行顺序
✅ 失败任务有恢复机制

性能提升

任务数量	串行耗时	并行耗时	提升
5	25 分钟	10 分钟	2.5x
10	50 分钟	15 分钟	3.3x
20	100 分钟	25 分钟	4x

系列导航：

← 上一篇：教程 7：代码审查技能完全指南
→ 下一篇：教程 9：verification-before-completion 与 finishing-a-branch
返回：教程系列索引