文档大纲

一个人就是一支团队：Claude Code 代理团队（Agent Teams）实战完全指南

你有没有过这种时刻：一个任务明明可以拆成 3 块同时干，但 Claude Code 只能一块一块跑？等你等得花儿都谢了。

Claude Code 本身已经够强了，但当你遇到这种场景：

🔍 同一个 PR 想从安全、性能、测试覆盖率三个角度同时审查
🐛 一个诡异 Bug，可能有 5 个不同的根因方向，要并行验证
🧱 一个新功能要拆成前端、后端、测试三块独立实现

单线程的 Claude 会慢得让人抓狂。而 Agent Teams 就是为这种"多线并进"场景而生的——它能让多个 Claude 实例组成一支团队，并行探索、彼此通信、共享任务清单。

一、什么是 Claude 代理团队？

简单一句话概括：

一个 Claude 会话充当"团队负责人"（Team Lead），负责派活、汇总；多个 Claude 实例作为"队友"（Teammates），并行干活、互相通信。

每个队友都是一个独立、完整的 Claude Code 实例，有自己的 context window，能直接互相发消息讨论问题，而不是只能向"老板"汇报。

下面这张官方对比图能帮你直观理解它的架构：

（图：左侧是 subagents，全部结果回流到主代理；右侧是 agent teams，队友共享任务列表，直接互相对话。）

它的四大核心组件

组件	干什么的
Team Lead（团队负责人）	主 Claude Code 会话，负责派活、协调、汇总
Teammates（队友）	独立 Claude 实例，各自干活、各自有 context
Task List（任务列表）	团队共享的工作看板，任务有"待处理 / 进行中 / 已完成"三态
Mailbox（邮箱）	队友之间互相通信的消息系统

二、什么时候该用它？与子代理的对比

Claude Code 其实有两种并行方式——Agent Teams 和 Subagents。选错不仅慢，还浪费 token。

一张表帮你秒选

	Subagents（子代理）	Agent Teams（代理团队）
Context	自己的窗口，但结果回传主代理	完全独立，自己的 context
通信方式	只能向主代理汇报	队友之间直接互相发消息
协调机制	主代理统一管理	共享任务列表，自我协调
最佳场景	任务专注、只关心结果	需要讨论、协作、互相质疑的复杂工作
Token 成本	较低（结果汇总回主 context）	较高（每个队友都是独立实例）

强推使用 Agent Teams 的 4 个场景

🔍 研究与审查：多个队友从不同角度调查同一问题，然后互相挑战对方的发现
🧱 新模块或功能：每个队友独立负责一块，不互相干扰
🐛 竞争假设调试：队友并行测试不同理论，谁的假设被驳倒谁出局（科学辩论模式）
🌐 跨层协调：前端 / 后端 / 测试各派一个队友负责

千万别用 Agent Teams 的场景

❌ 严格的顺序任务（A 完成才能做 B）
❌ 编辑同一个文件（会互相覆盖）
❌ 任务之间强依赖

这种场景老老实实用单个会话或 subagents。

三、3 步开启你的第一个 AI 团队

Step 1️⃣：开启实验性功能

Agent Teams 默认是关闭的。打开 \~/.claude/settings.json，加入下面这段：

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

也可以直接在 shell 里 export：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Step 2️⃣：重启 Claude Code

让配置生效。重启后，Claude 就具备了"召唤队友"的能力。

Step 3️⃣：用自然语言"召唤"你的团队

不需要写复杂的命令，直接告诉 Claude 你想干什么就行：

我要设计一个 CLI 工具，帮开发者追踪代码里的 TODO 注释。
给我派 3 个队友，从三个角度一起探索：
- 一个负责用户体验（UX）
- 一个负责技术架构
- 一个扮演"反对者"，专门挑刺找问题

Claude 会自动：

建立一个共享任务列表
生成 3 个队友
给每个队友分配独立的探索方向
在他们完成时综合所有发现

启动后，终端会长这样

负责人终端底部会出现一个 Agent 面板，列出所有队友：

操作	按键
选择队友	`↑` `↓` 方向键
进入队友会话直接对话	`Enter`
中断队友当前工作	`Esc`
切换任务列表	`Ctrl+T`

四、玩转代理团队：6 个核心控制技巧

光会召唤还不行，你还得会"管团队"。下面这 6 个技巧是关键。

技巧 1：选择显示模式（in-process vs 分屏）

Agent Teams 支持两种显示模式：

模式	优点	缺点
In-process（默认）	所有队友挤在主终端，无需额外配置	不能同时看到所有输出
Split panes（分屏）	每个队友一个独立窗格	需要 tmux 或 iTerm2

