AI超载 | 第7章:Subagent军团——一人公司的「AI雇佣兵团队」

传统工作流程的上下文切换：

┌─────────┐   ┌─────────┐   ┌─────────┐

│ 写代码  │ → │ Review  │ → │ 写测试  │

│ 45分钟  │   │ 30分钟  │   │ 45分钟  │

└─────────┘   └─────────┘   └─────────┘

     ↑                                    ↑

     └──── 每次切换损失 10-15 分钟 ────┘

串行执行：

时间线 ──────────────────────────────────→

        ↓写代码↓review ↓写测试↓部署

        1小时  1小时   1小时  1小时

        = 总共 4 小时

并行执行：

时间线 ──────────────────────────────────→

  Agent A：写代码 ████████████

  Agent B：review        ████████████

  Agent C：写测试              ████████████

  Agent D：部署                      ████████████

        = 总共 1 小时（并行）

planner → executor → reviewer

  ↑        ↑          ↑

规划者    执行者     审查者

任务：实现用户登录功能

步骤 1：Planner Agent 制定计划

「需要：

1. 创建用户模型

2. 实现认证服务

3. 创建登录 API

4. 添加单元测试」

步骤 2：Executor Agent 执行

「按照计划实现：创建用户模型...」

步骤 3：Reviewer Agent 审查

「发现安全问题：密码明文存储，需要加密」

Agent A ──┐

Agent B ──┼──→ 汇总

Agent C ──┘

任务：审查 10 个核心文件的质量

分解：

- 文件 1-3 → Subagent A

- 文件 4-6 → Subagent B

- 文件 7-10 → Subagent C

并行执行：

Subagent A：「文件 1-3 审查完成，发现 5 个问题」

Subagent B：「文件 4-6 审查完成，发现 3 个问题」

Subagent C：「文件 7-10 审查完成，发现 7 个问题」

汇总：

主 Agent：「共发现 15 个问题，其中 3 个严重问题...」

主 Agent（CEO）

    ↓ 委托任务

┌─── Subagent A（部门经理）

│        ↓ 委托子任务

│    ┌─ Subagent A1（员工）

│    └─ Subagent A2（员工）

│

└─── Subagent B（部门经理）

         ↓ 委托子任务

     ┌─ Subagent B1（员工）

     └─ Subagent B2（员工）

任务：重构整个电商系统

主 Agent 分配：

→ Subagent A：「负责订单模块重构」

    → Subagent A1：「负责订单服务」

    → Subagent A2：「负责订单数据库」

→ Subagent B：「负责用户模块重构」

    → Subagent B1：「负责用户服务」

    → Subagent B2：「负责用户认证」

→ Subagent C：「负责支付模块重构」

    → Subagent C1：「负责支付服务」

    → Subagent C2：「负责支付网关」

结果逐层汇总，最终主 Agent 输出完整的重构方案

Task Tool 工作原理：

1. 主 Agent 定义任务

   「帮我分析 src/users/ 模块」

2. Task Tool 创建 Subagent Session

   分配独立环境，启动 AI

3. Subagent 执行任务

   读取文件，分析代码

4. Subagent 返回结果

   主 Agent 接收摘要

5. 主 Agent 继续处理

   基于结果继续工作

> [Task Tool]

> 任务描述：分析 src/users/ 模块的架构

> 输出格式：架构报告

> 输出路径：.opencode/explore/user-module.md

❌ 错误理解：

50 个 Subagent = 只能做 50 件事

✅ 正确理解：

50 个 Subagent = 50 个「大型任务槽」

正确用法：

1 个 Subagent 做 1 件大事

= 50 件大事

错误用法：

50 个 Subagent 各做 1 件小事

= 50 件小事（浪费了 Subagent 的能力）

❌ 错误示范：

主 Agent → Subagent：「继续上次的工作」

（Subagent 完全不记得上次是什么）

✅ 正确示范：

主 Agent → Subagent：「请分析 src/orders/ 模块，输出架构报告到指定路径」

（任务明确，完整描述）

Subagent 适合：

- 分析单一模块（10-50 个文件）

- 实现单个功能（1-5 个文件）

- 执行单一操作（1 次工具调用）

Subagent 不适合：

- 分析整个系统（1000+ 文件）

- 实现完整系统（100+ 文件）

- 多轮对话（需要上下文保持）

❌ 模糊任务：

> 帮我看看这个代码有什么问题

✅ 明确任务：

> 请审查 src/orders/order.service.ts 中的以下内容：

> 1. 是否有 SQL 注入风险

> 2. 是否有空指针异常

