Claude Code Agent Teams 指南：如何让多个 AI 实例协同工作

核心问题：如何突破单一 AI 会话的限制，通过多智能体协作大幅提升复杂开发任务的效率与质量？

随着软件开发的复杂性日益增加，单一的 AI 编程助手有时会显得力不从心。特别是在处理需要多角度审视、并行探索或跨层协调的任务时，仅仅依赖一个“大脑”往往容易陷入思维定势。Claude Code 引入的“Agent Teams（智能体团队）”功能，正是为了解决这一问题。它允许你编排多个 Claude Code 实例，让它们像人类团队一样分工合作。本文将深入探讨这项技术的原理、应用场景、操作细节以及如何在实际工程中发挥其最大价值。

Teamwork
图片来源：Unsplash

Agent Teams 是什么以及为什么需要它？

核心问题：Agent Teams 与普通的 AI 助手或 Subagents 有什么本质区别？

Agent Teams 允许你协调多个 Claude Code 实例协同工作。在这个架构中，一个会话充当“团队负责人”，负责统筹工作、分配任务并综合结果。而“队友”则在各自的上下文窗口中独立工作，并能够直接相互通信。这与传统的单一会话或子代理模式有着本质的区别。

独立性与直接通信

最关键的区别在于独立性。每个队友都是一个完整的、独立的 Claude Code 会话。这意味着它们拥有各自的上下文窗口，不会互相干扰，也不会因为单一会话的上下文限制而遗忘信息。更重要的是，队友之间可以直接“对话”，而不需要事事都经过负责人的中转。这种扁平化的通信结构，使得团队内部的协作更加高效，更像是一个真正的敏捷开发团队。

与 Subagents 的对比

为了更清晰地理解 Agent Teams 的定位，我们可以将其与 Subagents（子代理）进行对比。Subagents 也在单一会话内运行，但它们只能将结果报告给主代理，彼此之间无法交流。而 Agent Teams 则是一个去中心化程度更高的协作网络。

特性维度	Subagents（子代理）	Agent Teams（智能体团队）
上下文环境	拥有独立上下文；结果返回给调用者	拥有独立上下文；完全独立运行
通信机制	仅将结果报告回主代理	队友之间直接互发消息
协调方式	主代理管理所有工作	共享任务列表，自我协调
最佳适用场景	只关注结果的专注型任务	需要讨论和协作的复杂工作
Token 成本	较低：结果汇总回主上下文	较高：每个队友都是独立的 Claude 实例

“

反思 / 见解：
从架构设计的角度来看，Agent Teams 实际上是在模拟人类专家组的协作模式。Subagents 更像是“雇佣兵”，领命做事，交付结果；而 Agent Teams 则像是“项目组”，成员之间会有思想碰撞、观点交锋。这种模拟虽然增加了资源消耗，但对于那些需要创造性发散和交叉验证的任务来说，其产出的质量和深度往往是单一 Agent 无法比拟的。

什么时候应该使用 Agent Teams？

核心问题：在开发流程中，哪些场景下使用 Agent Teams 能带来显著的收益回报？

并不是所有任务都需要动用“团队”。Agent Teams 会带来显著的协调开销，并消耗更多的 Token。因此，识别最佳使用场景至关重要。Agent Teams 在那些“并行探索能带来真实价值”的任务中表现最为出色。

1. 研究与审查

当你需要对代码库或技术方案进行深度审查时，单一的审查者往往会陷入某种思维盲区。通过组建团队，可以让多个队友同时调查问题的不同方面，然后分享并挑战彼此的发现。例如，一人关注安全漏洞，一人关注性能瓶颈，另一人关注代码可读性。这种多维度的并行扫描，能确保问题被无死角地挖掘出来。

2. 新模块或功能的开发

在开发新功能时，不同队友可以分别负责不同的模块，互不干扰。这避免了单一代码文件被多人同时修改导致的冲突，同时也让每个人都能专注于自己领域的深度逻辑。

3. 基于竞争假设的调试

