Claude Code Agent Teams：多智能体协作编程的完全指南

发表于昨天更新于昨天

作者 Administrator

25~33 分钟 阅读

一、为什么需要多智能体协作？

单智能体的瓶颈

使用过 Claude Code 的开发者都有类似的体验：当你让AI处理一个复杂任务——比如跨三个服务重构认证模块——它可能完成到60%的时候，上下文就开始退化了。第2步的细节模糊到了第5步，你不得不 /clear 重新开始。

问题的本质在于：随着上下文窗口的扩大，LLM的推理能力会下降。 这不仅仅是触及Token限制的问题，而是上下文中的信息越多，模型就越难聚焦于当前最重要的事情。把项目经理的战略笔记塞进一个正在修复CSS Bug的上下文中，反而会影响AI的表现。

人类团队的启发

这和人类团队的工作方式异曲同工。我们不会让后端工程师坐在前端代码评审会上，也不会把每条Slack消息都抄送全公司。专业化的本质就是聚焦。

多智能体协作将这个理念系统化：给每个Agent一个狭窄的范围和干净的上下文，就能在每个领域获得更好的推理质量、独立的质量检查、自然的阶段性检查点，以及当某个Agent出错时的优雅降级。

二、Agent Teams 核心架构

基本组件

Agent Teams 的架构非常直观，由四个核心组件构成：

Team Lead（团队领导）： 你的主 Claude Code 会话，负责创建团队、派生队友、分配任务和综合结果
Teammates（队友）： 独立的 Claude Code 实例，每个都有自己的上下文窗口，独立处理分配的任务
Task List（任务列表）： 共享的工作项，支持依赖追踪，当依赖任务完成时自动解锁后续任务
Mailbox（邮箱系统）： 智能体之间的直接通讯系统——不仅仅是向领导汇报，队友之间也可以直接交流

与子代理（Subagents）的关键区别

很多人会问：Claude Code 已经有子代理了，Agent Teams 有什么不同？区别是本质性的：

维度	子代理（Subagents）	Agent Teams
上下文	独立窗口，结果返回调用者	独立窗口，完全自主
通讯方式	只能向主Agent汇报	队友之间可以直接交流
协调机制	主Agent管理一切	共享任务列表，自主协调
适用场景	聚焦型任务，只需要结果	需要讨论、挑战和协作的复杂工作
Token成本	较低（结果摘要返回）	较高（每个队友是独立实例，约5倍）

简单来说： 子代理是"去调查X，告诉我结果"；Agent Teams 是"从三个角度调查这个Bug，互相辩论哪个理论是正确的"。

三、快速上手指南

第一步：启用 Agent Teams

Agent Teams 目前是实验性功能，默认禁用。有三种启用方式：

方式一：通过 settings.json（推荐）

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

方式二：环境变量（永久生效）

在你的 .bashrc 或 .zshrc 中添加：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方式三：单次会话启用（测试用）

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

第二步：选择显示模式

Agent Teams 支持两种显示模式：

进程内模式（In-process，默认）： 所有队友在主终端内运行。使用 Shift+Up/Down 切换队友，Enter 查看队友会话，Escape 中断，Ctrl+T 切换任务列表。适用于任何终端。

分屏模式（Split-pane）： 每个队友在独立的 tmux 或 iTerm2 窗格中运行，可以同时看到所有人的输出。需要安装 tmux。

{
  "teammateMode": "in-process"  // 或 "tmux"
}

⚠️ 注意：分屏模式不支持 VS Code 集成终端、Windows Terminal 和 Ghostty。

第三步：创建你的第一个团队

启用后，用自然语言告诉 Claude 你想要什么样的团队结构即可：

我正在重构认证模块。创建一个Agent团队：
- 一个队友负责后端JWT逻辑
- 一个队友负责前端Session处理
- 一个队友编写集成测试

Claude 会自动创建共享任务列表、派生队友，并开始协调工作。不需要YAML配置，不需要样板代码。

四、典型应用场景

场景一：竞争性假设调试

这是Agent Teams 最精彩的用例。单个Agent找到一个合理的解释就会停下来；多个Agent互相辩论才能找到正确的解释。

生产环境API间歇性返回500错误。创建一个调试团队：
- 假设1：数据库连接池耗尽
- 假设2：缓存层的竞态条件
- 假设3：请求处理器的内存泄漏

让他们共享证据，辩论哪个理论符合日志记录。

这比串行调查要好得多——串行调查存在"锚定效应"，一旦你探索了一个理论，后续调查就会偏向它。多个调查员运行对抗性辩论，能更快地收敛到根本原因。

场景二：多视角代码评审

单个评审员倾向于在同一时间关注同一类型的问题。拆分评审标准到独立领域，每个都能得到充分关注：

创建Agent团队评审PR #142。派生三个评审员：
- 一个关注安全影响
- 一个检查性能影响
- 一个验证测试覆盖率

让他们各自评审并报告发现。

场景三：跨层特性开发

当特性横跨多个层时，每个队友负责一层，避免文件冲突：

为新的支付功能创建Agent团队：
- 队友1：后端API端点和数据库Schema
- 队友2：前端组件和状态管理
- 队友3：端到端测试和集成测试

场景四：研究与探索

在开始实施之前，同时探索不同的方案：

