编排 Claude Code 的 Agent teams

注意

Agent teams（代理团队）是实验性功能，默认处于禁用状态。您可以通过将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 添加到您的 settings.json 文件或环境变量中来启用它。Agent teams 在会话恢复、任务协调和关闭行为方面存在一些已知限制。

Agent teams 允许您协调多个协同工作的 Claude Code 实例。其中一个会话将扮演“团队主管”（team lead）的角色，负责协调工作、分配任务和整合结果。团队成员（teammates）则各自在独立的上下文窗口中工作，并可以直接相互通信。这与“子代理”（subagents）不同，子代理在单个会话中运行，并且只能向主代理汇报。使用 agent teams，您还可以直接与单个团队成员互动，而无需通过团队主管。

本页内容包括：

• 何时使用 agent teams，包括最佳用例以及与 subagents 的比较
• 启动一个团队
• 控制团队成员，包括显示模式、任务分配和授权
• 并行工作的最佳实践

何时使用 Agent Teams

当并行探索能带来真正价值时，Agent teams 最为有效。完整的场景请参见用例示例。最适合的用例包括：

• 研究与审查：多个团队成员可以同时研究问题的不同方面，然后分享并相互挑战彼此的发现。
• 新模块或新功能：团队成员可以各自负责一个独立的部分，而不会相互干扰。
• 基于竞争性假设进行调试：团队成员并行测试不同的理论，从而更快地找到答案。
• 跨层协调：当变更涉及前端、后端和测试时，可以由不同的团队成员分别负责。

与单个会话相比，Agent teams 会增加协调开销并消耗更多的 token。当团队成员可以独立工作时，它们的效果最好。对于顺序性任务、涉及同一文件的编辑或具有许多依赖关系的工作，使用单个会话或 subagents 会更有效。

与 Subagents 比较

Agent teams 和 subagents 都可以让您并行化工作，但它们的操作方式不同。选择哪种方式取决于您的“工作人员”（workers）是否需要相互通信。

当您需要能够快速汇报的、专注的“工作人员”时，请使用 subagents。当团队成员需要分享发现、相互挑战并自行协调时，请使用 agent teams。

启用 Agent Teams

Agent teams 默认处于禁用状态。您可以通过将环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 的值设置为 1 来启用它，可以在您的 shell 环境中设置，也可以通过 settings.json 文件进行配置：

settings.json

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

启动您的第一个 Agent Team

启用 agent teams 后，您可以用自然语言指示 Claude 创建一个 agent team，并描述您想要的任务和团队结构。Claude 会根据您的提示创建团队、生成团队成员并协调工作。

下面这个例子效果很好，因为三个角色是独立的，可以各自探索问题而无需等待他人：

我正在设计一个 CLI 工具，帮助开发者在他们的代码库中跟踪 TODO 注释。
创建一个 agent team 从不同角度来探索这个问题：一个团队成员负责用户体验（UX），
一个负责技术架构，另一个扮演“魔鬼代言人”（devil's advocate）的角色。

随后，Claude 会创建一个带有共享任务列表的团队，为每个视角生成一个团队成员，让他们探索问题，综合发现，并在完成后尝试清理团队。

团队主管的终端会列出所有团队成员以及他们正在做的工作。您可以使用 Shift + ↑/↓ 来选择一个团队成员并直接向他们发送消息。

如果您希望每个团队成员都在其自己的分割窗格中，请参阅“选择显示模式”。

控制您的 Agent Team

用自然语言告诉团队主管您想要什么。它会根据您的指示处理团队协调、任务分配和授权。

选择显示模式

Agent teams 支持两种显示模式：

• 进程内（In-process）：所有团队成员都在您的主终端内运行。使用 Shift + ↑/↓ 选择一个团队成员，然后输入以直接向他们发送消息。此模式适用于任何终端，无需额外设置。
• 分割窗格（Split panes）：每个团队成员都有自己的窗格。您可以同时看到所有人的输出，并单击进入某个窗格直接进行交互。此模式需要 tmux 或 iTerm2。

tmux 在某些操作系统上存在已知限制，传统上在 macOS 上效果最好。在 iTerm2 中使用 tmux -CC 是进入 tmux 的建议方式。

The default is "auto", which uses split panes if you’re already running inside a tmux session, and in-process otherwise. The "tmux" setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set teammateMode in your settings.json:

{
  "teammateMode": "in-process"
}

To force in-process mode for a single session, pass it as a flag:

