{/* TRANSLATED — 已翻译为中文 */}
> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。
# 编排 Claude Code 会话团队
> 协调多个 Claude Code 实例作为团队协同工作，支持共享任务、代理间消息传递和集中管理。
代理团队是实验性功能，默认禁用。通过在你的 [settings.json](/en/settings) 或环境变量中添加 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 来启用。代理团队在会话恢复、任务协调和关闭行为方面存在[已知限制](#limitations)。
代理团队让你可以协调多个 Claude Code 实例协同工作。一个会话充当团队负责人，协调工作、分配任务和综合结果。队友独立工作，各自拥有自己的上下文窗口，并可以直接相互通信。
与 [subagents](/en/sub-agents) 不同，subagents 在单个会话内运行，只能向主代理汇报结果；而你也可以直接与个别队友交互，无需通过负责人。
代理团队需要 Claude Code v2.1.32 或更高版本。使用 `claude --version` 检查你的版本。
本页涵盖：
* [何时使用代理团队](#when-to-use-agent-teams)，包括最佳用例及与 subagents 的比较
* [启动团队](#start-your-first-agent-team)
* [控制队友](#control-your-agent-team)，包括显示模式、任务分配和委派
* [并行工作最佳实践](#best-practices)
## 何时使用代理团队
代理团队对于并行探索能带来真正价值的任务最为有效。参见[用例示例](#use-case-examples)了解完整场景。最强的用例包括：
* **研究和审查**：多个队友可以同时调查问题的不同方面，然后分享和互相质疑发现
* **新模块或功能**：队友可以各自负责独立的部分而不会互相冲突
* **使用竞争假设进行调试**：队友并行测试不同理论，更快地收敛到答案
* **跨层协调**：跨越前端、后端和测试的变更，每个由不同队友负责
代理团队会增加协调开销，使用的令牌远多于单个会话。当队友可以独立运作时效果最好。对于顺序任务、同文件编辑或有大量依赖的工作，单个会话或 [subagents](/en/sub-agents) 更有效。
### 与 subagents 比较
代理团队和 [subagents](/en/sub-agents) 都可以让你并行化工作，但它们的运作方式不同。根据你的工作者是否需要相互通信来选择：
| | Subagents | 代理团队 |
| :---------------- | :----------------------------------------------- | :-------------------------------------------------- |
| **上下文** | 独立上下文窗口；结果返回给调用者 | 独立上下文窗口；完全独立 |
| **通信** | 仅向主代理汇报结果 | 队友之间直接发送消息 |
| **协调** | 主代理管理所有工作 | 共享任务列表，自我协调 |
| **最适合** | 只需结果的聚焦任务 | 需要讨论和协作的复杂工作 |
| **令牌成本** | 较低：结果汇总回主上下文 | 较高：每个队友都是独立的 Claude 实例 |
当你需要快速、聚焦的工作者汇报结果时，使用 subagents。当队友需要分享发现、互相质疑并自行协调时，使用代理团队。
## 启用代理团队
代理团队默认禁用。通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 环境变量设置为 `1` 来启用，可以在 shell 环境中或通过 [settings.json](/en/settings) 设置：
```json settings.json theme={null}
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
```
## 启动你的第一个代理团队
启用代理团队后，用自然语言告诉 Claude 创建代理团队并描述任务和你想要的团队结构。Claude 会创建团队、生成队友，并根据你的提示协调工作。
这个例子效果很好，因为三个角色是独立的，可以无需等待彼此就探索问题：
```text theme={null}
我正在设计一个帮助开发者跟踪代码库中 TODO 注释的 CLI 工具。
创建一个代理团队从不同角度探索这个问题：一个队友负责用户体验，
一个负责技术架构，一个扮演反对者。
```
然后，Claude 会创建一个带有[共享任务列表](/en/interactive-mode#task-list)的团队，为每个视角生成队友，让他们探索问题，综合发现，并在完成时尝试[清理团队](#clean-up-the-team)。
负责人的终端列出所有队友及其工作内容。使用 Shift+Down 在队友之间切换并直接发送消息。在最后一个队友之后，Shift+Down 会回到负责人。
如果你想让每个队友在自己的分屏窗格中，请参见[选择显示模式](#choose-a-display-mode)。
## 控制你的代理团队
用自然语言告诉负责人你想要什么。它会根据你的指令处理团队协调、任务分配和委派。
### 选择显示模式
代理团队支持两种显示模式：
* **进程内**：所有队友在你的主终端内运行。使用 Shift+Down 在队友之间切换，输入文字直接发送消息。适用于任何终端，无需额外设置。
* **分屏窗格**：每个队友有自己的窗格。你可以同时看到所有人的输出，点击窗格直接交互。需要 tmux 或 iTerm2。
`tmux` 在某些操作系统上有已知限制，传统上在 macOS 上效果最佳。在 iTerm2 中使用 `tmux -CC` 是建议的 `tmux` 入门方式。
默认值为 `"auto"`，如果你已经在 tmux 会话中运行则使用分屏窗格，否则使用进程内模式。`"tmux"` 设置启用分屏窗格模式，并根据你的终端自动检测使用 tmux 还是 iTerm2。要覆盖设置，在 `~/.claude/settings.json` 中设置 [`teammateMode`](/en/settings#available-settings)：
```json theme={null}
{
"teammateMode": "in-process"
}
```
要为单个会话强制使用进程内模式，将其作为标志传递：
```bash theme={null}
claude --teammate-mode in-process
```
分屏窗格模式需要 [tmux](https://github.com/tmux/tmux/wiki) 或带有 [`it2` CLI](https://github.com/mkusaka/it2) 的 iTerm2。手动安装：
* **tmux**：通过系统包管理器安装。参见 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) 了解特定平台的说明。
* **iTerm2**：安装 [`it2` CLI](https://github.com/mkusaka/it2)，然后在 **iTerm2 → Settings → General → Magic → Enable Python API** 中启用 Python API。
### 指定队友和模型
Claude 根据你的任务决定生成多少队友，或者你可以精确指定你想要的：
```text theme={null}
创建一个有 4 个队友的团队来并行重构这些模块。
每个队友使用 Sonnet。
```
队友默认不继承负责人的 `/model` 选择。要更改提示未指定时使用的模型，在 `/config` 中设置**默认队友模型**。选择**默认（负责人的模型）**让队友跟随负责人的当前模型。
### 要求队友的计划审批
对于复杂或高风险任务，你可以要求队友在实施前先做计划。队友在只读计划模式下工作，直到负责人批准其方案：
```text theme={null}
生成一个架构师队友来重构认证模块。
在他们做任何更改之前要求计划审批。
```
当队友完成计划后，会向负责人发送计划审批请求。负责人审查计划并批准或拒绝并附上反馈。如果被拒绝，队友保持在计划模式，根据反馈修改并重新提交。一旦获批，队友退出计划模式开始实施。
负责人自主做出审批决定。要影响负责人的判断，在你的提示中给出标准，例如"只批准包含测试覆盖的计划"或"拒绝修改数据库 schema 的计划"。
### 直接与队友交谈
每个队友都是一个完整的独立 Claude Code 会话。你可以直接给任何队友发送消息，提供额外说明、提出后续问题或调整他们的方法。
* **进程内模式**：使用 Shift+Down 在队友之间切换，然后输入发送消息。按 Enter 查看队友的会话，然后按 Escape 中断他们当前的回合。按 Ctrl+T 切换任务列表。
* **分屏窗格模式**：点击队友的窗格直接与其会话交互。每个队友有自己的完整终端视图。
### 分配和认领任务
共享任务列表协调团队的工作。负责人创建任务，队友完成它们。任务有三种状态：待处理、进行中和已完成。任务也可以依赖其他任务：有未解决依赖的待处理任务在依赖完成前不能被认领。
负责人可以显式分配任务，或者队友可以自行认领：
* **负责人分配**：告诉负责人将哪个任务分配给哪个队友
* **自行认领**：完成任务后，队友自行拾取下一个未分配、未阻塞的任务
任务认领使用文件锁来防止多个队友同时尝试认领同一任务时的竞态条件。
### 关闭队友
要优雅地结束队友的会话：
```text theme={null}
请研究员队友关闭
```
负责人发送关闭请求。队友可以批准（优雅退出）或拒绝并附上解释。
### 清理团队
完成时，请负责人清理：
```text theme={null}
清理团队
```
这会移除共享的团队资源。当负责人运行清理时，会检查是否有活跃的队友，如果有仍在运行的则失败，因此请先关闭它们。
始终使用负责人来清理。队友不应运行清理，因为它们的团队上下文可能无法正确解析，可能导致资源处于不一致状态。
### 使用钩子强制质量门控
使用 [hooks](/en/hooks) 在队友完成工作或任务被创建或完成时强制执行规则：
* [`TeammateIdle`](/en/hooks#teammateidle)：在队友即将空闲时运行。以代码 2 退出发送反馈并让队友继续工作。
* [`TaskCreated`](/en/hooks#taskcreated)：在任务被创建时运行。以代码 2 退出阻止创建并发送反馈。
* [`TaskCompleted`](/en/hooks#taskcompleted)：在任务被标记完成时运行。以代码 2 退出阻止完成并发送反馈。
## 代理团队的工作原理
本节涵盖代理团队背后的架构和机制。如果你想开始使用它们，请参见上面的[控制你的代理团队](#control-your-agent-team)。
### Claude 如何启动代理团队
有两种方式启动代理团队：
* **你请求团队**：给 Claude 一个受益于并行工作的任务，并明确请求代理团队。Claude 根据你的指令创建团队。
* **Claude 建议团队**：如果 Claude 判定你的任务会从并行工作中受益，它可能会建议创建团队。你确认后才会继续。
在这两种情况下，你都保持控制。Claude 不会在未经你批准的情况下创建团队。
### 架构
代理团队由以下部分组成：
| 组件 | 角色 |
| :------------ | :----------------------------------------------------------------------------------------- |
| **团队负责人** | 创建团队、生成队友并协调工作的主 Claude Code 会话 |
| **队友** | 分别处理各自分配任务的独立 Claude Code 实例 |
| **任务列表** | 队友认领和完成的工作项共享列表 |
| **邮箱** | 代理之间通信的消息系统 |
参见[选择显示模式](#choose-a-display-mode)了解显示配置选项。队友消息会自动到达负责人。
系统自动管理任务依赖。当队友完成其他任务依赖的任务时，被阻塞的任务会自动解除阻塞，无需手动干预。
团队和任务存储在本地：
* **团队配置**：`~/.claude/teams/{team-name}/config.json`
* **任务列表**：`~/.claude/tasks/{team-name}/`
Claude Code 在你创建团队时自动生成这两个文件，并在队友加入、空闲或离开时更新它们。团队配置包含运行时状态，如会话 ID 和 tmux 窗格 ID，因此不要手动编辑或预先编写：你的更改会在下一次状态更新时被覆盖。
要定义可重用的队友角色，请改用 [subagent 定义](#use-subagent-definitions-for-teammates)。
团队配置包含一个 `members` 数组，其中每个队友有名称、代理 ID 和代理类型。队友可以读取此文件来发现其他团队成员。
没有项目级别的团队配置等价物。项目目录中类似 `.claude/teams/teams.json` 的文件不会被识别为配置；Claude 将其视为普通文件。
### 为队友使用 subagent 定义
在生成队友时，你可以从任何 [subagent scope](/en/sub-agents#choose-the-subagent-scope)（项目、用户、插件或 CLI 定义）引用一个 [subagent](/en/sub-agents) 类型。这让你可以定义一次角色，如安全审查员或测试运行器，并将其既作为委派的 subagent 又作为代理团队队友重用。
要使用 subagent 定义，在要求 Claude 生成队友时按名称提及它：
```text theme={null}
使用 security-reviewer 代理类型生成一个队友来审计认证模块。
```
队友遵循该定义的 `tools` 白名单和 `model`，定义的正文会附加到队友的系统提示中作为额外指令，而不是替换它。团队协调工具如 `SendMessage` 和任务管理工具对队友始终可用，即使 `tools` 限制了其他工具。
subagent 定义中的 `skills` 和 `mcpServers` frontmatter 字段在该定义作为队友运行时不会被应用。队友从你的项目和用户设置加载技能和 MCP 服务器，与常规会话相同。
### 权限
队友启动时继承负责人的权限设置。如果负责人使用 `--dangerously-skip-permissions` 运行，所有队友也是如此。生成后，你可以更改个别队友的模式，但不能在生成时设置每个队友的模式。
### 上下文和通信
每个队友有自己的上下文窗口。生成时，队友加载与常规会话相同的项目上下文：CLAUDE.md、MCP 服务器和技能。它还接收来自负责人的生成提示。负责人的对话历史不会传递过来。
**队友如何共享信息：**
* **自动消息传递**：队友发送消息时，会自动传递给收件人。负责人不需要轮询更新。
* **空闲通知**：队友完成并停止时，会自动通知负责人。
* **共享任务列表**：所有代理都可以看到任务状态并认领可用工作。
* **队友消息**：通过名称向特定队友发送消息。要联系所有人，请为每个收件人发送一条消息。
负责人在生成队友时为每个队友分配一个名称，任何队友都可以通过该名称向其他队友发送消息。要获得可在后续提示中引用的可预测名称，请在生成指令中告诉负责人如何称呼每个队友。
### 令牌使用
代理团队使用的令牌远多于单个会话。每个队友有自己的上下文窗口，令牌使用量随活跃队友数量线性增长。对于研究、审查和新功能工作，额外的令牌通常是值得的。对于常规任务，单个会话更具成本效益。参见[代理团队令牌成本](/en/costs#agent-team-token-costs)了解使用指南。
## 用例示例
这些示例展示了代理团队如何处理并行探索能增加价值的任务。
### 运行并行代码审查
单个审查者倾向于一次只关注一种类型的问题。将审查标准拆分为独立的领域意味着安全性、性能和测试覆盖都能同时得到彻底的关注。提示为每个队友分配不同的视角，使他们不会重叠：
```text theme={null}
创建一个代理团队来审查 PR #142。生成三个审查者：
- 一个专注于安全影响
- 一个检查性能影响
- 一个验证测试覆盖
让他们各自审查并报告发现。
```
每个审查者从同一个 PR 出发但应用不同的过滤器。负责人在他们完成后综合三个审查者的发现。
### 使用竞争假设进行调查
当根本原因不明确时，单个代理倾向于找到一个合理的解释就停止寻找。提示通过让队友明确对抗来对抗这一点：每个人的职责不仅是调查自己的理论，还要质疑其他人的理论。
```text theme={null}
用户报告应用在一条消息后退出而不是保持连接。
生成 5 个代理队友来调查不同假设。让他们互相交谈
尝试反驳彼此的理论，就像科学辩论一样。
将出现的共识更新到发现文档中。
```
辩论结构是这里的关键机制。顺序调查会受到锚定效应的影响：一旦探索了一个理论，后续调查就会偏向它。
多个独立调查员积极尝试反驳彼此，存活下来的理论更有可能是真正的根本原因。
## 最佳实践
### 给队友足够的上下文
队友自动加载项目上下文，包括 CLAUDE.md、MCP 服务器和技能，但它们不继承负责人的对话历史。参见[上下文和通信](#context-and-communication)了解详情。在生成提示中包含特定任务的细节：
```text theme={null}
生成一个安全审查员队友，提示为："审查 src/auth/ 下的
认证模块是否存在安全漏洞。重点关注令牌处理、会话
管理和输入验证。应用使用存储在 httpOnly cookie 中的
JWT 令牌。报告任何问题并附上严重性评级。"
```
### 选择适当的团队规模
对队友数量没有硬性限制，但存在实际约束：
* **令牌成本线性增长**：每个队友有自己的上下文窗口并独立消耗令牌。参见[代理团队令牌成本](/en/costs#agent-team-token-costs)了解详情。
* **协调开销增加**：更多队友意味着更多通信、任务协调和潜在冲突
* **收益递减**：超过某个点后，额外的队友不会成比例地加速工作
大多数工作流从 3-5 个队友开始。这在并行工作和可管理的协调之间取得平衡。本指南中的示例使用 3-5 个队友，因为这个范围在不同类型的任务中效果良好。
每个队友有 5-6 个[任务](/en/agent-teams#architecture)可以保持每个人的生产力而不会过度上下文切换。如果你有 15 个独立任务，3 个队友是一个好的起点。
只有当工作真正受益于队友同时工作时才扩大规模。三个专注的队友往往优于五个分散的队友。
### 适当地划分任务大小
* **太小**：协调开销超过收益
* **太大**：队友工作时间太长而没有检查，增加浪费工作的风险
* **刚好**：产生明确交付物的独立单元，如一个函数、一个测试文件或一次审查
负责人将工作分解为任务并自动分配给队友。如果没有创建足够的任务，要求它将工作拆分为更小的部分。每个队友有 5-6 个任务可以保持每个人的生产力，并让负责人在有人卡住时重新分配工作。
### 等待队友完成
有时负责人会自己开始实施任务而不是等待队友。如果你注意到这一点：
```text theme={null}
在继续之前等待队友完成他们的任务
```
### 从研究和审查开始
如果你是代理团队的新手，从有明确边界且不需要编写代码的任务开始：审查 PR、研究库或调查 bug。这些任务展示了并行探索的价值，而没有并行实施带来的协调挑战。
### 避免文件冲突
两个队友编辑同一文件会导致覆盖。拆分工作，让每个队友负责不同的文件集。
### 监控和引导
检查队友的进度，重定向不起作用的方法，并在发现到来时进行综合。让团队无人看管运行太久会增加浪费工作的风险。
## 故障排除
### 队友未出现
如果你要求 Claude 创建团队后队友未出现：
* 在进程内模式下，队友可能已在运行但不可见。按 Shift+Down 在活跃队友之间切换。
* 检查你给 Claude 的任务是否足够复杂以值得一个团队。Claude 根据任务决定是否生成队友。
* 如果你明确请求了分屏窗格，确保 tmux 已安装并在你的 PATH 中：
```bash theme={null}
which tmux
```
* 对于 iTerm2，验证 `it2` CLI 已安装且 Python API 在 iTerm2 偏好设置中已启用。
### 权限提示过多
队友的权限请求会上报给负责人，这可能会造成摩擦。在生成队友之前，在你的[权限设置](/en/permissions)中预先批准常见操作以减少中断。
### 队友因错误停止
队友可能在遇到错误后停止而不是恢复。在进程内模式下使用 Shift+Down 或在分屏模式下点击窗格检查他们的输出，然后：
* 直接给他们额外的指令
* 生成替代队友继续工作
### 负责人在工作完成前关闭
负责人可能在所有任务实际完成之前就判定团队已完成。如果发生这种情况，告诉它继续。如果它开始自己做工作而不是委派，你也可以告诉负责人在继续之前等待队友完成。
### 孤立的 tmux 会话
如果团队结束后 tmux 会话仍然存在，它可能没有被完全清理。列出会话并杀死团队创建的那个：
```bash theme={null}
tmux ls
tmux kill-session -t
```
## 限制
代理团队是实验性的。当前需要注意的限制：
* **无法恢复进程内队友的会话**：`/resume` 和 `/rewind` 不会恢复进程内队友。恢复会话后，负责人可能会尝试向不再存在的队友发送消息。如果发生这种情况，告诉负责人生成新队友。
* **任务状态可能滞后**：队友有时未能将任务标记为已完成，这会阻塞依赖任务。如果任务看起来卡住了，检查工作是否实际完成并手动更新任务状态或告诉负责人督促队友。
* **关闭可能很慢**：队友在关闭前完成当前请求或工具调用，这可能需要时间。
* **一次只能有一个团队**：负责人只能管理一个团队。在创建新团队之前清理当前团队。
* **不支持嵌套团队**：队友不能生成自己的团队或队友。只有负责人可以管理团队。
* **负责人是固定的**：创建团队的会话在其生命周期内都是负责人。你不能将队友提升为负责人或转移领导权。
* **权限在生成时设置**：所有队友启动时继承负责人的权限模式。你可以在生成后更改个别队友的模式，但不能在生成时设置每个队友的模式。
* **分屏窗格需要 tmux 或 iTerm2**：默认的进程内模式适用于任何终端。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分屏窗格模式。
**`CLAUDE.md` 正常工作**：队友从其工作目录读取 `CLAUDE.md` 文件。使用此功能为所有队友提供特定项目的指导。
## 后续步骤
探索并行工作和委派的相关方法：
* **轻量级委派**：[subagents](/en/sub-agents) 在你的会话内生成辅助代理进行研究或验证，更适合不需要代理间协调的任务
* **手动并行会话**：[Git worktrees](/en/worktrees) 让你自己运行多个 Claude Code 会话，无需自动团队协调
* **比较方法**：参见 [subagent 与代理团队](/en/features-overview#compare-similar-features)比较，了解逐项对比