Claude Code Agent Teams 指南

Agent Teams 让多个 Claude Code 实例并行工作并通过共享任务列表相互协调。与 subagents 不同，agent teams 中的队友可以直接相互通信、协作和分享发现，适合需要团队协作的复杂任务。

本文将详细介绍 Agent Teams 的启用方式、使用方法、最佳实践以及与 Subagents 的区别。

一、Agent Teams 概述

1.1 什么是 Agent Teams

Agent Teams 是一组并行工作的 Claude Code 实例，通过共享任务列表协调工作。每个队友都是完整的、独立的 Claude Code 会话，拥有自己的 context window。

核心组件：

组件	角色
Team Lead	创建团队、生成队友并协调工作的主 Claude Code 会话
Teammates	各自处理分配任务的独立 Claude Code 实例
Task List	队友认领和完成的共享工作项列表
Mailbox	代理之间通信的消息系统

1.2 与 Subagents 的区别

Agent Teams 和 Subagents 都支持并行工作，但运作方式不同：

特性	Subagents	Agent Teams
Context	自己的 context window；结果返回给调用者	自己的 context window；完全独立
通信	仅向主代理报告结果	队友直接相互发送消息
协调	主代理管理所有工作	共享任务列表，自我协调
最适合	只有结果重要的专注任务	需要讨论和协作的复杂工作
令牌成本	较低：结果汇总回主 context	较高：每个队友是独立的 Claude 实例

架构对比图：

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e1f5fe', 'primaryTextColor': '#01579b', 'primaryBorderColor': '#0288d1', 'lineColor': '#0288d1', 'secondaryColor': '#fff3e0', 'tertiaryColor': '#e8f5e9'}}}%%

flowchart TB
    subgraph Subagents["Subagents 架构"]
        direction TB
        MA1["Main Agent"]
        SA1["Subagent 1"]
        SA2["Subagent 2"]
        SA3["Subagent 3"]
        
        MA1 -->|"委托"| SA1
        MA1 -->|"委托"| SA2
        MA1 -->|"委托"| SA3
        SA1 -.->|"结果返回"| MA1
        SA2 -.->|"结果返回"| MA1
        SA3 -.->|"结果返回"| MA1
    end

    subgraph AgentTeams["Agent Teams 架构"]
        direction TB
        TL["Team Lead"]
        T1["Teammate 1"]
        T2["Teammate 2"]
        T3["Teammate 3"]
        TLB[("共享 Task List")]
        
        TL -->|"创建团队"| T1
        TL -->|"创建团队"| T2
        TL -->|"创建团队"| T3
        
        T1 <-.->|"直接通信"| T2
        T2 <-.->|"直接通信"| T3
        T1 <-.->|"直接通信"| T3
        
        T1 <--> TLB
        T2 <--> TLB
        T3 <--> TLB
    end

1.3 最佳用例

Agent Teams 最适合并行探索能增加真实价值的任务：

• 研究和审查：多个队友同时调查问题的不同方面，然后分享和质疑彼此的发现
• 新模块或功能：队友各自拥有独立的部分，不会相互干扰
• 使用竞争假设进行调试：队友并行测试不同的理论，更快收敛到答案
• 跨层协调：跨越前端、后端和测试的更改，每个由不同的队友负责

---

二、启用 Agent Teams

2.1 启用实验性功能

Agent Teams 默认禁用，需要通过环境变量启用：

方式一：设置环境变量

# Linux/macOS
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Windows PowerShell
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方式二：在 settings.json 中配置

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

---

三、启动与控制 Agent Team

3.1 启动第一个 Agent Team

启用后，用自然语言告诉 Claude 创建团队：

Create an agent team to review this PR. One teammate should focus on
security issues, another on performance, and a third on test coverage.

这个例子效果很好，因为三个角色是独立的，可以并行探索问题。

3.2 选择显示模式

Agent Teams 支持两种显示模式：

模式	说明	适用场景
In-process	所有队友在主终端内运行	无需额外设置，任何终端都可用
Split panes	每个队友获得自己的窗格	需要同时看到所有人的输出

配置显示模式：

// settings.json
{
  "teammateMode": "auto"    // 自动选择：tmux 会话中用分割窗格，否则用 in-process
  // 或
  "teammateMode": "tmux"   // 强制使用分割窗格（需要 tmux 或 iTerm2）
  // 或
  "teammateMode": "in-process"  // 强制使用 in-process 模式
}

In-process 模式操作：

• Shift+Down：循环浏览队友
• Enter：查看队友会话
• Escape：中断队友当前轮次
• Ctrl+T：切换任务列表

Split-pane 模式要求：

• tmux：通过系统包管理器安装
• iTerm2：安装 it2 CLI，启用 iTerm2 → Settings → General → Magic → Enable Python API

3.3 指定队友和模型

可以明确指定团队结构：

Create a team with 3 teammates:
- A security reviewer using Opus
- A performance analyzer using Sonnet
- A test coverage checker using Haiku

3.4 要求计划批准

对于复杂或有风险的任务，要求队友在实施前进行规划：

Create a team to refactor the authentication system. Each teammate
should plan their approach first and wait for approval before
implementing changes.

队友在只读计划模式下工作，直到负责人批准。

3.5 直接与队友交谈

每个队友都是完整的独立会话：

• In-process 模式：用 Shift+Down 循环到队友，然后输入消息
• Split-pane 模式：点击队友窗格直接交互

3.6 任务分配与认领

共享任务列表协调整个团队：

任务状态：

• 待处理（Pending）
• 进行中（In Progress）
• 已完成（Completed）

任务依赖：
具有未解决依赖关系的待处理任务在这些依赖关系完成之前无法被认领。

分配方式：

• 负责人分配：告诉负责人将哪个任务分配给哪个队友
• 自我认领：完成任务后，队友自己选择下一个未分配的任务

3.7 关闭队友与清理团队

关闭特定队友：

Close the security-reviewer teammate

清理整个团队：

Clean up the team

3.8 使用 Hooks 强制质量门

// settings.json
{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "scripts/check-work-quality.sh" }]
      }
    ],
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "scripts/validate-completion.sh" }]
      }
    ]
  }
}

• TeammateIdle：队友即将空闲时运行。以代码 2 退出可发送反馈并保持队友工作
• TaskCompleted：任务被标记完成时运行。以代码 2 退出可阻止完成并发送反馈

---

四、Agent Teams 工作原理

4.1 启动方式

方式一：你请求一个团队
给 Claude 一个受益于并行工作的任务，并明确要求创建 agent team。

方式二：Claude 提议一个团队
如果 Claude 确定你的任务将受益于并行工作，它可能会建议创建一个团队，你在继续之前确认。

4.2 文件存储

文件	位置
Team config	~/.claude/teams/{team-name}/config.json
Task list	~/.claude/tasks/{team-name}/

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

4.3 权限

队友从负责人的权限设置开始。如果负责人使用 --dangerously-skip-permissions 运行，所有队友也会这样做。

生成后可以更改个别队友模式，但在生成时无法设置每个队友的模式。

4.4 Context 和通信

Context 加载：
队友生成时加载与常规会话相同的项目 context：

• CLAUDE.md
• MCP servers
• Skills
• 来自负责人的生成提示

注意：负责人的对话历史不会继承。

通信机制：

• 自动消息传递：消息自动传递给收件人，负责人不需要轮询更新
• 空闲通知：队友完成并停止时，自动通知负责人
• 共享任务列表：所有代理可看到任务状态并认领工作

消息类型：

• message：向特定队友发送消息
• broadcast：同时发送给所有队友（谨慎使用，成本随团队规模增加）

4.5 令牌使用

Agent Teams 使用明显更多的令牌。每个队友有自己的 context window，令牌使用量随活跃队友数量增加。

对于研究、审查和新功能工作，额外的令牌通常是值得的。对于日常任务，单个会话更具成本效益。

---

五、用例示例

5.1 并行代码审查

单个审查者往往一次只关注一种类型的问题。将审查标准分解为独立的域：

Create an agent team to review PR #42:
- Teammate 1: Focus exclusively on security vulnerabilities
- Teammate 2: Focus on performance issues and optimization opportunities
- Teammate 3: Focus on test coverage and test quality

Each teammate should review independently, then share findings
and critique each other's conclusions.

5.2 使用竞争假设进行调查

当根本原因不清楚时，让队友并行测试不同理论：

Create an agent team to investigate why users are experiencing
slow load times. Each teammate should pursue a different hypothesis:

- Teammate 1: Investigate database query performance
- Teammate 2: Investigate network latency and CDN issues
- Teammate 3: Investigate client-side rendering performance

Work in parallel, then share findings. Each teammate should also
try to disprove the others' hypotheses.

5.3 跨层功能开发

Create an agent team to implement the user profile feature:
- Teammate 1: Backend API endpoints and database schema
- Teammate 2: Frontend components and UI
- Teammate 3: Integration tests and documentation

