Agent Teams 多智能体协作

什么是 Agent Teams？

Agent Teams 是 Claude Code 的实验性功能，允许你编排多个 Claude Code 会话在同一项目上协作。一个会话担任团队领导，负责协调工作、分配任务和综合结果；队友独立工作，各自拥有自己的上下文窗口，并可以直接互相通信。

真正的协作

队友之间可以直接通信、共享发现、相互质疑，而不仅仅是向主 Agent 汇报。

共享任务列表

所有 Agent 共享一个中央任务队列，支持任务状态和依赖关系追踪。

独立上下文

每个队友拥有完全独立的上下文窗口，不会相互污染。

原生集成

内置于 Claude Code 核心，无需外部依赖或脆弱的脚本。

子 Agent vs Agent Teams

两者都可以并行化工作，但运作在不同层面。核心区别在于：你的工作者是否需要互相通信？

特性	子 Agent	Agent Teams
上下文	独立窗口，结果汇总回调用者	独立窗口，完全独立运行
通信	仅向主 Agent 汇报结果	队友之间可直接发消息
协调	主 Agent 管理所有工作	共享任务列表，自协调
适用场景	只关心结果的专注任务	需要讨论和协作的复杂工作
Token 成本	较低（结果汇总回主上下文）	较高（每个队友是独立 Claude 实例）
通信模式	辐射式（全部通过主 Agent）	网状（任意队友到任意队友）
设置要求	无需额外设置	需要环境变量启用

类比：子 Agent 就像你派出去跑腿的承包商，Agent Teams 则是坐在同一个房间里的项目团队 — 每人做自己的部分，同时通过对话保持同步。

何时使用 Agent Teams

Agent Teams 增加协调开销并消耗显著更多的 token。它们在队友可以独立运作于不同范围、同时受益于通信时效果最好。

适合的场景

场景	说明
研究与审查	多个队友同时调查问题的不同方面，然后共享和挑战彼此发现
新模块/功能	队友各自负责独立组件，不会踩到对方的文件
竞争假设调试	队友并行测试不同理论，积极尝试推翻彼此
跨层协调	横跨前端、后端和测试的变更，每层由不同队友负责
辩论与共识	多个队友就架构决策辩论不同立场，收敛到最强方案
大规模分类	队友分割大数据集，独立处理各段

不适合的场景

顺序任务 — 单会话更高效
同文件编辑 — 容易冲突
紧密依赖的工作 — 子 Agent 模式更划算
不需要通信的独立并行变更 — 使用 /batch 更简单
简单并行执行 — 异步工作流即可，无需协作层

快速开始

启用 Agent Teams

设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

或添加到 settings.json 持久化：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

描述任务和团队结构

用自然语言告诉 Claude 你的需求，明确角色和范围：

创建一个 Agent 团队来审查我们的认证系统。生成三个队友：
- 安全审查员：审计漏洞，检查 token 处理
- 性能分析师：分析响应时间，识别瓶颈
- 测试覆盖检查员：验证边界情况，找到未测试的路径
让他们通过任务列表共享发现并协调。

监控和引导团队

Claude 创建团队领导（你的主会话），生成队友并通过共享任务列表分配工作。

键盘快捷键：

快捷键功能
Shift+Down 选择队友（带循环）
Ctrl+T 查看任务列表
Enter 查看选中会话
Escape 中断
清理团队

工作完成后关闭队友并清理：
```
请所有队友关闭，然后清理团队。
```
始终使用领导来清理。先关闭所有队友 — 领导不会在队友仍在运行时清理。

快捷键	功能
Shift+Down	选择队友（带循环）
Ctrl+T	查看任务列表
Enter	查看选中会话
Escape	中断

实际表现

队友通常在 20-30 秒内生成并开始工作
3 个队友的团队大约消耗单会话顺序完成同样工作的 3-4 倍 token
对于复杂任务，时间节省通常远超成本增加

架构

Agent Teams 由四个组件协同工作：

┌────────────────────────────────────────────┐
│              团队领导 (Team Lead)            │
│  创建团队、生成队友、分配任务、综合结果       │
└────────┬──────────────┬──────────────┬──────┘
         │              │              │
    ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
    │ 队友 A  │←→│ 队友 B  │←→│ 队友 C  │
    │ API 层  │   │ 数据库  │   │ 测试    │
    └─────────┘   └─────────┘   └─────────┘
         │              │              │
         └──────────────┼──────────────┘
                        │
              ┌─────────▼─────────┐
              │   共享任务列表      │
              │ (Shared Task List) │
              └───────────────────┘

