这段时间在过 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 分发回报到 inboxlocal本地运行的快速小工具型代理轻量工具与主线程交互不参与团队消息流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 --agentsClaude 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 收件箱消息流的真实观察跑通之后我观察到的消息流大概是这样的我把任务发给 leadlead 回复“收到我先让 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 回报后自主决定下一步动作只有最终汇总时才需要用户确认”。加了这句话之后整个团队的主动性会明显改善你会突然发现自己变成了那个只看周报的老板。
Agent Teams 架构解析：用收件箱机制实现多智能体高效协作
这段时间在过 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 分发回报到 inboxlocal本地运行的快速小工具型代理轻量工具与主线程交互不参与团队消息流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 --agentsClaude 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 收件箱消息流的真实观察跑通之后我观察到的消息流大概是这样的我把任务发给 leadlead 回复“收到我先让 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 回报后自主决定下一步动作只有最终汇总时才需要用户确认”。加了这句话之后整个团队的主动性会明显改善你会突然发现自己变成了那个只看周报的老板。