# 命令行临时指定
claude --teammate-mode tmux

# 或写到 settings.json
{
  "teammateMode": "tmux"
}

技巧 2：精确指定队友数量和模型

不要让 Claude 自己决定规模，给它明确指令：

抽调 4 名团队成员并行重构这些模块。
每位成员分配 Sonnet 模型开展工作。

还可以在 /config 里设置默认队友模型，让所有队友都按某个模型启动。

技巧 3：要求队友先出方案、再动手

对于复杂或有风险的任务，让队友先"写计划"再"写代码"：

指派一名架构师重构认证模块。
要求其开展任何代码修改前，方案必须先行审批通过。

工作流程：

队友进入只读计划模式
完成后向负责人提交计划
负责人审阅，批准 / 拒绝并给反馈
拒绝后队友继续修改、重新提交
批准后才真正动手实施

你可以告诉负责人你的批准标准，比如：

"只批准包含测试覆盖的计划" 或 "拒绝任何修改数据库架构的方案"

技巧 4：随时直接找某个队友谈

每个队友都是一个完整的 Claude Code 会话，你可以直接找任何一个聊：

In-process 模式：在 Agent 面板选中队友 → Enter → 像平时和 Claude 聊天一样
Split-pane 模式：直接点队友的窗格

⚠️ 注意：当你查看某个 in-process 队友时，纯文本和 skills 发给该队友，但内置命令（如 /model）仍然作用在负责人身上。

技巧 5：用共享任务列表协调

任务有三种状态：待处理 → 进行中 → 已完成，任务之间还能设置依赖关系。

共享任务列表

📋 共享任务列表
状态	任务	备注
✅ 完成	设计 UX 流程
🔄 进行中	实现后端 API
⏳ 待处理	编写集成测试	← 依赖 API 完成
⏳ 待处理	写用户文档

两种分配方式：

负责人分配：你直接告诉负责人"把任务 X 派给 researcher"
自我认领：队友空闲后自己挑未分配的任务（用文件锁防竞争）

技巧 6：用 Hooks 强制质量门

如果你想自动把关，可以用 Hooks：

Hook	触发时机	用途
`TeammateIdle`	队友准备空闲时	退出码 2 → 阻止空闲，给反馈
`TaskCreated`	任务被创建时	退出码 2 → 阻止创建，强制修改
`TaskCompleted`	任务被标记完成时	退出码 2 → 阻止完成，要求补充

举个例子：用 TaskCompleted hook 强制队友写完测试才能标记完成。

五、幕后揭秘：代理团队到底是怎么运转的

这一节稍微硬核，但你只要理解下面 3 件事就能完全 hold 住。

5.1 团队是怎么"组起来"的

当你让 Claude 派队友时：

主会话自动成为 Team Lead
每个队友获得自动生成的名字（基于会话 ID 前 8 位）
Claude Code 自动在本地建两个目录：

目录	作用	何时清理
`\~/.claude/teams/{team-name}/config.json`	团队运行时状态	会话结束自动清理
`\~/.claude/tasks/{team-name}/`	任务列表数据	持久保留（用于 `/resume`）

⚠️ 不要手动编辑 config.json！那是运行时状态，你改了会被覆盖。

5.2 队友之间的通信机制

自动消息传递：队友发消息无需负责人轮询
空闲通知：队友完成工作会自动通知负责人
共享任务列表：所有代理都能看到彼此状态
按名寻人：用 SendMessage 按名字定向联系某人

5.3 权限继承与隔离

队友从负责人继承权限设置
负责人用了 --dangerously-skip-permissions，所有队友也是
但队友不能代表你批准权限——所有权限请求都会冒泡到负责人
一个队友被拒的操作不能转给其他队友绕过

六、3 个真实场景，手把手带你跑一遍

理论讲够了，下面来点真实的。

场景 1：并行代码审查 🔍

安排三名团队成员评审142 号 PR：
一人重点核查安全相关影响
一人评估性能影响
一人校验测试覆盖完整性
要求各人独立评审并输出评审结论。

为什么有效：三个审查者从同一个 PR 工作，但应用不同的"过滤器"。负责人最后综合三份报告。

场景 2：用竞争假设调查 Bug 🐛

用户反馈应用发送单条消息后就退出，无法保持连接。
指派 5 名 Agent 成员分头调研不同猜想。
安排成员相互交流，以类似科学辩论的形式，尝试证伪彼此的推断。
将最终达成的共识更新至问题调研文档。