这是一个非常有趣且强大的场景。当 Bug 的根因不明时，单一 Agent 通常会找到一个 plausible（看似合理）的解释就停止搜索。而在 Agent Teams 中，你可以让队友们提出不同的假设，并鼓励他们互相反驳、试图证伪对方的观点。这种“科学辩论”式的调试方法，能帮助团队更快地收敛到真正的根本原因，避免被误导性的表象所迷惑。

4. 跨层协调

对于涉及前端、后端和测试的修改，每个队友可以负责一个层级。他们之间通过通信机制协调接口定义和数据流，确保全栈修改的一致性。

反面案例：何时不应使用

如果任务是顺序进行的（例如步骤 B 必须依赖步骤 A 的结果），或者涉及对同一文件的大量密集编辑，又或者存在复杂的依赖关系，那么单一会话或 Subagents 会是更高效的选择。因为在这种情况下，协调并行工作的开销超过了其带来的收益。

如何启用并启动你的第一个 Agent Team？

核心问题：从零开始配置并运行一个多智能体团队需要哪些具体步骤？

Agent Teams 目前是一个实验性功能，默认情况下是禁用的。要使用它，你需要先进行简单的环境配置。

第一步：启用功能开关

你需要通过设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 为 1 来启用该功能。你可以在 Shell 环境中设置，或者更推荐地在 settings.json 文件中进行持久化配置。

配置文件示例：

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

第二步：用自然语言描述需求

启用功能后，你不需要编写复杂的配置脚本来定义团队结构。你只需要用自然语言告诉 Claude 你想创建一个团队，并描述任务和团队结构。

实战案例：设计 CLI 工具

假设你要设计一个帮助开发者追踪代码库中 TODO 注释的 CLI 工具。你可以这样输入：

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.

在这个例子中，你定义了三个独立的角色：UX 体验专家、技术架构师以及唱反调的评审者。这三个角色是相互独立的，可以在不等待彼此的情况下并行探索问题。Claude 会据此创建一个拥有共享任务列表的团队，生成相应的队友，并开始协调工作。

第三步：观察团队运作

一旦团队创建成功，负责人的终端会列出所有队友及其当前的工作状态。如果你使用的是“进程内”模式，可以使用键盘快捷键在队友之间切换并进行交互。

“

反思 / 见解：
这里的“自然语言驱动”非常关键。它极大地降低了使用多智能体系统的门槛。以前，设计一个多 Agent 系统可能需要编写复杂的编排逻辑，而现在，你只需要像一个项目经理一样，清晰地表达目标和分工。这让开发者可以专注于“做什么”而不是“怎么做”。

如何控制和管理你的 Agent Team？

核心问题：作为用户，如何通过不同的显示模式和控制手段，让团队按照预期的方式高效协作？

一旦团队启动，你就成为了这个团队的“总监”。你可以通过自然语言向负责人下达指令，由它来处理团队协调、任务分配和委派。但为了更精细地控制，你需要了解几个关键的管理维度。

选择显示模式

Agent Teams 支持两种主要的显示模式，适应不同的工作习惯和终端环境。

1. 进程内模式

这是最通用的模式，所有队友都在你的主终端内运行。你可以使用 Shift+Up/Down 键在不同的队友之间切换，选中后直接输入消息即可。它不需要任何额外的设置，适用于任何终端环境。

2. 分屏模式

在这种模式下，每个队友都会获得自己独立的终端窗格。你可以同时看到所有人的输出，点击某个窗格即可直接与该队友交互。这种模式非常直观，适合需要同时监控多个工作流的场景。它依赖于 tmux 或 iTerm2。

配置显示模式

默认设置是 "auto"，即如果你已经在 tmux 会话中运行，则自动使用分屏模式，否则使用进程内模式。你可以通过 settings.json 强制指定模式：

{
  "teammateMode": "in-process"
}

或者，通过命令行标志为单次会话指定模式：

claude --teammate-mode in-process

“

注意：如果你选择分屏模式，需要手动安装 tmux 或 iTerm2 的 Python API。对于 tmux，通过系统包管理器安装即可；对于 iTerm2，需要安装 it2 CLI 并在设置中启用 Python API。

