这段时间在过 learn-claude-code 系列，前面几章还在研究怎么把单个 Agent 的 system prompt 写好、怎么挂工具，到 S09AgentTeams 这节突然就上强度了：你可以在项目里直接拉起一个 Agent 团队，一个 Lead 负责拆解任务和汇总结果，下面挂多个 Teammate 各自干活，Agent 之间的沟通全部走收件箱（inbox）方式。第一次跑通的时候我还挺意外，因为这种“一个项目管理 + 多个执行者”的结构，比我想象中更像一个真实的小组。这篇文章就围绕 Agent Teams 的架构、inbox 通信机制和配置细节，把我在 S09 里的实操经验和踩坑记录分享出来。如果你正在做 Agent 开发，或者搞不明白多智能体协作到底怎么落地，这篇应该能帮你省不少时间。
1. 为什么需要 Agent 团队：单 Agent 模式的三个致命瓶颈
1.1 上下文窗口是单 Agent 的硬天花板
所有用过大模型编程助手的人都体会过一件事：上下文窗口是有限的。哪怕模型窗口再大，塞满历史消息后，前面的内容要么被压缩、要么被遗忘。单 Agent 模式下，你让它做一件复杂任务——比如先摸清整个代码库的模块结构，再改某个核心函数的实现，然后跑测试，最后写文档——这些步骤的所有对话记录、工具输出、中间结果都会堆积在同一个上下文里。任务越长，早期信息被挤掉的速度越快，到后面它就“忘了”自己一开始定的方案。
Agent Teams 把这个问题拆开了。每个 Teammate 是独立的上下文，只处理自己那一块任务的信息。Lead 不需要记住每个执行细节，它只要掌握任务分解和汇总；Teammate 也不需要考虑全局，它只关心自己被分配的子任务。这就像公司里写代码的人不会同时去记财务账，每个人的工作记忆都留给自己的职责范围，协作效率自然上去了。
1.2 职责和工具混在一起，安全性和可靠性都很差
单 Agent 模式还有个隐蔽问题：工具权限没办法做最小化。你给一个 Agent 同时配上“读代码”“写文件”“执行 shell 命令”“调用外部 API”这些工具，它在执行过程中到底用哪个，完全由模型自己判断。一旦某个环节判断出偏差，比如本来只让它读代码，它却执行了一条危险命令，问题就来了。
在 Agent 团队里，工具是跟着角色走的。负责代码审查的 Teammate 可以只挂只读工具，负责写测试的 Teammate 可以只挂编辑器和命令行工具，负责发邮件的 Teammate 可以只挂邮件相关工具。这样做的好处是双重的：第一，每个 Agent 的注意力更集中，不会被无关工具干扰；第二，权限边界更清晰，就算某个 Agent 突然“走偏”，它手里也没有能造成大破坏的工具。这也是我实操中最喜欢的一点，它让“用一个 Agent 团队干活”这件事变得可以放心交给流程去管。
1.3 串行是单 Agent 的天性，并行是团队的红利
还有一个非常实际的原因：单 Agent 只能一条线推进。它正在跑测试的时候，不能让另一个“分身”同时去做代码审查。复杂项目里，很多任务其实是互相独立的——比如前端代码审查、后端接口梳理、文档骨架搭建，这三件事完全可以同时做。团队模式下，Lead 可以把这三个任务分别发给三个 Teammate，它们并行执行，最后把结果汇总回来。
这里顺带回答一个经常被问到的问题：Agent 开发到底是做什么的？本质上就是把“角色、目标、工具、通信”这四个要素设计清楚。Agent Teams 就是 Claude Code 给出的一套具体编排实现，让多智能体协作不用从零造轮子。后面我会详细讲这套编排是怎么工作的。
2. 团队架构拆解：Lead、Teammate 与收件箱通信
2.1 三种角色类型：lead、teammate、local
在 Agent Teams 配置里，一个 Agent 的身份由它的 mode 字段决定，常见的有三种：
| 类型 | 核心职责 | 典型工具 | 交互方式 |
|---|---|---|---|
| lead | 接收用户任务，拆解分配，汇总结果 | 规划类、消息发送类 | 与用户对话，给 teammate 发消息 |
| teammate | 执行具体子任务，汇报结果 | 按需配置的读/写/命令工具 | 接收 lead 分发，回报到 inbox |
| local | 本地运行的快速小工具型代理 | 轻量工具 | 与主线程交互，不参与团队消息流 |
Lead 更像一个项目经理，它不一定要自己干活，但一定要把任务拆清楚。Teammate 则是执行者，每个人只负责自己擅长的那一块，做完之后把结果写成一封“邮件”投递到 Lead 的收件箱。Local 适合那些不需要复杂协作的小任务，比如查一下系统环境变量、跑一个简单脚本，我在实际中通常不会让 local 进核心流程。
2.2 收件箱（inbox）消息机制是怎么跑的
团队协作的核心是通信。Agent Teams 默认使用收件箱（inbox）机制：Agent 之间不直接共享上下文，也没有“全局变量”，一切信息传递靠发消息。消息的投递方向通常是 Teammate 给 Lead 回报，或者 Lead 给 Teammate 分派任务，也可以设置成指定接收人。
这个设计很像现实中的邮件系统。发消息的一方把消息丢进对方的 inbox，对方在合适的时候读取并处理，双方不需要同步等待。这种异步模型有个非常好的特性：Agent 之间解耦了。Lead 发完任务就去处理其他事情，不用一直傻等 Teammate 跑完才继续；Teammate 收到任务后自己慢慢做，做完再把结果丢回去。对于跑长任务的场景，这种非阻塞的协作方式明显比“函数调用式”的同步等待更优雅。
2.3 用户如何参与对话与 @ 提及
在团队模式下，用户的默认消息是发给 Lead 的。你可以直接用自然语言给 Lead 下达任务，比如“安排一个 teammate 去检查这个模块的测试覆盖”。如果你想绕过 Lead 直接跟某个 Teammate 对话，可以用 @ 提及的方式，比如“@code-reviewer 你看一下 src/utils 的代码风格”。这样会把这个 Teammate 拉进直接对话，它的回复会直接显示给你，而不需要经过 Lead 转达。
我在实际使用中的体会是：日常小任务直接 @ 对应 teammate 效率最高；只有在任务比较综合、需要拆解分派的时候，才让 Lead 来调度。这个使用习惯能让团队模式的体验完全不一样——它不是逼你每件事都走一个“项目经理”，而是把“管流程”和“干小事”两种场景都覆盖到了。
2.4 这种设计解决了什么问题
收件箱通信最大的价值在于可观测性和可恢复性。你可以通过/agents命令随时查看当前团队里每个 Agent 的状态：谁在忙、谁空闲、谁发了消息但还没被读取。任务出错的时候，也能比较容易地定位是哪条消息、哪个 Agent 环节出了问题。相比之下，如果把所有 Agent 塞进同一个上下文里共享一切，那协作过程就变成了一锅粥——你根本分不清信息是谁提供的，也无法恢复某一步的状态。
当然，这种架构也不是没有代价。消息通信有额外的性能开销，Agent 之间不能实时“看见”对方的中间状态，必须通过显式的消息同步。这就要求我们在设计每个 Teammate 的 system prompt 时，明确约定消息的格式和内容。这一点我后面会专门展开。
3. 一步步配置一个最小 Agent 团队
3.1 目录结构与配置文件
在 Claude Code 里，Agent 的定义走.claude/agents/目录（不同版本细节有差异，但思路一致）。每个 Agent 是一个 Markdown 文件，文件名就是 Agent 名，文件头部用 YAML frontmatter 声明元信息，正文则是这个 Agent 的 system prompt。一个最小团队大概长这样：
.claude/ └── agents/ ├── lead.md ├── explorer.md ├── tester.md └── reviewer.md这里我把团队设计成四类：一个 Lead 负责统筹，三个 Teammate 分别负责代码库探索、测试编写、代码审查。你可以根据自己的项目需要随意增减。
3.2 Lead Agent 的配置示例
先看 Lead 的配置文件。我习惯把 Lead 的 prompt 写得“软”一点，因为它的职责就是拆任务、派活、汇总，不涉及具体技术实现：
--- name: lead description: 项目团队的主控 Agent，负责拆解任务、分派给 teammate 并汇总结果。 mode: lead tools: Read, Grep, Glob, Send Message --- 你是一个项目小组的 Lead，负责统筹整个任务的推进。 工作流程： 1. 收到用户任务后，先拆解成可并行执行的子任务。 2. 通过 Send Message 把子任务分派给对应的 teammate。 3. 收到 teammate 的回报消息后，检查结果是否满足要求。 4. 汇总所有子任务的结果，给用户一份完整的结论。 5. 发现 teammate 任务结果不达标时，直接发回消息要求补充或重做。 注意： - 不要自己接手 teammate 的具体执行工作，你的价值在协调。 - 每次分派任务时，明确告诉对方：任务背景、期望输出、回报格式。这里有个经常被忽略的点：Lead 的 prompt 里一定要写明“你可以在收到回报后自主决定下一步”。如果不写，模型会倾向于什么事都等用户确认，整个团队就变成了“每走一步都要问一下老板”的低效小组。我在第五部分还会专门说这个问题。
3.3 Teammate Agent 的配置示例
再来看一个 Teammate 的配置，以负责代码库探索的 explorer 为例：
--- name: explorer description: 负责扫描代码库、梳理模块结构、输出依赖关系。适用于任务开始前的调研阶段。 mode: teammate tools: Read, Grep, Glob --- 你是一个资深代码库分析师，负责在团队任务中完成代码调研工作。 职责边界： - 只负责读取和分析代码，不修改任何文件。 - 输出内容为文本形式的模块结构说明，包含：关键目录、核心文件、模块间依赖。 - 完成调研后，把结果通过消息发送给 lead。 回报格式： - 模块清单 - 每个模块的关键文件路径 - 模块之间的依赖关系 - 你发现的潜在问题点 注意： - 你只挂了只读工具，不要尝试执行写操作。 - 如果任务描述不清晰，先给 lead 发消息确认，不要自行假设。注意 explorer 的 tools 只给了 Read、Grep、Glob，没有写文件工具也没有 shell 工具，这就是角色权限分离的实际落地。tester 和 reviewer 的配置思路类似，区别在于工具上 tester 需要加执行测试的命令工具，reviewer 则需要读代码和查看测试报告的工具。
3.4 启动团队与会话管理
配置文件写好之后，启动方式很简单：在项目目录下运行claude --agents，Claude Code 会自动读取.claude/agents/下的 Agent，并按照 mode 字段把团队串起来。如果你已经在会话里了，也可以用/agents命令查看当前团队状态、某个 Agent 是否空闲、最近的消息记录等。
我多说一句，启动后第一次跟 Lead 对话时，要给它一个明确的上层目标，而不是让它“看着办”。实测下来，“请让我先了解代码库结构，然后为 utils 模块补齐测试，最后让 reviewer 检查一轮”这种描述，比“帮我优化项目”要高效得多——Lead 做拆解的前提是它知道最终要交付什么，否则它自己也会迷茫。
3.5 为不同 Teammate 配置不同模型
Agent 定义里可以给单个 Agent 指定 model 字段。团队模式下这个能力很实用：负责探索和梳理的 explorer 可以用速度更快的模型，负责最终审查的 reviewer 可以用推理能力更强的模型。这样既控制了成本，又保证了关键环节的质量。
我现在的团队就是这么配的：explorer 用轻量模型，tester 用中等型号，reviewer 用最强型号，Lead 用中等型号。实测下来费用比“全部用最强模型”低不少，质量却没有明显下降——因为真正需要深度推理的环节本来就不多，把它们集中到 reviewer 这一个 Agent 身上就够了。
4. 实测：用 Agent 团队跑一个“代码库分析与补测试”任务
4.1 任务设定与分工设计
为了验证这套配置，我拿了一个内部小项目做实验。这是一个 Python 工具库，大概十几个模块，测试覆盖不高。我给团队下达的目标是：“梳理一下项目现状，给核心模块补一批单元测试，最后让 reviewer 检查一遍。”
分工设计如下：
- explorer：先扫描全部代码，输出模块地图和依赖关系。
- tester：基于 explorer 的模块地图，挑出 3 个核心模块补测试。
- reviewer：检查测试质量和覆盖率，给出改进建议。
- lead：全程统筹，负责转达阶段性成果。
这个分工本身就是一次对 Agent 开发的练习：核心不是写代码，而是把目标拆成有明确边界、有明确输入输出、可以并行执行的子任务。
4.2 收件箱消息流的真实观察
跑通之后，我观察到的消息流大概是这样的：
- 我把任务发给 lead，lead 回复“收到，我先让 explorer 做一次代码梳理”。
- lead 给 explorer 发消息，内容是任务说明和要求的输出格式。
- explorer 开始扫描代码，完成后给 lead 的 inbox 投递了一封“调研报告摘要”。
- lead 读完后，把摘要整理了一下，给 tester 发消息：“这是模块地图，请优先补 utils 和 parser 两个模块的测试。”
- tester 写测试、跑测试，然后回报覆盖率结果。
- lead 收到 tester 的结果后，让 reviewer 做一轮检查。
- reviewer 看完代码后回报发现的问题清单。
- lead 把整个链条的结果汇总成一份最终报告给我。
整个过程看着像一个微型项目管理工具：有任务分派、有阶段汇报、有质量把关。最关键的是，这些 Agent 之间的通信都是通过收件箱异步完成的，每一步的产物都有消息记录，我可以通过/agents看到当前卡在哪一步、谁还没回复。
4.3 并行与串行的取舍
这个流程里，explorer 必须先完成，tester 才能开始，这属于强依赖的串行环节。但 reviewer 的检查其实可以更早开始——它在 explorer 梳理完代码结构之后，就可以先看代码风格和潜在问题，不必等测试写完。在实际运行中，如果你对任务足够熟悉，完全可以手动 @reviewer 让它提前介入，这样能进一步压缩整体时间。
我的结论是：Agent Teams 不是“无脑并行”，它只是在架构上给了你并行的能力，具体怎么编排、哪些步骤并行哪些串行，仍然需要人来设计。Lead 的 prompt 里写的“工作流程”越清楚，团队跑起来就越接近你想要的效果。
4.4 成本与上下文管理观察
这次实验还有一个意外的收益：整个流程跑下来，没有出现“上下文爆了”的情况。以前用单 Agent 跑这种任务，到后面它经常把前面的调研结果忘掉；现在 explorer 的调研结果以摘要形式固化成消息，tester、reviewer 各拿各的输入，互不干扰。每个 Agent 的上下文都是按需加载的，信息密度反而更高。
代价是 token 消耗会增加一些——因为消息传递、多次启动 Agent 都有额外开销。实测下来，同样一个任务，团队模式比单 Agent 模式大概多花 20% 到 30% 的 token，换来的是更稳定的质量和更强的可观测性。对于任务复杂、结果要求可靠的项目，这笔开销我认为完全值得。
5. 常见问题与排查技巧实录
5.1 任务卡在 Lead 上，Teammate 一直没被调度
这是我遇到最多的一个问题。现象是用户给 Lead 下了任务，Lead 回了一句“好的，我来安排”，然后就没了下文。排查后发现，原因往往是 Lead 的 prompt 没有写清楚“你有权主动向 teammate 发消息”。模型默认会倾向于等待用户下一步指令，即使它权限上有发消息工具，也不会主动使用。
解决办法有两个：一是在 Lead 的 prompt 里明确写“收到任务后，你必须先拆解并立即分派给队友，不要等待用户确认”；二是检查 teammate 的 description 是否足够具体，让 Lead 能判断该把这个任务派给谁。description 写得越精确，Lead 的调度准确率越高。
5.2 收件箱消息没人读，任务卡在中间环节
第二种常见问题是消息发出去了，但接收方迟迟不处理。我遇到过一次：tester 给 reviewer 发了消息，但 reviewer 一直没有回应，整个流程卡死。用/agents查看后才发现，reviewer 的 description 写得太笼统，导致团队调度器没有把它正确纳入当前任务的执行链，它可能根本没有被“唤醒”。
建议在配置 teammate 时，把 description 写成“在什么场景下、接收什么任务、输出什么”的三段式。比如 reviewer 可以写：“当 lead 需要代码质量检查时被调用，接收测试结果和代码路径，输出问题清单和改进建议。”这样消息投递的命中率会高很多。
5.3 上下文还是会爆，怎么办
虽然每个 Teammate 的上下文是独立的，但如果某个 teammate 被分配了大而全的任务，它自己的上下文照样会爆。比如我把“补全所有模块的测试”直接扔给 tester，它跑一会儿就晕了。
解决思路是继续拆。把一个 teammate 的任务拆成多轮，每轮处理一个模块，处理完把结果以摘要形式发送给 Lead，然后清空该 teammate 的上下文，再开始下一轮。换句话说，Agent 团队不是只能有一层，必要时可以做成“Lead -> 子 Lead -> Teammates”的多层结构，让每一层的上下文都保持小而专注。
5.4 工具权限给太宽，差点出事
这是我踩过的最值得分享的一个坑。早期配置 tester 的时候，我图省事给它挂了写文件工具加 shell 工具，它写测试写到一半，顺手执行了一条清理操作——本来想清理临时文件，但路径写错，差点删掉测试目录。虽然最终没有造成实际损失，但给我提了个醒：工具的权限边界必须严格按角色来。
现在我的原则是：默认最小权限，逐项按需追加。只负责读代码的，绝不挂写工具；需要执行测试的，只挂执行测试相关的命令，不挂文件删除之类的危险操作。这不仅是安全问题，也是让模型“少分心”的重要手段——工具列表越短，模型越清楚自己该干什么。
5.5 什么时候不应该用 Agent 团队
最后一定要说反过来的场景。如果你只是改一个文件的几百行代码，或者做一次简单的问答，单 Agent 模式完胜：启动快、省 token、没有通信开销。Agent 团队适合的是中等以上复杂度、有明确可拆解阶段、需要多个角色协作的任务。如果任务本身是线性强依赖、且单 Agent 就能跑完，硬上团队模式只会浪费时间。
6. 从 Agent Teams 看智能体开发：框架、编排与 skill 的边界
6.1 Agent Teams 是编排层，不是新框架
很多人在了解 Agent 开发时会混淆“框架”和“编排”这两个概念。Claude Code 本身是一个 harness（执行环境），它负责模型调用、工具执行、会话管理等基础设施；Agent Teams 则是在这个 harness 之上的一种编排模式，定义了角色怎么划分、消息怎么投递、流程怎么串起来。你不需要额外引入 Agent 框架，所有协作逻辑都在配置文件和 system prompt 里完成。
6.2 skill 与 Agent 的区别
还有一个常见的疑问：skill 是什么，跟 Agent 有什么区别？我的理解是：skill 是给 Agent 用的“技能包”，相当于能力组件，比如一个“生成单元测试”的 skill 封装了 prompt、工具、步骤；Agent 则是承担某个角色的执行主体，它可以拥有多个 skill。在团队模式下，你可以给 tester 挂上“生成单元测试”的 skill，给 reviewer 挂上“代码审查清单”的 skill，这样它的行为质量会进一步提升。
6.3 对做 Agent 开发的人有什么参考价值
如果你正在设计自己的 Agent 产品或者自动化系统，Agent Teams 这套“Lead + Teammates + 收件箱”的模式很有参考价值。它证明了几个通用原则：上下文隔离比共享更可靠；消息通信让协作过程可观测；角色权限分离让系统更安全；并行需要显式设计而不是自动获得。这几个原则不限于 Claude Code，任何多智能体系统都绕不开。
到这里，S09AgentTeams 这节课的核心内容基本就捋完了。我在实际过 learn-claude-code 的过程中，最大的感受是：Agent 团队真正解决的并不是“能不能多智能体协作”的问题，而是“让复杂任务变得可控”的问题。收件箱通信机制看起来不起眼，但正是这种显式的消息传递，让每个 Agent 的输入输出都清清楚楚，出了问题也能顺着消息流回溯。最后再分享一个小技巧：如果你的 Lead 总是“太礼貌”，习惯等你下指令才行动，试着在它的 prompt 里加一句“你有权在收到 teammate 回报后自主决定下一步动作，只有最终汇总时才需要用户确认”。加了这句话之后，整个团队的主动性会明显改善，你会突然发现自己变成了那个只看周报的老板。