关键机制：要求队友互相反驳对方的理论，而不是只调查自己那一摊。锚定效应被打破，存活下来的假设更接近真相。

场景 3：跨层新功能开发 🧱

指派 3 名成员搭建通知系统：
后端成员：设计接口与数据库表结构
前端成员：开发通知界面组件
测试成员：编写集成测试
各成员权责对应的文件相互独立，不存在职责交叉。

关键点：每个队友明确拥有不同的文件集合，避免文件冲突。

七、5 条经验总结（最佳实践）

✅ 经验 1：给队友足够的 context

队友会自动加载项目的 CLAUDE.md、MCP servers、skills，但不会继承负责人的对话历史。

所以你需要在派活时把关键信息塞进去：

指派一名安全评审人员，并下发如下提示词：
"审查 src/auth/ 目录下认证模块存在的安全漏洞。
重点关注令牌处理、会话管理以及输入校验。
本应用采用存放于 httpOnly Cookie 中的 JWT 令牌。
所有发现问题均需标注风险等级并上报。"

✅ 经验 2：团队规模不要贪多

规模	适用场景
3-5 个队友	绝大多数工作流的最佳甜蜜点
1-2 个队友	不如直接用 subagents
6+ 个队友	协调成本剧增，收益递减

每个队友有 5-6 个任务最舒服，能保持高效又不至于过载。

✅ 经验 3：任务大小要合适

太大	太小	刚好
队友长时间工作无检查，浪费风险高	协调开销 > 收益	自包含单元，如一个函数、一个测试文件、一份审查

✅ 经验 4：避免文件冲突

两个队友编辑同一个文件会互相覆盖。派活时明确文件归属：

- 后端成员：仅可修改 src/api/* 与 migrations/* 目录代码
- 前端成员：仅可修改 src/components/* 与 src/pages/* 目录代码
- 测试成员：仅可修改 tests/* 目录代码

✅ 经验 5：保持监督，及时纠偏

时不时切到队友会话看看进度
发现方向错了立刻发消息修正
别让团队无人值守跑太久

💡 如果你发现负责人开始自己动手而不是等队友，立刻喊停： "text Wait for your teammates to complete their tasks before proceeding "

八、踩坑速查：常见问题与排查

❌ 队友根本没出现？

检查 in-process 模式下，队友列表在提示输入下方的 agent 面板
检查任务是否够复杂（太简单的任务 Claude 不会派队友）
分屏模式要确认 tmux 装好了：which tmux
iTerm2 模式要装 [it2 CLI](https://github.com/mkusaka/it2) 并启用 Python API

❌ 队友在错误后就停了？

进入队友会话（in-process 按 Enter，分屏点击窗格），然后：

直接给新指令
或者重新派一个替补队友

从 v2.1.198 起，来自负责人的消息会唤醒等待重试的队友，不需要等完整重试延迟。

❌ 权限弹窗太多？

在生成队友前，先在 [权限设置](https://code.claude.com/docs/zh-CN/permissions) 里预批准常见操作。

❌ 负责人过早关闭？

直接告诉它继续：

继续推进当前工作，等待所有成员完成任务。

❌ tmux 会话没清掉？

tmux ls                    # 列出现存会话
tmux kill-session -t <session-name>   # 手动清理

九、当前已知的限制（避坑必读）

Agent Teams 还是实验性功能，这几个坑你必须心里有数：

限制	影响	应对
In-process 队友不支持 `/resume` `/rewind`	恢复会话后队友消失	告诉负责人生成新队友
任务状态可能滞后	依赖任务卡住	手动更新或让负责人推动
关闭比较慢	队友要等当前请求完成	耐心等待，别强杀
每个会话一个团队	不能跨会话共享团队	接受现状
不能嵌套	队友不能再派队友	只让负责人管团队
负责人是固定的	不能"提拔"队友	接受现状
权限在生成时确定	生成后改权限生效，但生成时不能按队友设置	—
Windows Terminal 不支持分屏	只能用 in-process	切到 WSL 或 macOS

💡 好消息：队友会读取他们工作目录下的 CLAUDE.md，所以项目级指导一样生效。

写在最后

Agent Teams 不是一个"啥都能并行"的黑科技——它有明确的适用场景和成本代价。

总结成一句话：

🔑 当任务真正能并行、队友能独立运作、需要协作讨论时，上 Agent Teams；否则老实点用单个会话或 subagents。

记住这套决策树：

从代码审查、竞合假设调查这类边界清晰的任务开始尝试，是最稳妥的入门姿势。

阅读量： 302