claude --teammate-mode in-process

Split-pane mode requires either tmux or iTerm2 with the it2 CLI. To install manually:

• tmux: install through your system’s package manager. See the tmux wiki for platform-specific instructions.
• iTerm2: install the it2 CLI, then enable the Python API in iTerm2 → Settings → General → Magic → Enable Python API.

指定团队成员和模型

Claude 会根据您的任务决定要生成的团队成员数量，您也可以精确指定您的需求：

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

要求团队成员批准计划

对于复杂或有风险的任务，您可以要求团队成员在实施前先制定计划。团队成员将以只读的“计划模式”工作，直到团队主管批准其方法：

生成一个架构师团队成员来重构认证模块。
要求在他们做出任何更改之前批准计划。

当团队成员完成计划后，它会向团队主管发送一个计划批准请求。团队主管会审查该计划，并批准或附带反馈意见予以拒绝。如果被拒绝，团队成员将保持在计划模式，根据反馈修改计划并重新提交。一旦获得批准，团队成员将退出计划模式并开始实施。

团队主管会自主做出批准决定。要影响团队主管的判断，您可以在提示中给出标准，例如“只批准包含测试覆盖率的计划”或“拒绝修改数据库模式的计划”。

使用委托模式（Delegate Mode）

在非委托模式下，团队主管有时会自己开始执行任务，而不是等待团队成员。委托模式通过将团队主管的工具限制为仅限协调的工具来防止这种情况发生：生成、消息传递、关闭团队成员以及管理任务。

当您希望团队主管完全专注于编排工作，例如分解工作、分配任务和综合结果，而不直接接触代码时，此模式非常有用。

要启用它，请先启动一个团队，然后按 Shift + Tab 切换到委托模式。

直接与团队成员交谈

每个团队成员都是一个完整的、独立的 Claude Code 会话。您可以直接向任何团队成员发送消息，以提供额外的指示、提出后续问题或调整他们的方法。

• 进程内模式：使用 Shift + ↑/↓ 选择一个团队成员，然后输入以向他们发送消息。按 Enter 查看团队成员的会话，然后按 Escape 中断他们当前的轮次。按 Ctrl + T 切换任务列表。
• 分割窗格模式：单击进入团队成员的窗格，直接与他们的会话进行交互。每个团队成员都有自己终端的完整视图。

分配和认领任务

共享任务列表用于协调整个团队的工作。团队主管创建任务，团队成员则完成这些任务。任务有三种状态：待处理（pending）、进行中（in progress）和已完成（completed）。任务之间也可以存在依赖关系：一个待处理的任务如果其依赖项尚未解决，那么在这些依赖项完成之前，该任务是无法被认领的。

团队主管可以明确地分配任务，或者团队成员可以自行认领：

• 主管分配：告诉团队主管将哪个任务分配给哪个团队成员。
• 自行认领：完成一个任务后，团队成员会自行接手下一个未分配、无阻塞的任务。

任务认领机制使用文件锁定来防止多个团队成员同时尝试认领同一任务时发生竞态条件。

关闭团队成员

要正常结束一个团队成员的会话：

请研究员团队成员关闭

团队主管会发送一个关闭请求。团队成员可以批准并正常退出，也可以附带解释予以拒绝。

清理团队

完成后，请团队主管进行清理：

清理团队

此操作会移除共享的团队资源。当团队主管运行清理时，它会检查是否有活动的团队成员，如果仍有成员在运行，清理会失败，所以请先关闭他们。

重要提示
始终使用团队主管进行清理。团队成员不应运行清理，因为他们的团队上下文可能无法正确解析，这可能会导致资源处于不一致的状态。

使用钩子（Hooks）强制执行质量门禁（Quality Gates）

您可以使用钩子在团队成员完成工作或任务完成时强制执行规则：

• TeammateIdle：当团队成员即将进入空闲状态时运行。以退出码 2 退出可以发送反馈并让团队成员继续工作。
• TaskCompleted：当任务被标记为完成时运行。以退出码 2 退出可以阻止任务完成并发送反馈。

Agent Teams 工作原理

本节介绍了 agent teams 背后的架构和机制。如果您想开始使用它们，请参阅上文的“控制您的 Agent Team”。

Claude 如何启动 Agent Teams

启动 agent teams 有两种方式：