> 3. 错误处理是否完善

> 输出格式：检查清单 + 问题列表

主 Agent Session：

用户：「我们讨论过...」

Agent：「我记得，上次你说...」

Subagent Session：

用户：「我们讨论过...」

Agent：「抱歉，我不记得之前发生了什么」

❌ Subagent 无法处理：

「继续上次没写完的代码...」

（Subagent 不记得上次是什么）

✅ Subagent 擅长处理：

「分析这个模块，输出报告」

（每次都是完整的新任务）

解决方案：

1. 主 Agent 把上下文写入文件

2. Subagent 读取文件

3. Subagent 基于文件内容执行任务

主 Agent：完整上下文窗口（如 200K tokens）

Subagent：减半的上下文窗口（如 100K tokens）

✅ Subagent 的正确打开方式：

任务足够小，Subagent 能完整处理

= 主 Agent 分配一个「明确的小任务」

❌ Subagent 的错误打开方式：

任务太大，Subagent 上下文装不下

= 应该用主 Agent 而不是 Subagent

❌ 模糊指令：

> 帮我看看这个代码

✅ 清晰指令：

> 请审查 src/users/user.service.ts 的代码质量，

> 检查以下方面：

> 1. 代码可读性（命名、注释、结构）

> 2. 错误处理（异常捕获、日志记录）

> 3. 安全性（输入验证、权限检查）

> 4. 性能（数据库查询、循环优化）

> 输出格式：问题列表 + 严重程度评级

General Agent（主会话）：

✅ 完整上下文

✅ 完整历史记忆

✅ 可以多轮对话

✅ 可以读写文件

✅ 可以执行命令

✅ 知道所有之前的操作

Subagent（Task Tool 创建）：

✅ 独立 Session

❌ 无历史记忆

❌ 有限上下文

❌ 任务单一明确

❌ 专注执行

最佳实践：General + Subagent 协作

General Agent（主）

├── 规划任务

├── 分解任务

├── 分派给 Subagent

└── 汇总结果

    │

    ├── Subagent A → 并行执行独立任务

    ├── Subagent B → 并行执行独立任务

    └── Subagent C → 并行执行独立任务

任务类型                    → 委托对象

─────────────────────────────────────────────────────

复杂功能规划                → planner

代码刚写完需要审查          → code-reviewer

Bug 修复或新功能开发         → tdd-guide

架构决策                    → architect

安全敏感代码审查            → security-reviewer

自主循环执行/监控停滞        → loop-operator

Harness 配置调优            → harness-optimizer

探索/搜索代码库             → Subagent（Haiku）

简单编辑                    → Subagent（Haiku）

多文件实现                  → 主 Agent（Sonnet）

复杂架构                    → 主 Agent（Opus）

安全分析                    → 主 Agent（Opus）

{

  "model": "sonnet",                    // 主 Agent：日常默认

  "env": {

    "MAX_THINKING_TOKENS": "10000",     // 控制思考 token

    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"  // Subagent：80% 便宜

  }

}

Haiku 适合 Subagent：

- 快速搜索文件

- 简单代码分析

- 单一模块理解

- 格式化输出

Haiku 不适合：

- 复杂架构设计

- 安全漏洞分析

- 多文件重构

> 我需要对订单模块进行以下改进：

> 1. 代码审查（发现质量问题）

> 2. 状态机重构（优化设计）

> 3. 单元测试（补充覆盖率）

> 4. 性能优化（解决 N+1）

>

> 请用 Subagent 并行处理这些任务。

主 Agent 创建 4 个 Subagent：

Subagent A（代码审查）：

「审查 src/modules/order/ 目录下的所有文件，

输出：问题列表 + 严重程度评级 + 建议修复方案」

Subagent B（状态机重构）：

「分析 src/modules/order/state-machine.ts，

输出：当前设计问题 + 优化方案 + 实施步骤」

Subagent C（单元测试）：

「分析 src/modules/order/ 的代码，

输出：缺失的测试用例清单 + 建议的测试覆盖点」

Subagent D（性能优化）：

「分析 src/modules/order/ 的数据库查询，

输出：N+1 查询问题清单 + 优化 SQL + 预期性能提升」

时间线（并行）：

0分钟 ──────────────────────────────────→ 60分钟

  │

  ├─ Subagent A：审查代码 ████████████ ✓

  ├─ Subagent B：分析状态机 ████████████ ✓

  ├─ Subagent C：规划测试 ████████████ ✓

  └─ Subagent D：分析性能 ████████████ ✓

              ↑

           同时进行

主 Agent 收集并汇总：

