Claude Code 多智能体协作模式详解

Claude Code 提供了两种强大的多智能体协作模式：子智能体（Subagents） 和 智能体团队（Agent Teams）。它们如同两种不同的项目管理方法论，适用于从简单任务到复杂工程的各种场景。本文将详细解读这两种模式的核心差异、适用场景、配置方法以及实战策略。

---

一、两种模式的核心差异

1.1 核心差异对比表

维度	Subagents（子智能体）	Agent Teams（智能体团队）
上下文管理	拥有独立上下文窗口，执行结果摘要后返回给主调用者	完全独立的上下文窗口，每个 Teammate 都是独立运行的 Claude 实例
通信方式	只能单向向主 Agent 汇报结果，无法与其他子智能体直接通信	Teammates 之间可以直接互相发送消息，支持 peer-to-peer 协作讨论
任务协调	由主 Agent 统一管理所有任务分配、进度和结果汇总	通过共享任务列表实现自主认领，团队内部自主协调推进
适用场景	专注于结果输出的单一任务，无需协作讨论（如代码片段生成、单模块分析）	需要多角色协作、深度讨论的复杂项目（如系统架构设计、多模块并行开发）
Token 成本	较低：仅将结果摘要回传主上下文，减少冗余 Token 消耗	较高：每个 Teammate 都是独立实例，并行调用会显著增加 Token 用量

1.2 通俗理解

• Subagents 更像「外包员工」：只需要接收指令、交付结果，不参与团队内部讨论，也不和其他外包同事沟通。
• Agent Teams 更像「项目开发组」：有 Team Lead 统筹任务，成员之间可以互相交流、同步进度、甚至争论方案，共同完成复杂项目。

1.3 选择建议

• 当你只需要快速完成一个独立子任务，且不需要中间协作时 → 选 Subagents，成本更低、更高效。
• 当你需要拆解复杂项目、多角色并行协作、或需要智能体之间深度讨论时 → 选 Agent Teams，能处理更复杂的工程场景。

1.4 补充说明

• Agent Teams 目前仍为实验性功能，需要手动开启环境变量才能使用。
• Subagents 是更成熟的轻量方案，适合大多数日常开发场景。

---

二、选型场景测试与核心逻辑

2.1 场景题答案与深度解析

场景1：5个目录中搜索特定模式的文件

• 正确答案：Subagents
• 解析：
  该任务属于无协作需求的并行执行任务，仅需多个子智能体各自独立完成目录搜索、返回结果即可，无需智能体之间沟通、质疑或方案讨论。
  从成本角度，Subagents 会将结果摘要回传主智能体，Token 消耗远低于启动多个独立 Claude 实例的 Agent Teams，符合"高效低成本完成单一结果导向任务"的选型原则。

场景2：PR审查，希望审查者能互相质疑对方的发现

• 正确答案：Agent Teams
• 解析：
  PR审查的核心需求是多主体协作与观点碰撞，需要智能体之间直接通信、互相验证发现、提出异议并协同完善审查结论。
  Subagents 仅能单向向主智能体汇报结果，无法实现"互相质疑"的对等沟通；而 Agent Teams 支持成员间点对点消息交互，且通过独立上下文窗口保障审查的独立性，完美匹配该复杂协作场景。

2.2 选型核心逻辑总结

任务特征	推荐模式	核心依据
单一结果导向、无协作需求、并行执行	Subagents	低成本、高效率，主智能体统一管控结果
需协作讨论、观点碰撞、对等沟通	Agent Teams	支持双向通信，独立实例保障判断客观性

2.3 实操延伸建议

针对 Windows C++ 客户端开发场景，可将该选型逻辑落地到具体工作：

1. Subagents 适用场景：多模块代码语法检查、不同目录下的内存泄漏检测、批量接口文档生成。
2. Agent Teams 适用场景：复杂模块的架构评审、跨模块交互的 Bug 根因分析、PR 审查中的多维度风险核验（功能、性能、兼容性）。

---

三、启用 Agent Teams 配置指南

Agent Teams 目前为实验性功能，默认禁用，需通过环境变量或配置文件开启。

3.1 通过 settings.json 配置（持久化生效）