指定队友和模型

虽然 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.

这是一个极其重要的安全机制。当队友完成计划后，会向负责人发送批准请求。负责人会根据你设定的标准（如“必须包含测试覆盖”或“禁止修改数据库架构”）来决定是批准还是拒绝。这能有效防止 AI 在理解不充分的情况下进行破坏性修改。

使用委派模式

有时，负责人可能会“手痒”，自己开始执行任务而不是等待队友。委派模式就是为了解决这个问题。启用后，负责人只能使用协调类工具：生成、向队友发送消息、关闭队友和管理任务。这迫使领导专注于统筹全局，而不是陷入具体的代码细节中。在团队创建后，按下 Shift+Tab 即可循环切换到委派模式。

任务分配与认领

团队通过“共享任务列表”来协调工作。任务有三种状态：待处理、进行中和已完成。任务之间还可以设置依赖关系。

负责人分配：你可以明确告诉负责人把哪个任务交给哪个队友。
自主认领：队友完成任务后，会自动从列表中认领下一个未被分配且无依赖阻塞的任务。

为了防止多个队友同时抢夺同一个任务，系统使用了文件锁机制，确保任务分配的原子性。

清理团队

工作完成后，不要忘记清理资源。你可以输入 Clean up the team。负责人在执行清理前会检查是否还有活跃的队友，如果有，必须先关闭它们。这会移除共享的团队资源，保持系统的整洁。

Agent Teams 的底层架构是如何工作的？

核心问题：在这个多智能体系统中，组件之间是如何通信并保持状态一致的？

理解了如何使用之后，让我们深入到幕后，看看这套系统是如何在技术层面实现的。

组件构成

一个 Agent Team 由以下几个核心组件构成：

组件	角色
团队负责人	主 Claude Code 会话，负责创建团队、生成队友并协调工作
队友	独立的 Claude Code 实例，各自在分配的任务上工作
任务列表	共享的工作项列表，供队友认领和完成
邮箱	智能体之间的消息传递系统

启动机制

Agent Teams 的启动通常有两种触发方式：

你主动请求：你明确告诉 Claude 需要一个团队来处理并行任务。
Claude 提议：Claude 分析任务后，认为并行处理能带来显著收益，于是建议创建团队。这需要你的确认才会执行。

数据存储

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

团队配置：~/.claude/teams/{team-name}/config.json
任务列表：~/.claude/tasks/{team-name}/

配置文件中包含了 members 数组，记录了每个队友的名字、Agent ID 和类型。队友通过读取这个文件来发现彼此的存在。

上下文与通信细节

上下文隔离：每个队友生成时，会加载与常规会话相同的项目上下文（如 CLAUDE.md、MCP 服务器和技能），但不会继承负责人的对话历史。这保证了每个队友都从一个相对“干净”的状态开始，避免被之前的讨论误导。
消息传递：系统支持自动消息投递。当队友发送消息时，会自动送达接收方，无需负责人轮询。当队友完成任务停止工作时，也会自动通知负责人。
广播机制：支持向所有队友同时发送广播消息，但由于成本随团队规模线性增加，建议谨慎使用。

“

反思 / 见解：
架构中最精妙的设计在于“本地文件锁”和“邮箱”机制的结合。通过简单的本地文件存储来实现分布式状态管理，既保证了轻量级，又避免了引入复杂的数据库依赖。这种设计哲学非常符合开发者工具的定位——简单、可靠、可调试。

实际应用场景深度解析

核心问题：在实际的开发工作流中，Agent Teams 能解决哪些具体的痛点？

让我们通过两个具体的例子，看看 Agent Teams 是如何在实战中发挥作用的。

场景一：并行代码审查

单一的代码审查者往往会在一段时间内只关注某一类问题。例如，先看了安全问题，再看性能问题时可能已经疲惫了。Agent Teams 可以将审查标准分解为独立的领域，让每个队友戴上不同的“眼镜”。