Subagent A（代码审查）：

✅ 发现 12 个问题

├── 🔴 严重（阻塞）：2 个

│   - 密码明文存储

│   - SQL 注入风险

├── 🟡 中等：5 个

│   - 缺少错误处理

│   - 日志记录不规范

└── 🟢 建议：5 个

    - 命名不规范

    - 注释缺失

Subagent B（状态机重构）：

✅ 发现 3 个设计问题

├── 状态转换规则不清晰

├── 缺少状态验证

└── 事件定义冗余

✅ 输出优化方案

Subagent C（单元测试）：

✅ 缺失 15 个测试用例

├── 4 个核心业务逻辑

├── 6 个边界条件

└── 5 个异常处理

Subagent D（性能优化）：

✅ 发现 4 个 N+1 查询

├── 订单列表查询用户信息

├── 订单查询商品详情

└── 批量查询重复执行

✅ 优化后预期提升 70% 性能

主 Agent 基于汇总结果，协调执行：

步骤 1：优先修复阻塞问题

→ 派发 Subagent 修复：密码加密、SQL 注入

步骤 2：执行状态机重构

→ 派发 Subagent：基于优化方案重构

步骤 3：补充单元测试

→ 派发 Subagent：基于测试清单编写测试

步骤 4：性能优化

→ 派发 Subagent：优化 N+1 查询

步骤 5：最终 review

→ 主 Agent 综合验收

❌ 错误分解：

Task A：「读取数据」

Task B：「处理 A 的数据」  ← 依赖 A，不能并行

✅ 正确分解：

Task A：「读取数据」

Task B：「读取配置」

Task C：「读取用户信息」

（三个任务独立，可以并行）

❌ 任务太小：

10 个文件 → 拆成 10 个 Task

（Task 创建有开销，不值得）

✅ 任务合适：

10 个文件 → 拆成 3 个 Task（3+3+4）

（每个 Task 3-4 个文件，平衡良好）

❌ 任务太大：

100 个文件 → 1 个 Task

（太大，无法并行，Subagent 上下文可能不够）

✅ 好的任务描述：

「分析 src/users/ 模块，输出：

1. 模块结构（文件列表）

2. 每个文件用途说明

3. 关键函数清单

4. 依赖关系图

输出到：.opencode/explore/users-module.md」

❌ 差的任务描述：

「帮我看看这个模块有什么问题」

（太模糊，输出不可预测）

推荐并行数量：

- 小项目（< 10 文件）：2-3 个 Subagent

- 中项目（10-50 文件）：3-5 个 Subagent

- 大项目（50+ 文件）：5-10 个 Subagent

注意：50 次调用限制是总量，不是单次并行的数量

Subagent A：「发现 5 个问题，格式：问题+级别+建议」

Subagent B：「发现 3 个问题，格式：问题+级别+建议」

Subagent C：「发现 7 个问题，格式：问题+级别+建议」

主 Agent 汇总：

「共发现 15 个问题，按严重程度分类：

🔴 严重：3 个

🟡 中等：7 个

🟢 建议：5 个」

汇总结果：

1. 🔴 严重问题 1（阻塞上线）

2. 🔴 严重问题 2（安全风险）

3. 🟡 中等问题 1（功能缺陷）

...

❌ 模糊任务：

> 帮我分析这个模块

✅ 详细任务：

> 帮我分析 src/orders/ 模块，输出包含：

> 1. 模块结构（文件树）

> 2. 每个文件用途（1-2 句话）

> 3. 核心函数列表（函数名+参数+返回值）

> 4. 模块依赖关系

> 5. 关键设计模式识别

> 6. 建议的阅读顺序

> 输出格式：Markdown 文档

Subagent A → 主 Agent → Subagent B

示例：

1. Subagent A 分析完毕，发现需要调用某个 API

2. Subagent A 把发现写入文件

3. 主 Agent 读取文件，发现需要让 Subagent B 处理

4. 主 Agent 创建 Subagent B，读取 Subagent A 的输出

5. Subagent B 基于 Subagent A 的结果继续工作

每个 Task Tool 调用 = 1 个 Subagent 配额

✅ 用完配额的方法：

1. 等待当前任务完成

2. Subagent 结果已汇总到主 Agent

3. 继续下一个任务（可以用新的 Subagent）

❌ 错误方法：

创建大量微小 Task（每个 Task 只做 1 件事）

= 50 次调用只能做 50 件小事

Task Tool 调用时可以设置：

- max_attempts：最大重试次数

- timeout：超时时间

- fallback：失败时的备选方案