多智能体并行协作开发模式（Claude Code Agent Teams）

星浩AI2026-05-11 9:11

什么是 Agent Teams？

协调多个 Claude Code 实例作为一个团队协同工作，共享任务，实现代理间消息传递和集中管理。

其中一个会话充当团队领导，负责协调工作、分配任务和汇总结果。团队成员各自独立工作，在各自的上下文窗口中进行操作，并直接相互沟通。

多 Agent 协作架构

运行原理

下面分条说明建队规则、核心组件与本地存储。

  • 如何建队 ：你 主动要求 创建团队；或 Claude 建议 建队------均需你确认 后才会创建，不会静默建队。
  • 架构组件：
组件 作用
Team lead（负责人） 建队、拉队友、协调与汇总
Teammates（队友） 独立 Claude Code 实例，执行分派任务
Task list 共享工作项，认领与完成
Mailbox 代理间消息

任务依赖由系统维护；前置任务完成后，被阻塞任务会自动解除阻塞。

  • 本地存储 （Claude 自动生成，勿手改 config.json，会被覆盖）：
    • 团队配置：~/.claude/teams/{team-name}/config.json
    • 任务目录：~/.claude/tasks/{team-name}/
  • 项目目录下自建类似 .claude/teams/teams.json 不会 被识别为团队配置。

Subagent 与 Agent Teams 的区别

两者都支持「并行处理任务」，但它们运行方式不同，选择哪种方案取决于你的工作人员是否需要相互沟通：

维度 Subagent Agent Teams
上下文 拥有独立的上下文窗口，结果会返回给调用者。 拥有独立的上下文窗口，且完全独立运行。
通信方式 仅向主代理汇报结果。 团队成员之间可以直接互相发送消息。
协调机制 由主代理管理所有工作。 通过共享任务列表进行自我协调。
适用场景 适用于只关注结果的聚焦型任务。 适用于需要讨论和协作的复杂工作。
Token 成本 较低：结果会被汇总后传回主上下文。 较高：每个队友都是一个独立的 Claude 实例。

简单选择：

  • 需要 快速、单向拆任务 、只要结果回到主会话即可 → 优先考虑 Subagent。
  • 需要 多人讨论、互相质疑、并行探索复杂问题 、且愿意承担更高 Token 成本 → 考虑 Agent Teams。

何时使用 Agent Teams？

Agent Teams 适合 「并行工作能带来收益」 的工作：多名队友 同时 查不同方向、管不同文件或不同假设，最后再收敛结论。

若工作 强依赖顺序 、或 大量来回改同一文件，协调成本往往大于收益。

更偏「编排与成本」的取舍表见后文「实战经验」中的 「何时开 Team、何时 solo」；本节保留按任务类型的速查。

适合的场景

类型 说明
调研与审查 多人分工看不同方面（如安全 / 性能 / 测试），再交叉比对结论
新模块或新功能 各队友负责不同模块或边界清晰的子任务，减少互相覆盖
调试多假设 同时验证多种可能原因，甚至通过「争论式」讨论削弱单一假设的锚定效应
跨层协作 前端、后端、测试等由不同队友各管一层，边界清晰时较顺

不适合的场景

类型 说明
严格串行任务 后一步完全依赖前一步输出时，多实例并行收益小，更适合单会话按步执行
同文件高频协作 多人同时改同一文件易导致覆盖与冲突；应拆成 不同文件/模块 或由单人串行修改
协调重于执行 若任务需要不停开会同步、依赖关系极密，团队开销大，不如单会话或子代理
日常小改动 简单改几处、问几个问题即可时，单会话 更省 Token、更省事
不愿承担实验限制时 实验阶段限制见「已知限制」；关键路径请先评估是否可接受

如何启用 Agent Teams？

Agent Teams 默认关闭，需显式打开实验开关。

方式一：settings.json 中的环境变量

在 Claude Code 的 settings.json 里增加：

json 复制代码 
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

方式二：系统环境变量

在 Shell / 系统环境中设置：

  • 名称：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
  • 值：1

启用后，用 自然语言 向 Claude 说明要组建 Agent Team 及任务即可（例如：「创建一个 agent team，分别从 UX 和架构两方面调研......」）。官方文档：Agent Teams。

快速开始

按顺序做即可跑通第一次 Agent Team（默认 进程内 in-process 模式，不依赖 tmux）。

  1. 确认版本

    终端执行 claude --version，需 v2.1.32 及以上。

  2. 打开实验开关

    按「如何启用」一节设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（settings.json 或环境变量），然后 重新打开 Claude Code / 终端，使配置生效。

  3. 进入工作目录并启动会话

    在目标项目根目录打开 Claude Code（保证能读到该项目的 CLAUDE.md 等上下文）。

  4. 用自然语言建队

    向负责人（当前主会话）说明任务与分工，并明确要求创建 Agent Team，例如：