我正在设计一个帮助开发者追踪代码库中TODO注释的CLI工具。
创建Agent团队从不同角度探索：
一个队友负责UX，一个负责技术架构，一个扮演魔鬼代言人。

五、高级功能与控制

计划审批机制

对于高风险任务，可以要求队友在实施前先提交计划：

派生一个架构师队友来重构认证模块。
在他做任何更改之前要求计划审批。

队友会在只读计划模式下工作，直到领导批准。如果被拒绝，他们会修改并重新提交。你还可以设定审批标准：

"只批准包含测试覆盖的计划"
"拒绝修改数据库Schema的计划"

委派模式（Delegate Mode）

按 Shift+Tab 可以限制领导只能做协调工作——派生队友、发送消息、管理任务，不能直接写代码。这解决了一个常见问题：领导"手痒"自己开始实现，而不是等队友完成。

直接与队友交互

每个队友都是完整的 Claude Code 会话。你可以直接与任何队友通讯，给额外指令、问后续问题或调整方向——无需通过领导中转。

任务依赖管理

任务可以依赖其他任务。待处理的任务如果有未解决的依赖，在依赖完成之前无法被认领。系统自动处理解锁逻辑。

六、最佳实践

1. 给队友充足的上下文

队友会自动加载项目上下文（CLAUDE.md、MCP服务器、技能），但不会继承领导的对话历史。在派生提示中包含任务特定的细节：

派生一个安全评审队友，提示为："评审src/auth/目录下的认证模块，
检查安全漏洞。重点关注Token处理、Session管理和输入验证。
应用使用存储在httpOnly cookies中的JWT Token。
按严重程度报告所有问题。"

2. 合理划分任务粒度

太小： 协调开销超过收益
太大： 队友工作太久没有检查点，浪费风险增加
刚好： 自包含的工作单元，能产出清晰的交付物（一个函数、一个测试文件、一份评审报告）

建议每个队友分配5-6个任务，保持生产力并允许在某人卡住时重新分配。

3. 避免文件冲突

两个队友编辑同一个文件会导致覆盖。规划工作时让每个队友拥有不同的文件。如果必须修改同一文件，用依赖关系来排序任务。

4. 从只读任务开始

如果你是Agent Teams的新手，从代码评审或研究性任务开始——有清晰边界且不需要写代码的任务。先学会协调模式，再尝试并行化实现。

5. 主动监控和引导

定期检查队友的进度。及时纠正不对的方向。让团队长时间无人值守会增加浪费的风险。

七、什么时候不该用 Agent Teams

Agent Teams 增加了协调开销，Token消耗大约是单会话的5倍。以下场景不适合使用：

顺序依赖的任务： 必须按顺序完成的工作无法从并行化中受益
同文件编辑： 多个Agent编辑同一文件会造成冲突
高度耦合的任务： 大量相互依赖的任务会创建阻塞链
简单修复： 一个拼写错误不需要出动团队
日常例行任务： 单会话在成本效益上更优

最佳使用场景的甜蜜点是： 并行探索能带来真正价值，且队友之间可以基本独立运作的复杂工作。

八、已知限制与故障排除

当前限制

不支持会话恢复：/resume 和 /rewind 无法恢复进程内队友
每个会话只能有一个团队
不支持嵌套团队：队友不能派生自己的团队
领导角色固定：不能提升队友为领导
权限继承：所有队友继承领导的权限设置
关闭可能较慢：队友会完成当前工作后才退出

常见问题

Agent Teams 选项不出现？ 验证环境变量是否正确设置：

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

输出应为 1。如果使用 settings.json，确保标志在 env 块中。

队友不出现？ 在进程内模式下，队友可能已经在运行。按 Shift+Down 循环查看。也检查一下你的任务是否足够复杂到需要一个团队。

队友卡住了？ 任务状态可能有延迟。给它10-15秒。如果确实卡住了，通过领导直接给队友发消息。

孤立的 tmux 会话？

tmux ls
tmux kill-session -t <session-name>

九、存储位置

团队和任务数据存储在本地：

~/.claude/teams/{team-name}/config.json    # 团队元数据和成员信息
~/.claude/tasks/{team-name}/               # 任务列表

十、总结与展望

Claude Code Agent Teams 代表了AI辅助开发的一次重要进化。对于合适的场景——并行代码评审、对抗性调试、多模块特性开发——并行探索确实能发现单个Agent容易遗漏的问题。仅"竞争性假设"这一个模式，就足以证明学习这个特性的价值。

但要记住一条重要的原则：让问题引导工具选择，而不是反过来。 如果单个Agent在聚焦会话中就能更快完成任务，那就用单个Agent。Agent Teams 的Token成本是实实在在的（约5倍），应该把它留给真正受益于多视角并行工作的场景。

对于我们这样需要独立管理大型代码库的技术负责人来说，Agent Teams 最大的启示或许是：管理AI团队的技能，和管理人类团队的技能，在底层是相通的——任务分解、边界划分、上下文管理、进度监控。 掌握了一个，另一个也就手到擒来了。

本文基于 Claude Code 官方文档及社区实践整理。Agent Teams 目前仍为实验性功能（Research Preview），功能和行为可能随版本更新而变化。

智能编程, AI开发工具

许可协议: