Claude Code Agent Teams：让多个 Claude 实例协同工作

当一个问题需要从多个角度同时探索时，与其让一个 Claude 实例串行思考，不如让多个 Claude 实例并行工作、相互质疑、共同收敛。

什么是 Agent Teams？

Agent Teams 是 Claude Code 的一项实验性功能，它允许你协调多个独立的 Claude Code 实例（称为”队友”）同时工作。一个会话充当团队负责人（Team Lead），负责协调工作、分配任务和综合结果。每个队友都在自己的 context window 中独立运行，并且可以直接相互通信。

这与传统的 subagents 不同——subagents 在单个会话中运行，只能向主代理单向报告结果，而 Agent Teams 的队友们可以互相质疑、讨论、共享发现。

何时使用 Agent Teams？

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

场景	说明
并行代码审查	一个审查安全、一个审查性能、一个审查测试覆盖，同时进行
竞争假设调试	多个队友分别测试不同的理论，相互质疑，更快找到根本原因
新模块设计	前端、后端、测试各自负责，同时推进
研究和调查	多个角度同时探索问题，然后整合发现

与 Subagents 的对比

特性	Subagents	Agent Teams
Context	共享主会话的 context	每个队友独立 context
通信	单向：向主代理报告	双向：队友直接相互通信
协调	主代理管理	共享任务列表，自我协调
令牌成本	较低	较高（每个队友是独立实例）
最佳用途	专注任务，只需要结果	需要讨论和协作的复杂工作

启用 Agent Teams

Agent Teams 默认禁用，需要设置环境变量：

方法 1：环境变量

1 2	export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

方法 2：settings.json

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

启动你的第一个 Agent Team

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

1
2
3

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 会：

创建一个团队负责人（你自己）
根据任务生成 2-3 个队友
创建共享任务列表
让队友开始并行工作

显示模式

Agent Teams 支持两种显示模式：

In-process 模式（默认）

所有队友在主终端内运行
使用 Shift+Up/Down 切换队友
无需额外配置

Split panes 模式

每个队友有自己的 tmux/iTerm2 窗格
可同时看到所有队友的输出
需要安装 tmux 或 iTerm2 with it2 CLI

切换模式：

1	claude --teammate-mode split-pane # 或 in-process

核心操作指南

1. 直接与队友对话

每个队友都是完整的 Claude Code 会话：

1	Ask the UX teammate to focus on the onboarding flow

快捷键：

Shift+Up/Down - 切换队友
Enter - 查看队友会话
Escape - 中断队友当前轮次
Ctrl+T - 切换任务列表

2. 任务分配与认领

团队使用共享任务列表协调工作：

1	Assign the authentication refactor to the backend teammate

任务状态：

⏳ 待处理
🔄 进行中（被某队友认领）
✅ 已完成

任务可以设置依赖关系，被阻塞的任务会在依赖完成后自动解锁。

3. 计划批准模式

对于复杂任务，可以要求队友先提交计划：

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

队友会在只读模式下工作，完成计划后发送批准请求。负责人可以批准或拒绝并给出反馈。

4. 委派模式

防止负责人自己开始实施任务（而不是等待队友）：

按 Shift+Tab 进入委派模式
负责人被限制为仅协调工具：生成、消息、关闭、任务管理
适合完全专注于编排的场景

5. 关闭与清理

1	Ask the researcher teammate to shut down

或一键清理整个团队：

1	Clean up the team

⚠️ 清理前确保所有队友已关闭。

实际用例示例

用例 1：并行代码审查

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.

负责人综合三个审查者的发现，生成完整的审查报告。

用例 2：竞争假设调试

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.

多个独立调查员相互反驳，幸存下来的理论更可能是实际根本原因。

最佳实践

✅ 应该做的

给队友足够的 context
- 队友加载项目 context（CLAUDE.md、MCP、skills）
- 但不继承负责人的对话历史
- 在生成提示中包含任务细节
适当调整任务大小
- 太小：协调开销超过收益
- 太大：队友工作太久不检查
- 恰到好处：自包含的单位（函数、测试文件、审查）
从研究和审查开始
- 新手先从无代码任务开始
- 熟悉后再尝试并行实现
避免文件冲突
- 分解工作，让每个队友负责不同文件集

❌ 避免的

顺序任务（用单个会话更有效）
同一文件的多人编辑
让团队长时间无人值守
在队友完成前负责人就开始实施

限制与注意事项

Agent Teams 是实验性功能，当前限制：

限制	说明
会话恢复	`/resume` 和 `/rewind` 不会恢复 in-process 队友
任务状态滞后	队友有时无法将任务标记为完成
关闭较慢	队友在关闭前需完成当前请求
单团队限制	负责人一次只能管理一个团队
无嵌套	队友无法生成自己的团队
权限固定	生成后无法批量更改权限模式