• 您请求一个团队：给 Claude 一个能从并行工作中受益的任务，并明确要求一个 agent team。Claude 会根据您的指示创建一个。
• Claude 提议一个团队：如果 Claude 判断您的任务将从并行工作中受益，它可能会建议创建一个团队。在它继续之前，您需要进行确认。

在这两种情况下，您都拥有控制权。未经您的批准，Claude 不会创建团队。

架构

一个 agent team 由以下部分组成：

有关显示配置选项，请参阅“选择显示模式”。团队成员的消息会自动送达团队主管。

系统会自动管理任务依赖关系。当一个团队成员完成一个被其他任务依赖的任务时，被阻塞的任务会自动解除阻塞，无需手动干预。

团队和任务存储在本地：

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

团队配置文件包含一个 members 数组，其中包含每个团队成员的姓名、代理 ID 和代理类型。团队成员可以读取此文件以发现其他团队成员。

权限

团队成员启动时会继承团队主管的权限设置。如果团队主管以 --dangerously-skip-permissions 模式运行，所有团队成员也会如此。生成后，您可以更改单个团队成员的模式，但在生成时无法为每个团队成员设置不同的模式。

上下文与通信

每个团队成员都有自己的上下文窗口。生成时，团队成员会加载与常规会话相同的项目上下文：CLAUDE.md、MCP 服务器和技能。它还会收到来自团队主管的生成提示。团队主管的对话历史不会被继承。

团队成员共享信息的方式：

• 自动消息传递：当团队成员发送消息时，消息会自动传递给接收者。团队主管无需轮询更新。
• 空闲通知：当团队成员完成工作并停止时，它们会自动通知团队主管。
• 共享任务列表：所有代理都可以看到任务状态并认领可用的工作。

团队成员消息传递：

• message：向一个特定的团队成员发送消息。
• broadcast：同时向所有团队成员广播。请谨慎使用，因为成本会随着团队规模的扩大而增加。

Token 使用

Agent teams 比单个会话消耗更多的 token。每个团队成员都有自己的上下文窗口，token 使用量会随着活跃团队成员的数量而增加。对于研究、审查和新功能开发等工作，额外的 token 通常是值得的。对于常规任务，单个会话更具成本效益。有关使用指南，请参阅 agent team token 成本。

用例示例

这些示例展示了 agent teams 如何处理那些并行探索能带来价值的任务。

进行并行代码审查

单个审查者倾向于一次只关注一种类型的问题。将审查标准划分为独立的领域，意味着安全性、性能和测试覆盖率都能同时得到彻底的关注。下面的提示为每个团队成员分配了一个独特的视角，以避免他们工作重叠：

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

每个审查者都基于同一个 PR 工作，但采用不同的筛选标准。在他们完成后，团队主管会综合所有三个人的发现。

基于竞争性假设进行调查

当根本原因不明确时，单个代理倾向于找到一个看似合理的解释后就停止寻找。下面的提示通过让团队成员明确地相互对抗来解决这个问题：每个人的工作不仅是调查自己的理论，还要挑战他人的理论。

用户报告应用程序在发送一条消息后就退出了，而不是保持连接。
生成 5 个 agent team 成员来调查不同的假设。让他们互相交谈，
试图推翻彼此的理论，就像一场科学辩论一样。
用最终达成的任何共识来更新发现文档。

这里的关键机制是“辩论”结构。顺序调查会受到“锚定效应”的影响：一旦一个理论被探索，后续的调查就会偏向于它。

通过让多个独立的调查者积极地试图推翻彼此的理论，最终存活下来的理论更有可能是真正的根本原因。

最佳实践

为团队成员提供足够的上下文

团队成员会自动加载项目上下文，包括 CLAUDE.md、MCP 服务器和技能，但他们不会继承团队主管的对话历史。有关详细信息，请参阅“上下文与通信”。在生成提示中包含特定于任务的详细信息：

生成一个安全审查员团队成员，提示如下：“审查 src/auth/ 中的身份验证模块
的安全漏洞。重点关注令牌处理、会话
管理和输入验证。该应用程序使用存储在
httpOnly cookie 中的 JWT 令牌。报告任何问题并附上严重性评级。”

适当调整任务规模

• 太小：协调开销超过了收益。
• 太大：团队成员工作时间过长而没有签到，增加了浪费精力的风险。
• 恰到好处：独立的单元，能产生明确的可交付成果，例如一个函数、一个测试文件或一份审查报告。