text 复制代码 
创建 agent team，分别从用户体验、技术架构、反面质疑三个角度调研......

Claude 会创建团队、拉起队友并开始协作。

  1. 在终端里与队友互动（in-process）

    • Shift+Down：在负责人与各位队友之间循环切换；切到某个队友后直接输入即可单独对其下指令。
    • Enter ：查看某个队友的会话；Escape：中断该队友当前一轮输出。
    • Ctrl+T ：打开/关闭共享 任务列表。

  2. 收工与清理

    需要结束某位队友时，可对负责人说例如：Ask the researcher teammate to shut down。

    全部结束后让负责人执行 Clean up the team ，释放团队资源；若仍有队友在跑，清理会失败，需先关闭队友。务必由负责人执行清理；队友自行清理可能导致团队上下文解析失败、资源不一致。

可选 ：若只想强制进程内模式（任意终端可用），可启动时加 claude --teammate-mode in-process。分屏多窗格需要 tmux 或 iTerm2，且 VS Code 集成终端、Windows Terminal、Ghostty 不支持官方分屏模式，请继续使用 in-process。

更多建队话术（人数、模型、计划门禁）见下一节。

自然语言建队进阶（人数、模型与计划门禁）

以下与操作系统无关，适用于任意已启用 Agent Teams 的环境。

指定人数与模型（自然语言即可）

text 复制代码 
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

先计划再实施

复杂或高风险任务可要求队友在只读计划模式下先出方案，经负责人批准后再改代码：

text 复制代码 
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

负责人会自动审批；你可在提示中写标准（例如「仅批准含测试覆盖的计划」）。

显示模式与队友参数

Agent Teams 提供两种显示模式，侧重点不同：进程里一次看一个但切换方便；分屏能同时看到多个队友的输出，但对终端环境有要求。

In-Process（进程内模式）

  • 所有队友跑在 同一个终端 里，同一时间主要看到 一个 会话界面，在负责人与队友之间 切换 查看。
  • 任意常见终端 都能用：VS Code 集成终端、Windows Terminal、普通 shell 等。
  • 不用 额外装 tmux / 做分屏配置。
  • 切换：与「快速开始」一致，常用 Shift+Down 在负责人与队友之间 循环 切换（以你本机 Claude Code 版本提示为准；若后续支持 Shift+Up 反向切换，以官方更新为准）。
  • 更适合：快速试团队 、协作不复杂、或 没法用 tmux 分屏 的环境（含多数 Windows 原生终端场景）。

Split-Pane（分屏模式）

  • 每个队友占 独立窗格 ，可以 同时扫 多路输出，整体进度更直观。
  • 依赖环境 ：需要 tmux 或 iTerm2 （配合 it2 CLI 等，并启用 iTerm2 Python API）。
  • 可直接 点进 / 聚焦 某个窗格，和对应队友交互。
  • 更适合：任务复杂 、多人并行、需要 对照多路日志 排查问题时。

默认与手动指定

  • 默认 auto ：若检测到当前在 tmux 会话里，倾向用 分屏 ；否则用 in-process。
  • 在 ~/.claude/settings.json 里配置 teammateMode。可与开启 Agent Teams 的 env 写在同一文件里，例如 强制进程内：
json 复制代码 
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

强制走分屏路径（需本机已具备 tmux 或 iTerm2 条件）：

json 复制代码 
{
  "teammateMode": "tmux"
}

单次会话覆盖（不写入配置文件）：

bash 复制代码 
claude --teammate-mode in-process
claude --teammate-mode tmux

Windows 与 tmux

  • 原生 Windows 终端 （PowerShell、CMD、Windows Terminal）：官方 不支持 基于 tmux 的 分屏队友 。团队功能请用 in-process （teammateMode 设为 in-process 或 claude --teammate-mode in-process）；不必为 Agent Teams 单独装 tmux。
  • 想要分屏 ：最省事仍是用 in-process ；若坚持多窗格输出，可在 WSL2 里装 tmux，在 tmux 内进入项目目录（常见为 /mnt/<盘符>/...）再启动 claude，auto 才可能走分屏，具体以本机版本为准。
  • 吃不准时一律 in-process（含 MSYS2、Cygwin 等非官方组合）。

任务列表与协作要点

团队使用 共享任务列表：任务有 待处理 / 进行中 / 完成 等状态；可设 依赖 ，未完成的依赖会阻止认领下游任务。负责人可显式分派，队友也可在规则允许下 自领 下一项；认领侧有文件锁，降低多人抢同一任务的竞态。（组件级说明见上文「运行原理」中架构组件表的 Task list 一行。）