1. 找到 Claude Code 配置文件路径：~/.claude/settings.json（Windows 为 C:\Users\[你的用户名]\.claude\settings.json）
2. 在文件中添加 env 字段，将实验开关设为 "1"：

{
  "statusLine": {
    "type": "command",
    "command": "powershell -File $HOME/.claude/statusline-command.ps1"
  },
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

3. 保存后重启 Claude Code，配置将永久生效。

3.2 通过 Shell 环境变量（临时生效）

在终端中执行以下命令，仅对当前 Shell 会话生效：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Windows 环境：

• CMD：set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• PowerShell：$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS="1"

3.3 配置文件常见问题修复

• 缺少逗号：statusLine 节点结束后未加 ,，导致 JSON 解析失败
• 配置不完整：缺少必要的基础结构，仅保留关键配置项
• 路径错误：Windows 系统中使用了 Linux 路径格式

---

四、创建 Agent Teams 实操指南

启用 Agent Teams 后，无需编写代码或配置文件，直接用自然语言描述任务和团队结构，Claude 会自动：

1. 解析你的需求，拆分出独立的 Teammate 角色
2. 为每个角色分配专属上下文与任务目标
3. 协调团队成员并行工作、互相沟通，最终汇总结果

4.1 示例：多角度探索（CLI 工具设计）

我正在设计一个帮助开发者追踪代码库中 TODO 注释的 CLI 工具。
创建一个 Agent 团队从不同角度探索：
- 一位负责 用户体验 (UX)
- 一位负责 技术架构
- 一位扮演 魔鬼代言人 (挑刺)

角色分工与价值：

• UX 角色：聚焦命令设计、交互流程、输出格式，确保工具易用性
• 技术架构角色：负责解析引擎、性能优化、扩展性设计
• 魔鬼代言人：主动质疑方案缺陷（如边界 case、兼容性问题）

4.2 实操关键技巧

1. 角色要具体：避免模糊描述（如"一个工程师"），明确职责边界（如"负责 Windows 客户端兼容性"）
2. 任务要清晰：告诉团队最终要交付什么（如"设计文档"“审查报告”“代码实现”）
3. 鼓励协作：明确要求成员间"互相质疑"“补充观点”，激活团队协作模式
4. 控制团队规模：建议 3-5 个角色，过多会增加 Token 消耗与协调成本

---

五、Agent Teams 团队定制化配置

5.1 基础定制：按职责定义角色

适用于明确审查维度的任务，无需指定数量，由 Claude 自动适配协作逻辑。

示例场景：PR 审查

创建一个 Agent 团队来审查 PR #42，生成三位审查者：
- 一位专注安全影响（如 C++ 内存越界、指针漏洞）
- 一位检查性能影响（如 MFC 控件渲染效率、内存泄漏）
- 一位验证测试覆盖率（如单元测试、边界场景覆盖）

5.2 高级定制：指定数量 + 模型

适用于大规模并行任务，通过量化成员数量和锁定模型，平衡效率与成本。

语法模板：

创建一个有 [X] 个 Teammates 的团队，
[核心任务描述]。
每个 Teammate 使用 [模型名称] 模型。

示例：创建一个有 4 个 Teammates 的团队，并行重构这些模块。每个 Teammate 使用 Sonnet 模型。

5.3 模型选型与任务匹配表

模型类型	适用任务场景	成本特性	C++ 开发适配场景
Sonnet	代码重构、模块开发、常规 PR 审查	中速中成本	MFC/duilib 界面重构、常规功能模块并行开发
Opus	架构设计、复杂 Bug 根因分析、安全审计	低速高成本	客户端核心逻辑架构升级、内存泄漏深度排查
Haiku	简单代码生成、注释编写、格式检查	高速低成本	批量生成代码注释、UI 控件属性检查

---

六、Agent Teams 架构与通信机制

6.1 四个核心组件与职责

组件	核心职责	通俗理解
Team Lead	创建主会话，Spawn（生成）Teammates，统筹任务分配与进度协调	项目组长：发起项目、招人、盯进度、汇总结果
Teammates	独立的 Claude Code 实例，各自处理分配的子任务	开发组员：每个人都是独立的工程师，只干自己的活
Task List	共享的任务列表，Teammates 从中认领任务并更新状态	看板/任务墙：所有任务都在这里，谁有空谁领
Mailbox	消息系统，实现 Agent 之间的直接通信	企业微信/IM：组员之间可以直接发消息、讨论问题

6.2 协作流程拆解

1. 启动阶段：你输入指令后，Team Lead 解析需求，生成对应职责的 Teammates，并把任务拆解后放入 Task List。
2. 执行阶段：Teammates 从 Task List 认领任务，各自独立执行；需要协作时，通过 Mailbox 互相发送消息、同步进展或提出质疑。
3. 汇总阶段：Team Lead 监控所有 Teammates 状态，收集完成结果，最终汇总成完整输出反馈给你。

6.3 通信机制详解

机制	说明	实际作用
自动消息投递	Teammates 发送的消息会自动送达接收者，无需 Lead 轮询	实现组员间即时通信，类似 IM 工具
空闲通知	Teammate 完成当前任务后，会自动通知 Lead	让 Lead 实时掌握任务进度，及时分配新任务
共享 Task List	所有 Agent 可查看任务状态并认领工作	去中心化任务分配，提升并行效率
message	向特定 Teammate 发送点对点消息	精准沟通，避免信息干扰
broadcast	向所有 Teammates 发送广播消息	同步全局信息，成本随团队规模线性增长

---

七、上下文与通信机制

7.1 上下文隔离规则

• 独立上下文窗口：每个 Teammate 都拥有完全独立的上下文，不会共享彼此的对话历史。
• 初始化加载：Teammate 被创建（Spawn）时，会加载与主会话一致的项目上下文：
  • CLAUDE.md：项目说明文档
  • MCP 服务器：已配置的工具/服务
  • Skills：已启用的技能
• 关键限制：Lead 的对话历史不会自动传递给 Teammates，必须在 spawn prompt 中明确提供任务所需的全部上下文信息，否则 Teammate 无法理解前置背景。

7.2 实操注意事项

1. 上下文补全：创建团队时，必须在 Prompt 中完整描述任务背景、目标和约束，不要依赖之前的对话历史。
   • 错误示例：只说「帮我审查这段代码」
   • 正确示例：「我正在开发 Windows C++ 客户端的登录模块，这段代码处理密码加密逻辑，请创建一个团队从安全、性能、兼容性三个角度审查，要求指出潜在的内存泄漏和跨版本兼容问题」
2. 通信成本控制：避免频繁使用 broadcast，优先用 message 点对点沟通，减少不必要的 Token 消耗。
3. 状态感知：利用「空闲通知」机制，在 Lead 视图下实时监控任务完成情况，及时调度新任务。

---

八、本地存储机制

8.1 核心存储路径

类型	路径格式	说明
团队配置	~/.claude/teams/<team-name>/config.json	存储团队的核心配置信息，包括成员列表、角色定义等
共享任务列表	~/.claude/tasks/<team-name>/	存储团队的共享任务数据，每个任务对应独立文件或目录

Windows 路径映射：~ 对应你的用户目录，例如 C:\Users\你的用户名\.claude\...

8.2 config.json 配置解析

团队配置文件 config.json 是团队协作的核心元数据，包含一个 members 数组，记录每个 Teammate 的关键信息：

{
  "members": [
    {
      "name": "UX 专家",
      "agentId": "ux-expert",
      "agentType": "expert"
    },
    {
      "name": "架构师",
      "agentId": "arch-expert",
      "agentType": "architect"
    }
  ]
}

• name：成员名称（如 “UX 专家”、“性能审查员”）
• agentId：唯一标识符，用于系统内部通信和任务分配
• agentType：成员类型（如 “reviewer”、“developer”、“architect”），用于角色权限控制

8.3 本地存储的核心优势

1. 数据安全：所有信息仅存储在本地，不会上传到 Anthropic 或第三方服务器，避免代码和敏感信息泄露。
2. 离线可用：即使断网，也能查看团队配置、任务历史和通信记录，不影响协作复盘。
3. 可审计性：你可以直接打开配置文件，查看团队结构和任务分配，便于调试和问题排查。
4. 版本可控：可以将 .claude 目录纳入 Git 管理，实现团队配置和任务历史的版本控制。

---

九、权限、任务与 Token 成本

9.1 权限继承与安全提示

• 权限继承规则：所有 Teammates 会继承 Lead 的权限设置。如果 Lead 使用 --dangerously-skip-permissions 跳过权限校验，所有 Teammates 也会继承该高风险模式。
• 修改时机：只能在 Teammate 生成（Spawn）后修改单个成员的权限模式，无法在创建时直接指定。
• 优化建议：在创建团队前，预先在权限设置中批准常用操作（如文件读写、命令执行），可避免协作过程中频繁出现权限提示中断。

9.2 任务依赖与认领机制

任务状态	含义	流转逻辑
pending	待处理	未被认领，或依赖其他任务未完成
in progress	进行中	已被 Teammate 认领，正在执行
completed	已完成	任务执行完毕，依赖它的任务会自动解除阻塞

• 依赖关系：任务可设置前置依赖，被阻塞的任务在依赖项完成前无法被认领。
• 并发控制：使用文件锁机制防止多个 Teammate 同时认领同一任务，避免竞争冲突。

9.3 Token 使用与性价比策略

• 消耗规律：每个 Teammate 拥有独立上下文窗口，Token 消耗随活跃 Teammates 数量线性增长。
• 场景适配：
  • ✅ 适合：研究、PR 审查、新功能开发等复杂任务，额外 Token 消耗可通过协作效率提升覆盖。
  • ❌ 不适合：简单日常任务，单个会话更具成本效益。
• 高性价比配置：
  • Lead 使用强推理模型（如 Opus）负责统筹、决策和最终汇总。
  • Teammates 使用轻量模型（如 Sonnet）负责执行具体子任务，平衡成本与效果。

---

十、Agent Teams 项目实测案例

10.1 项目背景与目标

• 项目：为 PicTacticAgent 实现「提示词模板库」功能
• 团队规模：5 人 Agent Team，覆盖从架构设计到代码审查的完整开发链路
• 模型版本：使用 Opus 4.6 作为核心模型，保证复杂任务的推理能力

10.2 角色分工与职责

角色	核心职责
architect	完善系统设计：表结构、API 接口定义
backend	实现数据库模型、Service 层、API 路由
frontend	实现 UI 组件、Hook、页面、API 客户端
qa	编写单元测试 + 集成测试并执行
reviewer	对所有代码改动做全面代码审查

10.3 执行顺序设计（依赖关系）

architect 先行 → backend/frontend 并行 → qa → reviewer

• 串行阶段：architect 先完成架构设计，为后续开发提供规范和接口契约
• 并行阶段：backend 和 frontend 基于统一接口并行开发，提升效率
• 验证阶段：qa 执行测试验证功能正确性，最后 reviewer 做代码质量把关

10.4 验收标准

1. 功能可用：模板 CRUD、搜索、从模板生成功能必须完整可用
2. 测试通过：
   • 新增测试用例全部通过
   • 现有测试用例不受影响，保证向后兼容
3. 质量保障：代码审查通过，符合项目编码规范

10.5 C++ 开发场景可复用模板

请为 Windows C++ 客户端实现「新登录界面」功能。
创建一个 5 人 Agent Team：
1. architect - 完善界面架构：控件布局、消息机制、接口定义
2. core - 实现登录逻辑、密码加密、Session 管理
3. ui - 实现 MFC/duilib 界面渲染、事件响应、样式适配
4. qa - 编写单元测试 + 兼容性测试（Windows 10/11、高 DPI）
5. reviewer - 对所有改动做代码审查，重点检查内存泄漏和资源泄漏

执行顺序：architect 先行 → core/ui 并行 → qa → reviewer。

验收标准：
- 登录界面可正常显示、交互流畅
- 新增测试全部通过，现有测试用例不受影响
- 无内存泄漏、GDI 资源泄漏，符合公司 C++ 编码规范

---

十一、界面操作与查看指南

11.1 基础切换操作

• 方向键 ↓ / ↑：在不同 Agent 之间上下切换
• 回车键 Enter：展开/收起当前 Agent 的详细对话与输出内容
• Tab 键：快速在主对话和 Agent 对话之间跳转

11.2 界面状态解读

• 绿色圆点 ●：表示当前活跃/正在执行任务的 Agent
• Coalescing...：表示系统正在汇总多个 Agent 的输出，或等待其他 Agent 完成任务
• @main：是你的主对话上下文，所有 Agent 的最终结果会汇总到这里
• 其他 @xxx：是团队中的独立 Agent，各自拥有独立上下文

11.3 高效查看技巧

1. 先看主上下文：在 @main 视图下，可以看到所有 Agent 的任务进展和最终汇总结果
2. 深入单个 Agent：切换到具体 Agent（如 @ux-expert），查看该角色的详细思考过程、代码片段或讨论内容
3. 并行对比：展开多个 Agent 的对话，横向对比不同角色的输出差异
4. 过滤视图：部分版本支持通过 /filter 命令，只显示特定 Agent 的输出

---

十二、Subagents 模式详解

12.1 工作原理

子智能体模式采用主从架构：

• 一个主智能体负责任务拆解和结果汇总
• 多个子智能体负责独立执行子任务
• 子智能体完成任务后，只返回结果摘要给主智能体

12.2 核心特征

特性	详细描述
上下文管理	子智能体拥有独立上下文窗口，但执行结果会摘要回传主智能体
通信方式	单向通信：子智能体 → 主智能体，子智能体之间无法直接交流
任务协调	主智能体集中管理所有任务分配、进度监控和结果整合
执行效率	极快，子智能体并行执行，结果快速汇总
成本控制	低成本，只需支付子任务执行和结果摘要的 Token

12.3 适用场景

子智能体模式是效率优先的选择，适合以下场景：

1. 批量文件处理：如在多个目录中搜索特定模式的文件
2. 代码质量检查：如对不同模块进行语法检查或安全扫描
3. 文档生成：如为多个 API 接口生成文档
4. 简单数据分析：如统计代码库中的 TODO 注释分布

12.4 使用示例

场景：需要在 10 个目录中搜索包含特定正则表达式的 C++ 源文件

我需要在以下目录中搜索包含正则表达式 "TODO:\\s*\\d+" 的 C++ 源文件：
- src/core
- src/ui
- src/network
- test/unit
- test/integration

创建子智能体并行执行搜索任务，每个子智能体负责一个目录，完成后汇总结果。

---

十三、决策框架与场景矩阵

13.1 任务复杂度评估

任务复杂度 = (任务分解难度 × 2) + (协作需求 × 3) + (决策难度 × 1)

• 简单任务（评分 < 5）：单一智能体足够
• 中度任务（评分 5-10）：子智能体模式
• 复杂任务（评分 > 10）：智能体团队模式

13.2 场景决策矩阵

场景类型	推荐模式	核心理由
代码搜索/分析	Subagents	独立任务，快速结果
简单代码生成	Subagents	单一职责，无需讨论
PR 审查	Agent Teams	需要多维度审查和讨论
架构设计	Agent Teams	需要深度讨论和方案对比
复杂问题排查	Agent Teams	需要交叉验证和协作分析
批量文件处理	Subagents	并行执行，效率优先

---

十四、总结与建议

Claude Code 提供的两种多智能体协作模式为开发工作带来了全新的可能性。

核心建议：

• 任务简单且无需协作时，选择 Subagents 模式
• 任务复杂且需要多角色沟通时，选择 Agent Teams 模式
• 在实际项目中，可以根据任务阶段灵活切换模式

关键启示：

• Subagents：像工厂流水线，每个工人负责特定工序，快速高效，无需交流
• Agent Teams：像研发部门，成员需要讨论方案、解决问题，协同创新

通过合理使用多智能体协作，开发者可以显著提高开发效率，降低复杂度，专注于更有价值的工作。

---

附录：快速参考

常用快捷键

功能	快捷键
切换智能体	↓ / ↑
展开/收起智能体内容	Enter
主对话和智能体对话跳转	Tab
切换到主对话	Shift + Tab

Windows 配置快速指南

1. 创建配置目录：

   mkdir -p $HOME/.claude
   

2. 创建配置文件：

   notepad $HOME/.claude/settings.json
   

3. 验证配置：

   Get-Content $HOME/.claude/settings.json
   

查看团队配置

Get-Content $HOME/.claude/teams/<team-name>/config.json