操作指令示例：

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.

执行逻辑：
三位审查员基于同一个 PR 分支工作，但应用了完全不同的过滤器。安全审查员寻找注入漏洞、权限绕过；性能审查员分析算法复杂度和资源占用；测试审查员则检查边界条件和覆盖率。最后，负责人将这三份独立的报告进行综合，生成一份全面的审查意见。这种并行处理不仅速度快，而且审查的深度是单次串行审查难以达到的。

场景二：基于竞争假设的根因调查

当面对一个模糊的 Bug 报告，例如“用户报告应用在发送一条消息后就退出了，而不是保持连接”，传统的调试方式往往是试错。

操作指令示例：

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.

执行逻辑：
这里的关键在于“辩论结构”。5 个队友分别持有不同的假设（如内存溢出、网络异常、未捕获的异常、状态机错误、并发竞争）。他们的任务不仅是调查自己的理论，还要去挑战别人的理论。这种机制有效地对抗了心理学上的“锚定效应”——即一旦我们探索了一个理论，后续的探索就会下意识地偏向它。在多个独立调查员相互证伪的压力下，只有那个经得起推敲的理论才能最终存活下来。这往往是寻找真正根因的最快路径。

使用 Agent Teams 的最佳实践

核心问题：如何规避常见的陷阱，确保多智能体协作高效且可控？

根据实际使用经验，以下是一些能帮助你最大化发挥 Agent Teams 效用的建议。

给予足够的上下文

虽然队友会加载项目上下文，但它们没有负责人的历史记忆。在生成队友时，务必在提示词中包含任务特定的细节。

示例：

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

合理划分任务粒度

太小的任务：协调开销会超过收益，得不偿失。
太大的任务：队友工作时间过长且没有检查点，一旦方向错误，浪费的计算资源巨大。
恰到好处：任务应该是自包含的单元，能产出清晰的交付物，比如一个函数、一个测试文件或一份审查报告。

学会“等待”

有时负责人会急不可耐地开始自己动手实现任务。如果你发现这种情况，明确指令：

Wait for your teammates to complete their tasks before proceeding

这能确保分工明确，避免负责人和队友做重复工作。

从研究和审查开始

如果你刚接触 Agent Teams，建议先从那些边界清晰且不需要写代码的任务开始，比如审查 PR、研究库或调查 Bug。这些任务能让你体验到并行探索的价值，而无需面对并行实施带来的协调复杂性。

避免文件冲突

这是最常见的问题。如果两个队友同时编辑同一个文件，后写入者会覆盖前者的修改。在分配任务时，务必确保每个队友拥有不同的文件集。

持续监控与引导

不要让团队完全处于无人看管的状态太久。定期检查队友的进度，对行不通的方法进行重定向，并随着结果的出现不断综合发现。这能将浪费精力的风险降到最低。

常见问题排查与当前限制

核心问题：在使用过程中遇到异常行为或功能限制时，该如何应对？

队友未出现

如果队友没有显示出来：

在进程内模式下，尝试按 Shift+Down 循环查看活跃队友。
检查任务是否足够复杂，Claude 可能认为不需要队友。
如果使用了分屏模式，确保 tmux 已安装并在 PATH 中，或者 iTerm2 的 Python API 已启用。

权限提示过多

队友的权限请求会汇总给负责人，可能造成干扰。建议在生成队友前，在权限设置中预批准常见操作。

队友遇到错误停止

队友可能遇到错误后直接挂起。你可以选中并查看其输出，然后给予额外指令或生成一个替代队友继续工作。

提前清理

如果负责人在任务完成前就决定结束，你可以明确告诉它继续工作，或者要求它等待队友完成。

当前局限性

这是一个实验性功能，请注意以下限制：

会话恢复：使用 /resume 或 /rewind 无法恢复进程内队友。恢复后负责人可能尝试向不存在的队友发送消息。
任务状态滞后：队友有时可能未能标记任务为完成，导致依赖任务被阻塞。
单团队限制：一个负责人一次只能管理一个团队。
无嵌套团队：队友不能创建自己的子团队。
终端支持：分屏模式不支持 VS Code 集成终端、Windows Terminal 或 Ghostty。