向负责人用自然语言说明目标即可；需要全员等待时可以说：「等队友完成后再继续」，避免负责人提前抢活。

权限与上下文

  • 队友启动时与 负责人相同 的权限；若负责人使用 --dangerously-skip-permissions，所有队友也会。无法在创建时为每名队友设置不同的初始权限；创建后可单独调整某队友模式。
  • 负责人的完整对话历史不会 同步给新队友；队友会加载项目上下文（如 CLAUDE.md、MCP、Skills）以及负责人给出的 创建（spawn）提示。请在 spawn 指令里写清路径、约束与验收标准。
  • 发消息按队友 名字 ；要通知多人需 逐人 发送。若希望名字稳定、便于后续引用，可在建队时让负责人为各角色 明确命名。

多队友会 显著增加 Token ；详见 Agent team token costs。

实践建议

  1. Spawn 里给足上下文：历史对话不会自动带给队友。
  2. 团队规模 ：常见 3～5 名 队友；每人约 5～6 个 任务较易保持节奏。
  3. 任务粒度：太小协调不划算，太大难以及时纠偏；以可交付单元为宜。
  4. 避免同文件冲突：按文件或模块划清边界。
  5. 负责人抢活：明确要求先等队友完成。
  6. 新手 ：先从 审 PR、调研库、查 Bug 等边界清晰、少并行写码的场景试起。
  7. 盯进度：长时间放任团队跑，容易浪费 effort。

实战经验与编排原则

本节来自项目内实践总结，与上文「官方能力说明」互补：重点不是把更多人同时丢出去干活 ，而是把 角色、依赖、规格、门禁和记忆 组织成 可收敛 的团队系统。

核心原则：Lead 只做编排，不做主力实现

  • Lead（负责人） ：定角色、卡依赖、批计划、收敛结果；不做主力写码。后续凡是拆团队的 Step 提示词，建议把这条写死，避免 Lead 和队友抢同一条路。
  • Teammates：按分派执行实现、审查、排查等具体工作。
  • 整体取向：编排优先、规格先行、门禁前置、有共享记忆（见法则三）。

法则一：先把团队跑顺，再谈并行规模

Lead 的价值主要在 orchestrator（编排） ：拆角色、写清依赖、批计划、最后收口。一条在真实项目里很稳的链路是 Architect → 规格广播 → Backend / Frontend → QA ，本质仍是 先规格、后实现。

在 Prompt 里务必写清：谁先等谁开工、谁完成后通知谁、最终由谁汇总；缺这几句，团队很容易各自为战、很快变乱。

法则二：并行不是放养，必须带 Gate

  • Plan approval 、测试门槛、错误处理、遵守 CLAUDE.md 等，尽量 前置，不要把质量堆到最后再补。
  • Agent Teams 的优势不只是「多开几个 agent」，而是 前后端、QA、实现者之间能直接通信和回流。
  • 复杂问题避免单路径死磕：可引入 对抗式分析（例如 adversarial debugger、architecture war room 等角色），用互相质疑换更稳的结论。

法则三：把团队经验沉淀成基础设施

  • 切忌角色过于单一 ：性能、可访问性、安全、响应式、坏链路等，可按维度 并行角色化 扫描，而不是所有人盯同一类问题。
  • 用仓库里的 BLOCKED.md / PROGRESS.md / TASKS.md （或等价约定）同时记录：失败尝试、任务状态、推进上下文 ，形成全队可读的 共享记忆，减轻「队友读不到 Lead 脑子里上下文」的问题。
  • CLAUDE.md ：单 agent 时是加分项；在 Agent Teams 下更像 团队操作系统------边界、常用命令、禁区、约定写清楚，全队默认遵守。

何时开 Team、何时 solo（或 swarm）

倾向 说明
更适合开 Team 并行收益明显：可拆分、可并行、需要 跨角色协同（规格、实现、审查、多假设并行等）。
更适合 solo 需求简单、模块 耦合很高 、强串行时，一个人往往 更快，少协调税。
判断标准 额外 协调成本 是否明显 小于 并行带来的 时间/质量收益；吃不准时先小规模试跑再扩人数。

已知限制（实验阶段）

  • In-process 队友 与 /resume、/rewind 不兼容 ；恢复后若负责人仍联系已退出队友，可让负责人 重新拉起队友。
  • 任务状态可能 更新滞后；若依赖链卡住，检查实际是否已完成，必要时人工改状态或让负责人催促。
  • 关闭队友可能 较慢（需等当前请求或工具调用结束）。
  • 一名负责人 同时只能管理一个团队 ；新建前须 清理 当前团队。
  • 不能嵌套团队：只有负责人能建队、管队；队友不能再去建子团队。
  • 负责人不可更换：创建团队时的主会话即为终身负责人。
  • CLAUDE.md 仍按工作目录加载，可用于向全队统一项目规范。