Coordinate on the API contract first, then work in parallel.

---

六、最佳实践

6.1 给队友足够的 Context

队友不继承负责人的对话历史。在生成提示中包含特定于任务的详情：

Create a team to implement the payment flow.
Context: We're using Stripe API v2024, the checkout happens
in /src/checkout/, and we need to support both card and
bank transfer payments.

6.2 选择适当的团队规模

规模	适用场景
2-3 队友	大多数任务的最佳规模
4-5 队友	大型、复杂的任务
6+ 队友	罕见，收益递减明显

约束因素：

• 令牌成本线性增加
• 协调开销增加
• 收益递减

6.3 适当调整任务大小

大小	问题
太小	协调开销超过收益
太大	队友工作太长时间不检查，增加浪费风险
恰到好处	自包含的单位，产生清晰的可交付成果

6.4 等待队友完成

有时负责人开始自己实施任务而不是等待队友：

Wait for all teammates to finish their tasks before continuing.
Don't start implementing anything yourself.

6.5 从研究和审查开始

新手建议从不需要编写代码的任务开始：

• 审查 PR
• 研究库
• 调查错误

这些任务展示并行探索的价值，没有并行实施的协调挑战。

6.6 避免文件冲突

两个队友编辑同一文件会导致覆盖。分解工作使每个队友拥有不同的文件集：

Assign distinct file sets to each teammate:
- Teammate 1: src/api/* only
- Teammate 2: src/components/* only
- Teammate 3: tests/* only

6.7 监控和指导

检查队友进度，重定向不起作用的方法，综合发现。让团队无人值守运行太长时间增加浪费风险。

---

七、故障排除

7.1 队友未出现

可能原因和解决方案：

问题	解决方案
In-process 模式中不可见	按 Shift+Down 循环浏览活跃队友
任务不够复杂	确保任务足够复杂以保证团队
tmux 未安装（分割模式）	安装 tmux 并确保在 PATH 中
iTerm2 Python API 未启用	启用 iTerm2 → Settings → General → Magic → Enable Python API

7.2 过多权限提示

队友权限请求会传递到负责人。预批准常见操作减少中断：

// settings.json
{
  "permissions": {
    "allow": ["Read(**)", "Bash(npm run:*)", "Bash(git status:*)"]
  }
}

7.3 队友在错误时停止

使用 Shift+Down（in-process）或点击窗格（分割模式）检查输出：

• 直接给予额外指示
• 生成替代队友继续工作

7.4 负责人过早关闭

告诉负责人继续：

Continue. Wait for all teammates to complete before closing the team.

7.5 孤立的 tmux 会话

列出并杀死由团队创建的会话：

tmux list-sessions
tmux kill-session -t <session-name>

---

八、当前限制

Agent Teams 是实验性功能，存在以下限制：

限制	说明
In-process 队友没有会话恢复	/resume 和 /rewind 不会恢复 in-process 队友
任务状态可能滞后	队友有时无法将任务标记为已完成，需手动更新
关闭可能很慢	队友完成当前请求或工具调用后才关闭
每个会话一个团队	负责人一次只能管理一个团队
没有嵌套团队	队友无法生成自己的团队或队友
负责人是固定的	无法将队友提升为负责人或转移领导权
权限在生成时设置	无法在生成时为每个队友设置不同权限模式
分割窗格需要 tmux 或 iTerm2	VS Code 终端、Windows Terminal、Ghostty 不支持分割模式

---

九、总结

Agent Teams 是 Claude Code 的高级特性，适合需要并行协作的复杂任务：

核心优势：

• 队友可以直接相互通信和协作
• 通过共享任务列表自我协调
• 并行探索增加真实价值

与 Subagents 选择指南：

场景	推荐方案
只需要结果，不需要协作	Subagents
需要队友间讨论和协作	Agent Teams
成本敏感	Subagents
复杂研究、竞争假设调查	Agent Teams
简单的代码搜索	Subagents
跨层协调、多角度审查	Agent Teams

最佳实践总结：

1. 从研究和审查任务开始熟悉 Agent Teams
2. 控制团队规模（2-4 队友最佳）
3. 给队友足够的任务 context
4. 避免文件冲突，分配不同的文件集
5. 监控进度，及时指导
6. 使用 hooks 强制质量门

通过合理使用 Agent Teams，可以让多个 Claude 实例像真正的团队一样协作，大幅提升复杂任务的效率。