Claude Code 一直有 Subagents——在单个会话内派出辅助 Agent 去读文件或做验证，结果汇报回主 Agent。但 Subagents 有个根本限制：它们只能向上汇报，彼此之间没法直接沟通。
Agent Teams（v2.1.32 起支持）拆掉了这道墙。它是一组完全独立的 Claude Code 会话，共用一份任务列表，可以互相发消息、共享发现，协作方式更接近真实的开发团队。
目前是实验性功能，默认关闭。
Subagents vs Agent Teams：选哪个
两者都能并行处理工作，核心区别是成员之间需不需要互相通信：
| Subagents | Agent Teams | |
|---|---|---|
| 上下文 | 独立上下文，结果汇报给调用方 | 独立上下文，完全独立 |
| 通信 | 只向主 Agent 汇报 | Teammates 可以直接互发消息 |
| 协调 | 主 Agent 管理所有工作 | 共享任务列表，自我协调 |
| 适合 | 结果导向的专注任务 | 需要讨论和协作的复杂工作 |
| Token 成本 | 较低 | 较高（每个 Teammate 是独立实例） |
如果你的工作者只需要报结果，用 Subagents；如果它们需要共享发现、相互质疑、动态协调，用 Agent Teams。
开启方式
在 settings.json 里加一行环境变量：
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
或者直接在 shell 里 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。
需要 Claude Code v2.1.32 或更高版本（claude --version 确认）。
架构
一个 Agent Team 由四个组件构成：
| 组件 | 作用 |
|---|---|
| Team Lead | 创建团队、派生 Teammate、分配任务、综合结果 |
| Teammates | 各自在独立上下文窗口里工作的 Claude Code 实例 |
| Task List | 共享任务列表，Teammates 认领和完成任务 |
| Mailbox | Agent 之间的消息系统，支持直接通信 |
任务有三个状态：pending、in progress、completed，并支持依赖关系——一个任务完成后，依赖它的任务自动解锁。
配置文件存在本地：
- 团队配置：
~/.claude/teams/{team-name}/config.json - 任务列表：
~/.claude/tasks/{team-name}/
不要手动编辑这些文件，每次状态更新会覆盖。
什么场景最适合
Agent Teams 在并行探索能带来真实价值的任务上效果最好：
研究与 Review：多个 Teammate 同时调查问题的不同方面，再共享发现、相互挑战。
新模块或特性：每个 Teammate 负责一个独立的部分，互不干扰。
带竞争假设的调试：多个 Teammate 各自测试不同的根因理论，并行排查，避免"找到一个就停止探索"的锚定效应。
跨层改动：前端、后端、测试各由不同 Teammate 负责，Lead 统筹。
不适合的场景：顺序任务、同一文件的多处编辑、依赖关系多的工作——这类情况用单会话或 Subagents 更高效，Agent Teams 的协调开销会大于收益。
启动一个 Team
告诉 Claude 你要创建一个 Agent Team，描述任务和你希望的团队结构：
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.
Claude 会创建团队、生成共享任务列表、派生 Teammate，等它们各自探索完再综合结果。
界面与操作
显示模式
两种模式：
- In-process（默认）：所有 Teammate 在主终端内运行，按
Shift+Down循环切换，直接输入给当前 Teammate 发消息。任何终端都支持。 - Split panes：每个 Teammate 占一个独立分屏，可以同时看到所有人的输出，点击分屏直接交互。需要 tmux 或 iTerm2。
在 settings.json 里可以设置默认模式：
{
"teammateMode": "in-process"
}
控制 Teammate
指定成员和模型：
Create a team with 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.
Teammate 进入只读的 plan mode，Lead 审批后才开始修改。
直接和某个 Teammate 说话：in-process 模式按 Shift+Down 切到它；split-pane 模式点击对应分屏。
任务分配
Lead 可以显式分配，Teammate 也可以自认领——完成一个任务后自动拾取下一个未分配的任务。用文件锁防止多人同时认领同一任务的竞争条件。
Hooks
可以用 Hooks 在任务生命周期节点执行脚本：
TeammateIdle：Teammate 即将空闲时触发，退出码 2 可阻止它空闲并发回反馈TaskCreated：任务创建时触发，退出码 2 阻止创建TaskCompleted：任务标记完成时触发，退出码 2 阻止完成
典型模式
并行 Code Review
把 Review 维度拆给不同 Teammate，确保安全、性能、测试覆盖率同时得到认真审查：
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
竞争假设调试
让 Teammate 不只调查自己的理论，还要主动推翻对方的——这个"辩论"结构能大幅减少锚定效应：
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.
最佳实践
给 Teammate 足够的上下文：Teammate 会自动加载 CLAUDE.md，但不继承 Lead 的对话历史。在 spawn 提示里写清楚任务所需的关键背景。
合理控制团队规模：从 3–5 个 Teammate 开始，每人 5–6 个任务。额外的 Teammate 不总是带来同比提速，协调开销会增加。
拆好任务粒度：太小——协调开销大于收益；太大——Teammate 跑太久没有检查点，浪费上下文。理想任务是能产出明确交付物的自包含单元（一个函数、一个测试文件、一份 review）。
避免文件冲突：两个 Teammate 编辑同一文件会互相覆盖。让每个 Teammate 负责不同的文件集。
新手先从 Research 类任务起步：review PR、调研一个库、排查一个 bug——边界清晰、不需要写代码，是体验 Agent Teams 价值的最低风险入口。
已知限制
- 不支持 Session 恢复：
/resume和/rewind不还原 in-process 的 Teammate - 任务状态可能滞后：Teammate 有时不会标记任务完成，导致依赖任务被阻塞
- 一次只能有一个 Team：清理完当前团队才能创建新的
- 不支持嵌套 Team：Teammate 不能再派出自己的 Team
- Split panes 不支持 VS Code 内置终端、Windows Terminal、Ghostty
本文改写自 Claude Code 官方文档 Orchestrate teams of Claude Code sessions，内容以官方文档为准。
关于
关注我获取更多资讯