组件说明

组件	用途
团队领导	你的主 Claude Code 会话。创建团队、生成队友、分配任务、综合结果
队友	独立的 Claude Code 实例。各自拥有上下文窗口，处理分配的任务
共享任务列表	所有 Agent 可见的中央工作队列。任务有状态（pending/in progress/completed）和依赖关系
邮箱	Agent 之间的通信消息系统

文件位置

文件	路径
团队配置	`~/.claude/teams/{team-name}/config.json`
任务列表	`~/.claude/tasks/{team-name}/`

队友初始化

队友生成时会加载与普通 Claude Code 会话相同的项目上下文：

你的 CLAUDE.md
MCP 服务器
Skills

它还会收到领导的生成提示。领导的对话历史不会传递到队友。

通信方式

方式	说明
自动消息投递	系统自动投递
空闲通知	队友空闲时通知
共享任务列表	所有队友可见
直接消息	发送给特定队友
广播	发送给所有队友（成本随团队规模增长，谨慎使用）

权限

队友继承领导的权限设置。生成后可以单独更改队友的权限模式，但生成时无法指定。

实战示例

示例 1：支付模块重构

创建一个 Agent 团队来重构支付模块。生成三个队友：
- API 层负责人：重构支付 API 端点和请求验证
- 数据库迁移负责人：更新数据库 schema 和迁移脚本
- 测试覆盖负责人：确保所有变更有完整测试覆盖
让他们通过共享任务列表协调工作。

示例 2：安全审计

创建安全审查团队。生成三个队友：
- 漏洞扫描员：审查 OWASP Top 10 风险
- 认证审计员：检查 token 处理、会话管理、密码策略
- 依赖检查员：扫描依赖项中的已知漏洞
每人独立工作后共享发现，互相挑战假设。

示例 3：架构决策辩论

创建架构辩论团队。议题：我们的实时通知系统应该用
WebSocket 还是 Server-Sent Events。
- 队友 A：为 WebSocket 方案辩护
- 队友 B：为 SSE 方案辩护
- 队友 C：作为评审，质疑两方论点
最终由评审基于辩论总结推荐方案。

规模化管理

随着 Agent 团队复杂度增长，协调挑战从「能否并行化」转变为「如何管理编排」。三种模式有助于规模化：

1. 标准化生成提示模板

为最常见的团队配置创建可重用的提示结构：

模板类型	定义内容
审查团队	角色、文件边界、成功标准
实现团队	组件划分、接口约定
研究团队	调查方向、汇报格式

2. 权限预设

在生成队友之前预批准常见操作。这消除了可能让新团队陷入困境的权限提示洪流。

{
  "permissions": {
    "allow": [
      "Bash(npm test*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Read",
      "Edit"
    ]
  }
}

3. CLAUDE.md 作为共享运行时上下文

结构良好的 CLAUDE.md（包含模块边界、验证命令和操作上下文）可以显著减少每个队友的探索成本。三个队友读一个清晰的 CLAUDE.md 远比三个队友独立探索代码库便宜。

# 项目结构
- src/api/ — REST API 端点
- src/db/ — 数据库模型和迁移
- src/services/ — 业务逻辑
- tests/ — 测试套件

# 验证命令
- npm test — 运行所有测试
- npm run lint — 代码检查
- npm run typecheck — 类型检查

# 模块边界
- API 层不直接访问数据库
- 服务层负责所有业务逻辑

多 Agent 方案全景

Agent Teams 处于 Claude Code 多 Agent 方案频谱的一端。理解每种工具的定位有助于做出正确选择：

方案	通信	适用场景
单会话	无	顺序、专注的任务
子 Agent（Task 工具）	仅结果回传	并行的专注工作
Builder-Validator 对	通过任务结构化交接	质量门控的实现
Agent Teams	全网状直接通信	协作探索和复杂工作

Hook 事件

Agent Teams 提供专用的 Hook 事件用于自动化工作流：

Hook 事件	触发时机
`TeammateIdle`	队友变为空闲时
`TaskCompleted`	任务完成时

这些 Hook 可用于在队友完成工作时执行规则检查、通知或后续操作。

当前限制

总结

你的需求	推荐方案
快速并行执行，只关心结果	子 Agent
独立的并行文件修改	`/batch` 命令
需要讨论、共享发现、互相挑战的复杂工作	Agent Teams
质量门控的实现流程	Builder-Validator 模式
简单顺序任务	单会话

从本周的一个审查任务开始尝试。开销不大，但这项能力会改变你对复杂开发工作的思考方式。