Claude Code Agent Teams

概述

Agent Teams 让多个独立的 Claude Code 会话组成一个协作团队。主会话担任 team lead，负责拆分任务、调度 teammate 和汇总结果；每个 teammate 拥有独立上下文，可以领取共享任务，也可以直接给其他成员发消息。

截至 2026 年 8 月 19 日，这仍是默认关闭的实验功能。它适合可以并行推进、成员之间又需要交换信息的复杂任务，例如多角度代码审查、并行验证故障假设和跨前后端功能开发。顺序依赖强、集中修改同一文件的任务，继续使用单会话或 subagent 更稳妥。

工作架构

一个 Agent Team 包含四个组成部分：

team lead：创建 teammate、分配工作并整合产出
teammate：独立运行的 Claude Code 会话
task list：记录待处理、进行中和已完成的共享任务
mailbox：在会话之间传递消息

Claude Code 会把团队运行状态保存在本机：

团队配置：~/.claude/teams/{team-name}/config.json
任务列表：~/.claude/tasks/{team-name}/
成员邮箱：~/.claude/teams/{team-name}/inboxes/{agent-name}.json

这些是运行时文件，不应手工创建或修改。当前版本在会话启动时准备团队环境，并在会话退出时清理团队配置；任务记录会按 Claude Code 的会话保留规则继续保存。

上下文传递

teammate 启动时会加载常规项目上下文，包括 CLAUDE.md、MCP Server 和 skills，也会收到 lead 提供的 spawn prompt。lead 的完整对话历史不会复制过去。

这条边界直接影响任务质量。只说“检查登录模块”通常不够，spawn prompt 还应包含目录、技术背景、检查范围和预期产物，例如：

text

启动一个 security-reviewer teammate，检查 src/auth/ 的令牌处理、
会话管理和输入校验。项目使用保存在 HttpOnly Cookie 中的 JWT。
按严重程度报告问题，并给出文件位置和判断依据，不要修改代码。

共享任务列表负责同步工作状态和依赖关系。一个任务完成后，依赖它的任务会自动解除阻塞；多个成员同时领取任务时，Claude Code 使用文件锁避免重复领取。

对比 Subagent

Agent Teams 和 subagent 都会创建独立上下文，但通信模型不同。

对比项	Subagent	Agent Teams
上下文	独立上下文，结果返回调用者	每个 teammate 都是完整独立会话
通信	只向主会话返回结果	teammate 可以互相发消息
协调	主会话集中调度	共享任务列表配合成员自协调
交互	主要关心最终结果	可以直接查看和指导单个 teammate
成本	相对较低	多个会话分别消耗 token
适合任务	一次性调研、搜索、验证	需要讨论、质疑和持续协作的任务

只需要把日志分析或资料查询移出主上下文时，subagent 已经足够。多个调查者需要互相反驳假设，或者几个模块的负责人需要持续同步接口时，Agent Teams 才能发挥通信能力。

启用功能

在 ~/.claude/settings.json 中设置实验变量：

json

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

也可以在 shell 环境中设置：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Agent Teams 只在交互会话中创建 teammate。使用 claude -p 的非交互模式和 Agent SDK 时，即使打开实验变量，命名 agent 仍按普通 subagent 运行。

启用后，用自然语言描述团队结构和任务即可：

text

为当前分支创建一个 Agent Team，并启动三个 teammate：

- security-reviewer 检查权限、输入校验和敏感信息泄露
- performance-reviewer 检查慢查询、重复计算和不必要的网络请求
- regression-reviewer 检查行为回归和缺失的测试覆盖

三人先独立审查，再互相质疑结论。等待全部完成后，按严重程度汇总，
每条问题必须包含文件位置和依据，不要修改代码。

明确角色、文件范围和最终产物，可以减少多人做同一件事的情况。需要控制成本时，也可以在 prompt 中指定 teammate 数量和模型。

终端交互

Agent Teams 支持两种显示模式：

in-process：所有成员运行在主终端中，通过 agent panel 选择成员
split panes：每个成员使用独立面板，需要 tmux 或带 it2 CLI 的 iTerm2

默认的 auto 模式会根据终端环境选择。也可以在 ~/.claude/settings.json 中固定：

json

{
  "teammateMode": "in-process"
}

单次启动时可以覆盖：

claude --teammate-mode auto

在 in-process 模式下，通过 agent panel 的上下方向键选择成员，按 Enter 打开其 transcript 并直接发送消息，按 Escape 中断当前 turn。成员空闲后仍保持可寻址状态，后续消息可以让它继续工作。

任务设计

Agent Teams 的收益来自独立工作流同时推进，不是单纯增加会话数量。下面几类任务更合适：

研究与审查：不同成员分别检查安全、性能和可维护性
竞争性假设：每个成员验证一种故障原因，并主动反驳其他结论
独立模块开发：按目录或组件划分文件所有权
跨层协作：前端、服务端和数据层分别处理各自边界

拆分任务时应满足三个条件：

每项工作有明确输入和可检查的产物
多数时间无需等待其他成员
不同成员尽量不修改同一批文件

Agent Teams 不会自动为 teammate 创建 Git worktree。多个成员直接修改同一文件时，后写入的内容可能覆盖先前改动。并行实现应按目录或文件划分所有权；确实需要重叠修改时，先让 teammate 做只读分析，再由 lead 统一落地。

权限与约束

teammate 启动时继承 lead 的权限设置。成员产生的权限请求会显示在 lead 会话中，用户仍是批准操作的人；一个 agent 发来的消息不能替用户批准权限，也不能绕过已经拒绝的操作。

复杂或高风险改动可以要求 teammate 先进入只读 plan mode。它提交计划后，由 lead 按 prompt 中的验收标准批准或驳回，批准后才开始实现。计划批准只控制实现节奏，不会替代文件系统、网络和命令执行权限。

还可以用 hooks 设置质量门槛：

TaskCreated：任务创建时校验描述和范围
TaskCompleted：任务完成前执行检查，不通过则阻止完成
TeammateIdle：成员即将空闲时检查是否还有遗漏

当前限制

实验阶段需要留意以下边界：

in-process teammate 无法随 /resume 或 /rewind 恢复
一个会话只有一个 team，不能再创建独立的命名团队
teammate 不能继续创建 teammate，lead 始终固定
任务状态可能滞后，已完成工作偶尔仍显示为阻塞
teammate 会等当前请求或工具调用结束后再关闭
split panes 不支持 VS Code 集成终端、Windows Terminal 和 Ghostty
token 消耗随活跃 teammate 数量增加，协调成本也会同步上升

Agent Teams 更适合从并行审查和故障调查开始。此类任务主要读取信息，成员之间容易划清边界；等任务拆分方式稳定后，再尝试多人并行修改代码。

Claude Code Agent Teams ​

概述 ​

工作架构 ​

上下文传递 ​

对比 Subagent ​

启用功能 ​

终端交互 ​

任务设计 ​

权限与约束 ​

当前限制 ​

参考 ​