Claude Code Agent Teams - 多智能体协作团队功能
2026-02-07 2026年01月 20260206-Claude-Code-Agent-Teams-多智能体协作.md

Claude Code Agent Teams - 多智能体协作团队功能

整理时间： 2026-02-06 14:31
来源： 群聊消息 - 盛万春分享
原始链接： https://code.claude.com/docs/en/agent-teams
整理人： AI助手

摘要

Claude Code 推出了实验性的 Agent Teams（智能体团队） 功能，允许用户协调多个 Claude Code 实例协同工作。一个会话作为团队负责人（Lead），协调工作、分配任务并综合结果；团队成员各自在独立的上下文窗口中独立工作，并可以直接相互通信。

核心概念

Agent Teams vs Subagents（子代理）

特性 Subagents Agent Teams
上下文 拥有独立上下文，结果返回给调用者 拥有独立上下文，完全独立运行
通信 仅向主代理报告结果 团队成员直接相互通信
协调 主代理管理所有工作 共享任务列表，自主协调
最佳场景 只需要结果的聚焦任务 需要讨论和协作的复杂工作
Token 成本 较低：结果汇总到主上下文 较高：每个成员都是独立的 Claude 实例

何时使用 Agent Teams

Agent Teams 最适合以下场景：

  1. 研究和审查：多个成员可以同时调查问题的不同方面，然后分享和挑战彼此的发现
  2. 新模块或功能开发：成员可以各自负责不同的部分，互不干扰
  3. 调试与竞争假设：成员并行测试不同的理论，更快地收敛到答案
  4. 跨层协调：涉及前端、后端和测试的变更，每个部分由不同的成员负责

启用与启动

启用 Agent Teams

默认情况下，Agent Teams 是禁用的。需要设置环境变量：

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

创建第一个团队

启用后，用自然语言告诉 Claude 创建团队并描述任务和团队结构：

我正在设计一个帮助开发者跟踪代码库中 TODO 注释的 CLI 工具。
创建一个 Agent Team 从不同角度探索这个问题：
一个成员负责 UX，一个负责技术架构，一个扮演魔鬼倡导者。

团队控制

显示模式

  1. In-process 模式（默认）：所有团队成员在主终端内运行，使用 Shift+Up/Down 选择成员直接发送消息
  2. Split panes 模式：每个成员有自己的面板，可以一次看到所有人的输出。需要 tmux 或 iTerm2

指定成员和模型

可以指定团队成员数量和使用的模型：

创建一个包含 4 名成员的团队来并行重构这些模块。
每个成员使用 Sonnet 模型。

计划审批模式

对于复杂或有风险的任务，可以要求成员在实施前提交计划：

生成一个架构师成员来重构认证模块。
在实施任何更改前需要计划审批。

委托模式（Delegate Mode）

启用后，负责人仅限于协调工具：生成、消息发送、关闭成员和管理任务，不直接处理代码。

按 Shift+Tab 切换到委托模式。

直接通信

每个成员都是完整的独立 Claude Code 会话：
- In-process 模式：Shift+Up/Down 选择成员，直接输入消息
- Split pane 模式：点击成员的面板直接交互

任务管理

共享任务列表

团队使用共享任务列表协调工作：
- 待处理（Pending）：等待执行的任务
- 进行中（In Progress）：已被认领的任务
- 已完成（Completed）：已完成的任务

任务可以设置依赖关系，有未解决依赖的任务在被阻塞前无法被认领。

任务认领

  • 负责人分配：明确告诉负责人将任务分配给哪个成员
  • 自主认领：完成任务后，成员自动选择下一个未分配、未被阻塞的任务

关闭成员和清理团队

要求研究员成员关闭
清理团队

清理前需要确保所有成员都已关闭。

架构详解

团队组成

组件 角色
Team Lead 主 Claude Code 会话，创建团队、生成成员、协调工作
Teammates 独立的 Claude Code 实例，各自处理分配的任务
Task List 共享的工作项列表，成员认领和完成
Mailbox 代理间通信的消息系统

存储位置

  • 团队配置：~/.claude/teams/{team-name}/config.json
  • 任务列表：~/.claude/tasks/{team-name}/

权限与上下文

  • 成员以负责人的权限设置启动
  • 每个成员有自己的上下文窗口，加载 CLAUDE.md、MCP 服务器和技能
  • 负责人的对话历史不会传递

使用案例

1. 并行代码审查

创建一个 Agent Team 来审查 PR #142。生成三个审查员：
- 一个专注于安全影响
- 一个检查性能影响
- 一个验证测试覆盖率
让他们各自审查并报告发现。

2. 竞争假设调查

用户报告应用在一条消息后退出而不是保持连接。
生成 5 个 Agent 成员来调查不同的假设。
让他们相互讨论，试图反驳彼此的假设，
就像科学辩论一样。用达成的共识更新发现文档。

最佳实践

✅ 应该做的

  1. 给成员足够的上下文：在生成提示中包含任务特定的细节
  2. 适当大小的任务：
  3. 太小：协调开销超过收益
  4. 太大：成员工作太久没有检查，增加浪费风险
  5. 适中：自包含的单元，产生清晰的交付物
  6. 等待成员完成：不要让负责人自己开始实施任务
  7. 从研究和审查开始：有明确边界、不需要写代码的任务

❌ 避免的事

  1. 文件冲突：两个成员编辑同一文件会导致覆盖
  2. 无人监控：让团队长时间无人看管会增加浪费努力的风险
  3. 顺序任务：有依赖的任务不适合并行处理

限制与注意事项

当前限制

  1. 会话恢复：/resume 和 /rewind 不会恢复 in-process 成员
  2. 任务状态延迟：成员有时未能将任务标记为完成
  3. 关闭可能慢：成员在完成当前请求或工具调用后才关闭
  4. 一个团队每个会话：负责人一次只能管理一个团队
  5. 无嵌套团队：成员不能生成自己的团队或成员
  6. 负责人固定：创建团队的会话在其生命周期内是负责人
  7. 权限在生成时设置：所有成员以负责人的权限模式启动
  8. Split panes 需要 tmux 或 iTerm2：VS Code 终端、Windows Terminal、Ghostty 不支持

Token 使用

Agent Teams 使用的 Token 明显多于单个会话。每个成员都有自己的上下文窗口，Token 使用量随活跃成员数量增加而增加。

相关资源

  • 文档：https://code.claude.com/docs/en/agent-teams
  • Subagents 文档：https://code.claude.com/docs/en/sub-agents
  • Git Worktrees：用于手动并行会话
  • 功能对比：Subagent vs Agent Team 详细对比

要点提炼

  • 🤖 Agent Teams 是 Claude Code 的实验性功能，允许多个 AI 实例协同工作
  • 🎯 最适合需要并行探索和协作的复杂任务
  • 💰 Token 成本较高，适合研究、审查和新功能开发
  • 🔄 与 Subagents 不同，团队成员可以直接相互通信
  • ⚙️ 需要设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用
  • 📋 使用共享任务列表协调工作，支持任务依赖
  • 🖥️ 支持 In-process 和 Split pane 两种显示模式
  • ⚠️ 注意文件冲突和 Token 消耗，合理规划任务