常见问题与边界（设计视角）

Agent Teams 仍是实验特性 。本节不重复罗列现象（以「已知限制」为准），只补充 设计时怎么用这些边界：团队形态、权限预期、终端选型、收尾流程。

实验特性会牵动哪些方面

会影响你对 团队形态 、权限预期 、终端选型 、收尾与清理流程 的整体设计。把 Agent Teams 当 带约束的协作模式 来规划，比当「万能多开」更稳。

会话与状态边界

设计预案时记住三点即可（细节见「已知限制」）：/resume、/rewind 与 in-process 队友不友好 ；任务状态可能滞后 ；关闭队友需等当前调用结束。

权限继承边界

队友 初始权限与 Lead 一致 ：负责人用什么方式开权限（含是否使用 --dangerously-skip-permissions），天花板就由谁定 。团队设计里要把 Lead 的权限策略 当成全队默认策略来评估风险（操作级说明见「权限与上下文」）。

团队模型边界

  • 一个 Lead 会话同时只能带一个 team ；换队前先 清理。
  • 不支持队友再建子团队 ，更适合 单层 协作，而不是「team of teams」多层嵌套。
  • 若你的组织方式强依赖「子团队再拆队」，需要在流程上 摊平 成单层角色与任务，而不是指望产品里再开一层。

运行环境边界

  • Split panes（分屏） 依赖 tmux 或 iTerm2（及配套配置）。
  • Windows Terminal 、VS Code 集成终端 等 不支持 官方这一分屏模式时，体验上限就是 in-process；环境会直接决定「能不能一眼看多路输出」。
  • 与 「Windows 与 tmux」 、「显示模式与队友参数」 一并阅读。

设计建议：怎么拿捏这些限制

  • 当实验能力用，不要默认当生产基座 ：适合 边界清晰、周期相对短、结果可验证 的协作任务；重依赖长期会话恢复、复杂 rewind 的长链路，要谨慎。
  • 避免强依赖 /resume、/rewind 与 in-process 队友组合 的关键路径设计；有恢复需求时优先考虑 单会话 或 可重建队友 的流程。
  • 在 macOS/Linux + tmux 或 iTerm2 下，分屏与整体可观测性通常更完整；在 Windows 原生终端场景，以 in-process + 明确任务与文档收口 为主更现实。

故障排查（简表）

现象 可尝试
看不到队友 In-process 下 Shift+Down 切换；确认任务是否复杂到值得建队；分屏时检查 tmux / it2 与 iTerm2 API
权限提示过多 事先在 permission settings 预批准常见操作
队友遇错就停 直接对该队友下新指令，或换新队友接手
负责人提前收尾 要求继续，或要求 等队友完成 再推进
tmux 会话残留 tmux ls 后 tmux kill-session -t <session-name>

延伸阅读

相关推荐
HIT_Weston2 小时前
78、【Agent】【OpenCode】bash 工具提示词（持久化）（二）
人工智能·agent·opencode
HIT_Weston2 小时前
77、【Agent】【OpenCode】bash 工具提示词（持久化）（一）
人工智能·agent·opencode
lihaozecq2 小时前
从零实现一个 ReAct Agent Loop - 可中断、可流式、多模型支持
前端·agent·ai编程
大龄码农有梦想2 小时前
AI 智能体核心组件：Tool、MCP 与 Skills 的区别、标准与协同架构
人工智能·agent·智能体·ai工具·tool·mcp·skills
johnny2332 小时前
AI Coding Agent：OMO、Goose、Ralph Wiggum、x-cmd、HolyClaude、Halo
agent
AI玫瑰助手14 小时前
Agent架构：规划、记忆、工具、反思
人工智能·架构·agent
coderyi16 小时前
理解AI Code Agent
人工智能·agent
一只叫煤球的猫16 小时前
用AI写业务代码后，必须要坚持自己做的几件事情——过程控制
面试·ai编程·vibecoding
YuTaoShao16 小时前
Agent = Model + Harness：Cursor 如何持续打磨 AI 编程体验？
人工智能·ai·agent·harness
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03零基础教你claude code 接入 deepseek V404【AI】2026 年具身智能模型和世界模型总结05CC-Switch & Claude 基于 Linux 服务器安装使用指南06要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法07Windows端Codex接入第三方模型（DeekSeek，BaiLian)08Dirtyfrag漏洞：我花了一下午搞清楚这个Linux内核提权漏洞到底在搞什么092026年AI前瞻：量子AI、具身智能与科学发现的新纪元10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法