Coding Screen
图片来源：Unsplash

实用摘要与操作清单

实用摘要

Agent Teams 为 Claude Code 引入了多智能体并行协作的能力。它通过一个负责人的统筹和多个独立队友的执行，特别适用于代码审查、多假设调试、新功能并行开发等场景。虽然其 Token 成本高于单一会话，但在处理复杂、多维度的问题时，其带来的质量和效率提升是显著的。合理配置显示模式、任务粒度和权限控制，是成功使用该功能的关键。

操作清单

环境准备：在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 为 1。
需求定义：明确你需要并行处理的具体任务，并判断其是否符合 Agent Teams 的适用场景。
创建团队：使用自然语言描述团队结构（如角色数量、具体职责）。
模式选择：根据终端环境选择 in-process 或 split panes 模式。
任务监控：利用 Shift+Up/Down 或分屏点击，实时监控队友工作状态。
干预与引导：在关键节点（如计划制定、出现错误时）进行人工干预。
结果综合：要求负责人综合所有队友的产出，生成最终报告。
资源清理：任务完成后，执行 Clean up the team 释放资源。

一页速览

定义：多 Claude 实例协作系统，包含负责人与独立队友。
核心优势：并行探索、多维度审查、去中心化通信、避免思维定势。
适用场景：代码审查、复杂调试、新模块开发、跨层协调。
启用方式：设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 为 1。
控制方式：自然语言指令、任务列表、计划批准机制、委派模式。
成本考量：Token 消耗随队友数量线性增加，适用于高价值任务。
关键限制：实验性功能、暂不支持会话恢复、依赖特定终端（分屏模式）。

常见问题解答（FAQ）

1. Agent Teams 和 Subagents 在成本上有什么具体的区别？
Agent Teams 的每个队友都是独立的 Claude 实例，拥有独立的上下文窗口，因此 Token 成本会随着队友数量的增加而显著增加。Subagents 则是在单一会话内运行，结果会被汇总回主上下文，成本相对较低。

2. 如果队友开始修改同一个文件怎么办？
这会导致文件内容覆盖，是必须避免的情况。最佳实践是在分配任务时，确保每个队友拥有独立的文件集合。如果必须操作同一文件，应通过严格的任务依赖和串行化来管理，但这违背了并行工作的初衷。

3. 我可以在 VS Code 的集成终端中使用分屏模式吗？
目前不行。分屏模式仅支持 tmux 或 iTerm2。在 VS Code 集成终端、Windows Terminal 或 Ghostty 中，你需要使用默认的“进程内”模式，通过键盘快捷键在队友之间切换。

4. 负责人如果不听指挥，自己开始写代码怎么办？
你可以使用“委派模式”。在团队创建后按下 Shift+Tab，这会将负责人限制为只能使用协调工具，禁止其直接执行代码修改或读写工具，强制它专注于管理工作。

5. 如何确保队友的修改是安全的？
在生成队友时，使用“要求计划批准”的指令。队友在进入实施阶段前必须提交计划，由负责人根据你预设的标准（如必须包含测试、禁止修改特定模式）进行审批。

6. 任务依赖是如何处理的？
任务列表支持依赖关系设置。如果一个待处理的任务依赖于未完成的任务，它会自动被阻塞。只有当依赖任务完成后，阻塞的任务才会解除锁定，供队友认领。

7. 如果我想中途更换队友的策略，应该怎么做？
你可以直接向该队友发送消息，给予新的指令或修正方向。如果队友无法纠正，你可以要求负责人关闭该队友，并生成一个新的替代者继续工作。

8. Agent Teams 的数据存储在哪里，安全吗？
团队配置和任务列表存储在本地目录 ~/.claude/ 下。所有数据均在本地处理，符合 Claude Code 的基本隐私安全策略。

Claude Code Agent Teams 终极指南：告别单打独斗，用多智能体并行开发实现10倍效率