团队主管会自动将工作分解为任务并分配给团队成员。如果它没有创建足够的任务，请要求它将工作拆分成更小的部分。为每个团队成员分配 5-6 个任务可以保持每个人的生产力，并允许团队主管在有人遇到困难时重新分配工作。

等待团队成员完成

有时，团队主管会自己开始执行任务，而不是等待团队成员。如果您注意到这种情况：

在继续之前，请等待您的团队成员完成他们的任务

从研究和审查开始

如果您是 agent teams 的新手，请从边界清晰且不需要编写代码的任务开始：审查 PR、研究库或调查错误。这些任务可以展示并行探索的价值，而不会带来并行实施所带来的协调挑战。

避免文件冲突

两个团队成员编辑同一个文件会导致覆盖。将工作分解，以便每个团队成员拥有不同的文件集。

监控和引导

检查团队成员的进度，重新引导无效的方法，并在发现结果时进行综合。让团队在无人看管的情况下运行太久会增加浪费精力的风险。

故障排除

团队成员未出现

如果您要求 Claude 创建团队后团队成员没有出现：

• 在 进程内模式 下，团队成员可能已经在运行但不可见。按 Shift + ↓ 循环浏览活动的团队成员。
• 检查您给 Claude 的任务是否足够复杂以至于需要一个团队。Claude 会根据任务来决定是否生成团队成员。
• 如果您明确要求了 分割窗格，请确保 tmux 已安装并在您的 PATH 中可用：

which tmux

对于 iTerm2，请验证 it2 CLI 已安装并在 iTerm2 偏好设置中启用了 Python API。

权限提示过多

团队成员的权限请求会冒泡到团队主管，这可能会产生摩擦。在生成团队成员之前，在您的权限设置中预先批准常用操作，以减少中断。

团队成员因错误而停止

团队成员在遇到错误后可能会停止，而不是恢复。在进程内模式下使用 Shift + ↑/↓ 或在分割模式下单击窗格来检查他们的输出，然后：

• 直接给他们额外的指示
• 生成一个替代的团队成员来继续工作

团队主管在工作完成前关闭

团队主管可能会在所有任务实际完成之前就判定团队已经结束。如果发生这种情况，请告诉它继续。如果它开始自己做工作而不是授权，您也可以告诉团队主管在继续之前等待团队成员完成。

孤立的 tmux 会话

如果团队结束后 tmux 会话仍然存在，则可能没有被完全清理。列出所有会话并终止由团队创建的会话：

tmux ls
tmux kill-session -t <session-name>

限制

Agent teams 是实验性的。当前需要注意的限制包括：

• 进程内团队成员无法恢复会话：/resume 和 /rewind 不会恢复进程内的团队成员。恢复会话后，团队主管可能会尝试向不再存在的团队成员发送消息。如果发生这种情况，请告诉团队主管生成新的团队成员。
• 任务状态可能滞后：团队成员有时无法将任务标记为已完成，这会阻塞依赖的任务。如果某个任务看起来卡住了，请检查工作是否实际完成，并手动更新任务状态或告诉团队主管去“催促”一下团队成员。
• 关闭可能很慢：团队成员在关闭前会完成当前的请求或工具调用，这可能需要一些时间。
• 每个会话一个团队：一个团队主管一次只能管理一个团队。在开始新团队之前，请先清理当前团队。
• 无嵌套团队：团队成员不能生成自己的团队或团队成员。只有团队主管可以管理团队。
• 团队主管是固定的：创建团队的会话在其整个生命周期内都是团队主管。您不能将团队成员提升为团队主管或转移领导权。
• 权限在生成时设置：所有团队成员都以团队主管的权限模式启动。您可以在生成后更改单个团队成员的模式，但在生成时不能为每个团队成员设置不同的模式。
• 分割窗格需要 tmux 或 iTerm2：默认的进程内模式可在任何终端中工作。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分割窗格模式。
• CLAUDE.md 正常工作：团队成员从其工作目录中读取 CLAUDE.md 文件。使用它来为所有团队成员提供特定于项目的指导。

后续步骤

探索并行工作和授权的相关方法：

• 轻量级授权：subagents 在您的会话中生成辅助代理进行研究或验证，更适合不需要代理间协调的任务。
• 手动并行会话：Git worktrees 允许您自己运行多个 Claude Code 会话，而无需自动化的团队协调。
• 比较方法：请参阅 subagent 与 agent team 的比较，以获得并排的详细分析。

原文：https://code.claude.com/docs/en/agent-teams