Claude Code 支持多会话编排，团队协作焕新

何时使用 agent 团队

研究和审查：多个队友可以同时调查问题的不同方面，然后分享和相互质疑各自的发现

新模块或功能：队友可以各自拥有一个独立的部分，不会互相干扰

使用竞争假设进行调试：队友并行测试不同的理论，更快地收敛到答案

跨层协调：跨越前端、后端和测试的变更，由不同的队友各自负责

与 subagent 对比

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

启动你的第一个 agent 团队

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

上下箭头：选择一个队友

回车：打开选中队友的对话记录并直接给其发送消息

Escape：中断选中队友的当前任务

控制你的 agent 团队

选择显示模式

进程内（In-process）：所有队友在你的主终端内运行。在 agent 面板中使用上下箭头键选择队友，然后按回车查看和输入消息。在任何终端都可用，无需额外设置。

分割窗格（Split panes）：每个队友有自己的窗格。你可以同时看到所有人的输出，点击窗格可直接交互。需要 tmux 或 iTerm2。

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

tmux：通过系统包管理器安装。详见 tmux wiki 的平台特定说明。

iTerm2：安装 it2 CLI，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API。

指定队友和模型

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

要求队友获得计划批准

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

直接与队友交谈

进程内模式：使用 agent 面板中的上下箭头键选择队友，然后按回车查看其会话并输入消息。在选中的队友上按 x 停止其工作。按 Ctrl+T 切换任务列表。

分割窗格模式：点击队友的窗格可直接与其会话交互。每个队友都有自己的完整终端视图。

分配和认领任务

主导分配：告诉主导应该把哪个任务分配给哪个队友

自主认领：完成一个任务后，队友会自动选择下一个未分配、未被阻止的任务

Ask the researcher teammate to shut down

使用 hook 强制质量控制

TeammateIdle：在队友即将空闲时运行。以代码 2 退出以发送反馈并让队友继续工作。

TaskCreated：在创建任务时运行。以代码 2 退出以阻止创建并发送反馈。

TaskCompleted：在标记任务完成时运行。以代码 2 退出以阻止完成并发送反馈。

Agent 团队如何工作

Claude 如何启动 agent 团队

你请求队友：给 Claude 一个受益于并行工作的任务，明确要求队友。Claude 会根据你的指示生成它们。

Claude 提议队友：如果 Claude 判断你的任务会受益于并行工作，它可能会建议生成队友。你确认后它才会继续。

团队配置：~/.claude/teams/{team-name}/config.json

任务列表：~/.claude/tasks/{team-name}/

使用 subagent 定义作为队友

Spawn a teammate using the security-reviewer agent type to audit the auth module.

上下文和通信

自动消息传递：队友发送消息时，消息会自动传递给接收者。主导不需要轮询更新。

空闲通知：当队友完成并停止时，它会自动通知主导。从 v2.1.198 开始，因 API 错误而结束的队友会通知主导它失败了并包含错误文本，而不是表现为正常完成。

共享任务列表：所有 agent 都可以看到任务状态并认领可用工作。

队友消息：按名称向一个特定队友发送消息。要联系所有人，需要为每个接收者发送一条消息。

运行并行代码审查

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

使用竞争假设进行调查

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

为队友提供充足的上下文

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

选择适当的团队规模

代币成本线性扩展：每个队友有自己的上下文窗口，独立消耗代币。详见 agent 团队代币成本。

协调开销增加：更多队友意味着更多通信、任务协调和潜在冲突。

收益递减：超过一定数量后，额外队友无法按比例加快工作。

适当规划任务大小

太小：协调开销超过受益

太大：队友长时间工作而无检查，增加浪费工作的风险

刚好合适：自包含的单位，可产生明确的交付物，如一个函数、一个测试文件或一次审查

等待队友完成

Wait for your teammates to complete their tasks before proceeding

从研究和审查开始

避免文件冲突

队友未出现

在进程内模式下，队友会在提示输入下方的 agent 面板中出现。使用上下箭头键选择一个，然后按回车查看。

坐着空闲后消失的队友行已被隐藏，不是停止了。空闲行在整个面板空闲 30 秒后隐藏，会在队友下一轮时重新出现。当超过三个队友空闲时，其多余行会折叠成一个「N 个空闲 agent」行，按回车可展开。通过名称向队友发送消息可让隐藏行重新出现。

检查你给 Claude 的任务是否足够复杂以保证有一个团队。Claude 会根据任务决定是否生成队友。

如果你明确要求分割窗格，确保 tmux 已安装且在你的 PATH 中可用：

which tmux

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

队友因错误停止

直接给它们额外指示

生成替代队友继续工作

主导在工作完成前关闭

孤立的 tmux 会话

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

进程内队友无会话恢复：/resume 和 /rewind 不会恢复进程内队友。恢复会话后，主导可能尝试给不再存在的队友发消息。如果发生这种情况，告诉主导生成新队友。

任务状态可能滞后：队友有时无法标记任务为已完成，这会阻止依赖的任务。如果任务似乎卡住了，检查工作是否实际完成，然后手动更新任务状态或告诉主导催促队友。

关闭可能很慢：队友在关闭前会完成其当前请求或工具调用，这可能需要时间。

每个会话一个团队：一个会话恰好有一个团队，作用于该会话。你无法创建额外的命名团队或跨会话共享团队。

无嵌套团队：队友无法生成自己的队友。只有主导可以管理团队。

进程内队友的后台 subagent：进程内队友自己的 subagent 在前台运行。要求一个后台的，无论是使用 run_in_background 还是设置 background: true 的 subagent 定义，都会返回错误，因为队友的后台工作无法超越主导进程的生命周期。从主对话启动的 subagent 遵循后台默认。

主导是固定的：主会话在其生命周期内是其团队的主导。你无法将队友晋升为主导或转移领导权。

权限在生成时设置：所有队友在启动时采用主导的权限模式。生成后你可以更改个别队友的模式，但无法在生成时设置每队友权限。

分割窗格需要 tmux 或 iTerm2：默认的进程内模式在任何终端都可用。VS Code 集成终端、Windows Terminal 或 Ghostty 中不支持分割窗格模式。

轻量级委托：subagent 在你的会话内生成助手 agent 进行研究或验证，更适合不需要 agent 间协调的任务

手动并行会话：Git worktree 允许你在没有自动化团队协调的情况下自己运行多个 Claude Code 会话

比较方法：详见 subagent vs agent 团队对比以了解并排对比