Claude Code Agent Teams 完全指南

Agent Teams 是 Claude Code 的实验性功能，允许你协调多个 Claude Code 实例作为一个团队工作。这个功能让 AI 代理之间可以相互通信、共享任务列表，真正实现并行探索和协作。

什么是 Agent Teams

Agent Teams 让你创建一个”团队”，其中包含一个负责人（Team Lead）和多个队友（Teammates）：

• Team Lead：主会话，负责创建团队、协调工作、分配任务
• Teammates：独立的 Claude Code 实例，各自处理分配的任务

与 Subagents 不同，队友之间可以直接相互通信，而不仅仅向主代理报告结果。

启用 Agent Teams

Agent Teams 默认禁用，需要通过配置开启：

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

将上述配置添加到 .claude/settings.json 或环境变量中。

可选配置

{
  "teammateMode": "in-process"
}

模式	说明
in-process	所有队友在主终端内运行，使用 Shift+Down 切换
tmux	每个队友获得独立窗格，需要 tmux
auto	自动检测（默认）

基本用法

启用后，用自然语言描述你想要的任务：

I'm designing a CLI tool. Create an agent team to explore this:
- One teammate on UX design
- One on technical architecture
- One playing devil's advocate

Claude 会自动创建团队，生成队友，并根据你的提示协调工作。

常用命令

指定队友数量和模型

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.

关闭队友

Ask the researcher teammate to shut down

清理团队

Clean up the team

与 Subagents 的对比

特性	Subagents	Agent Teams
Context	自己的 context window	自己的 context window
通信	仅向主代理报告	队友直接相互发送消息
协调	主代理管理所有工作	共享任务列表，自我协调
适用场景	结果重要的专注任务	需要讨论和协作的复杂工作

最佳实践

1. 任务分解要适当

• 太小：协调开销超过收益
• 太大：队友工作太久不检查
• 恰到好处：产生清晰的可交付成果

2. 等待队友完成

如果负责人开始自己做工作而不是等待队友：

Wait for your teammates to complete their tasks before proceeding

3. 避免文件冲突

分解工作，使每个队友拥有不同的文件集。

4. 监控和指导

检查队友进度，重定向不起作用的方法。

使用场景示例

并行代码审查

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

调试调查

Users report the app exits after one message. Spawn 5 teammates
to investigate different hypotheses. Have them debate like a
scientific discussion.

当前限制

• In-process 队友没有会话恢复
• 任务状态可能滞后
• 关闭可能很慢
• 每个会话只能有一个团队
• 没有嵌套团队

总结

Agent Teams 是一个强大的实验性功能，特别适合：

• 并行研究和审查
• 新模块或功能开发
• 使用竞争假设进行调试
• 跨层协调

虽然有一些限制，但对于复杂任务来说，它能显著提高效率。开启方式简单，配置好环境变量即可开始使用。