我自己在终端里天天用 Claude Code 写代码，单 Agent 用久了就会发现一个问题：活一多、项目一复杂，那个上下文窗口就像个越堆越满的垃圾桶，前面改的需求后面就忘，修了 A 文件的 bug 又把 B 文件的结构给带崩了。后来我把任务拆给多个 Agent 协作干，情况才真正好转。这篇我就拿 Claude Code 里的 agentTeams 机制开刀，从原理拆到实操，把多 Agent 协作到底是怎么跑起来的讲明白。
适合谁看？如果你正在用 AI 编程工具，但在大项目、跨模块改造或者复杂重构的时候总觉得单个 Agent 力不从心，这篇文章可以给你一套直接能用的做法。我会把架构逻辑、配置写法、任务拆分的原则、踩坑记录全部交代清楚，你照着敲一遍就能上手。
TAG: Claude Code, agentTeams, 多Agent协作, AI编程, 任务编排, LLM上下文管理
1. 为什么单 Agent 干活会卡壳：多 Agent 协作要解决的真实痛点
先说个亲历的场景。有个模拟项目 X，是一个跨平台商城系统，后端用 Go 写订单模块，前端用 React 写商品页，中间还有一层 Python 做推荐服务。以前直接用 Claude Code 干这种活，我把需求一股脑丢进去，它会吭哧吭哧写，但写到三千行之后就开始“失忆”——前面约定的接口字段名忘了，自己改过的数据模型也记不清了，经常出现前后自相矛盾。这不是工具笨，而是单 Agent 的结构决定的。
单 Agent 只有一个上下文窗口，所有信息都塞在上面。它能承载的 token 有限，短任务没问题，长任务、大项目一撑就爆。更麻烦的是，它分不清主次。主需求是“改订单状态机”，但顺手翻到用户头像组件觉得也该重构，一下注意力就散了，主线任务反而做不完整。这就是典型的坏味道：单个 Agent 既当项目经理又当搬砖工，还得自己记所有历史，忙不过来。
agentTeams 解决的核心问题，就是角色分权 + 上下文隔离。它相当于把一个超级大脑拆成一支队伍：一个主 Agent 负责规划拆解，多个子 Agent 各自领一块任务并行干活，各自维护自己的上下文。任务之间通过明确的消息边界传递结果，而不是所有信息都挤在一个上下文里互相污染。
我用了一个很生活化的类比：单 Agent 像一个人又要写需求文档又写代码又测试，上下文就是他的工作台，东西堆多了找不到，传真机还只有一台。agentTeams 像一个小团队：产品经理拆任务、开发各写各的模块、测试单独跑用例，每人只有自己桌面上的资料，需要协作就通过标准接口传文件，互不干扰又互相衔接。
明白了它解决什么，再看内部机制就顺了。多 Agent 协作不是简单开几个线程各写各的，背后需要一整套编排、通信和上下文管理机制。下面我把它的核心原理拆开讲。
2. agentTeams 核心原理拆解：编排、上下文与任务契约
2.1 整体架构：谁在指挥，谁在执行
我在实际使用中，把 agentTeams 的架构理解成三层：编排层、执行层、共享层。
编排层是主 Agent，它不直接写业务代码，角色更像技术组长。输入需求后，它负责做三件事：拆任务、派活、收结果。拆任务的时候它会分析代码库结构，找出模块边界和依赖关系，决定哪些任务能并行、哪些必须串行。派活的时候它把每个子任务连同必要的上下文片段一起打包给子 Agent。收结果的时候它负责把各模块的产出合并，解决接口不匹配的问题。
执行层是若干子 Agent，每个子 Agent 领到自己的任务包，在独立上下文里专注工作。它们不关心别的模块在干什么，只需要对自己负责的输入输出契约负责。这种设计让每个 Agent 都能在小而精的上下文里跑，token 压力小，理解能力强，干活的准确性明显提升。
共享层则负责状态同步和产物管理。这个层通常是文件系统、git 分支或者专门的 artifact 存储。子 Agent 把产出写到共享层，编排层从这里收集并校验。共享层的设计决定了 Agent 之间的耦合度，耦合度太低不行，太高又回到“所有信息挤一起”的老路。
2.2 上下文隔离与共享：为什么这是生死线
多 Agent 系统最容易出问题的就是上下文。一个子 Agent 的任务是“给订单服务加一个取消接口”，它需要知道订单模型的字段、路由注册方式、测试规范，但不需要知道推荐服务的协同过滤算法。如果这些它都扛着，上下文里全是噪音，模型注意力被分散，代码质量必然下降。
所以 agentTeams 在设计上强制做上下文预算。每一个子任务都带一份精简后的上下文包，里面只包含：任务描述、输入数据结构、输出契约、相关文件路径、如果涉及跨模块依赖，再附上依赖模块的接口签名。这些东西加一起可能才几千 token，比单 Agent 扛着整个项目要轻两个数量级。
共享机制也分两层。第一层是共享的代码仓库，子 Agent 的任务落盘就是一套代码变更，最终由编排层校验 git diff 的完整性和一致性。第二层是共享的消息队列，子 Agent 可以往队列里投递“我完成了一项变更，接口如下”的通知，编排层收到通知后决定下一步派发什么任务。这个队列用的是 Claude Code 底层的消息路由机制，不需要外部消息中间件。
我用下来最大的心得体会是：上下文包做得好不好，直接决定任务成败。上下文给多了，token 烧得快还容易干扰；给少了，子 Agent 拿不到必要信息，输出彻底跑偏。这个“度”需要通过几次试跑来校准，没有一劳永逸的公式。
2.3 任务分解与依赖管理：让子任务能并行还不打架
一个需求能不能高效并行，取决于编排层的拆分水平。常见的错误拆分是“按文件拆”，把 A 文件分给 Agent1，B 文件分给 Agent2，结果 A 文件里引用了 B 文件的接口，两个 Agent 互相等，最后编排层合并时发现接口对不上，返工成本极高。
正确的拆分思路是按“契约边界”拆。比如一个商城需求，可以拆成三块：订单模块的状态机改造、支付回调接口对接、前端结算页联调。这三块的接口契约明确，订单模块定义回调数据结构，支付模块按这个结构实现，前端页面对接支付回调的返回值。这样三个 Agent 之间没有共享内存，只有接口依赖，可以安心并行。
具体到编排逻辑，agentTeams 分两类依赖关系。第一类是数据依赖，即 Agent2 的输入是 Agent1 的输出，必须串行执行。第二类是资源依赖，两个 Agent 都要改同一个文件，那也是冲突，必须串行。识别依赖关系后，编排层会生成一张任务图（不是方便面加点，不展开画图），按图依次派发没有依赖的任务，有依赖的等前序完成后再派发。
我也踩过拆分太细的坑。任务拆到三十个以上，光合并成本就比单个 Agent 直接干还高。后来一个自己的经验准则：一个子任务的产出若少于 50 行代码，说明拆太碎了，应该合并掉。合理的粒度是“一个任务能独立完成一个完整的功能点，且产出可以被单独 review”。
2.4 多 Agent 的通信协议：结构化消息而非自然语言
子 Agent 之间不直接对话，它们传的结构化消息，这在 agentTeams 里叫 contract message。每条消息包含四个部分：type（事件类型，比如 task_complete、interface_change、need_review）、context（必要的数据引用）、payload（具体内容，通常是文件路径或接口定义）、callback（期望的后续动作）。消息看板把 route 分成三个管道：roster 存 roster（在 agentTeams 里叫 roster），blocker 存阻塞事件，done 存完成通知。
编排层通过监听消息队列做决策，一旦发现某个任务抛了 blocker，就会重新拆任务或者换一个子 Agent 再试。信号传递方法本身不神奇，神奇的是结构化约束带来的稳定性。自然语言消息传十次就有三次有歧义，结构化消息字段定死，解析器解析稳定可靠。
2.5 成本与并发：为什么多 Agent 反而能省钱
并发听起来会多烧 token，实际上多 Agent 用好了反而更省。原因是上下文高度聚焦，单个子 Agent 执行效率高，很少因为上下文混乱而反复重写。单 Agent 干大项目经常是“写到一半发现前面错了，自我修复十几轮”，每一轮都是一次大上下文重读，token 烧得飞快。agentTeams 里每个子任务上下文固定，干完就结束，基本不回头。
并发数量上我也做过的实验，我自己跑过 3 个子 Agent、6 个子 Agent、12 个子 Agent。3 个最稳，6 个在任务边界清楚时效率明显上升，12 个就开始频繁出现资源冲突和编排层决策过载，收益不增反降。经验值是：个人电脑上跑复杂项目，并发控制在 4~6 个能效最理想，超过 8 个基本都是虚火。
3. 环境准备：把 agentTeams 跑起来的前置条件
3.1 安装与基本配置
在动手配置 agentTeams 之前，你得先有一个能跑 Claude Code 的环境。这个过程不复杂，但有几个小细节直接影响后续稳定性。我建议用 Node.js 16 以上版本，装完后在终端里执行安装命令，把 Claude Code CLI 拉起来。首次运行它会要求登录 API 账号，这一步不需要额外申请权限，用的时候注意配额就行。
装好后建议先把CLAUDE_CODE_CONFIG_DIR环境变量设成一个专门目录，这个目录专门放配置和运行日志。没设的话它会默认散落在系统目录里，后面对多 Agent 调试不方便。同时检查你的终端是否具备全屏渲染能力，底层渲染跑不动多面板时，Agent 状态看起来会非常奇怪。
3.2 agentTeams 配置文件结构：先看懂再上手
agentTeams 的核心配置入口是一个 YAML/JSON 文件，我现在一般叫它team_config.json，放在项目根目录。它定义了一个团队配置对象，主要字段我用下来是这样：
| 字段 | 作用 | 我的推荐设置 |
|---|---|---|
| team_name | 团队名称 | 项目名加后缀，比如order_team |
| orchestrator | 定义编排主 Agent 的角色、模型、行为 | 用默认，负责规划，不碰代码 |
| agents | 声明子 Agent 的蓝图列表 | 3~6 个，每个带明确职责 |
| tasks | 初始任务队列，从需求描述开始 | 只有一个初始任务，编排层会去拆它 |
| artifacts | 定义产物路径与校验规则 | 统一放.agent/artifacts/ |
| contracts | 声明跨 Agent 的接口契约 | 越详细越好，减少合并期返工 |
写配置文件最大的一个注意点：不要把任务细节写进去。配置文件只描述团队结构、角色边界和接口契约，具体任务应该由主 Agent 在运行中途按需拆解。如果你把所有任务都写死，主 Agent 就失去动态调整的能力，遇到意外依赖时就会陷入死等。
3.3 角色声明与上下文预算设置
子 Agent 的声明我都用同一个模板，核心就是职责、权限、上下文预算。我贴一个真实的简化例子（项目本身虚构，但写法可直接抄）：
{ "agents": [ { "name": "standup_leads", "role": "代码执行Agent，负责订单模块的重构与优化", "tools": ["read_file", "write_file", "run_tests"], "context_budget": 12000, "input_contract": "order_service/schema.json", "output_contract": "order_service/restructured_api.md" }, { "name": "ui_builder", "role": "前端Agent，负责结算页的组件编写与联调", "tools": ["read_file", "write_file", "browser_check"], "context_budget": 9000, "input_contract": "checkout/api_types.ts", "output_contract": "checkout/component_tree.md" } ] }context_budget 这项我建议别给太大，给 8000~16000 token 之间是合理区间。给大了子 Agent 会把不相关的项目代码也拽进上下文，等于变回单 Agent。给小了它会频繁报“上下文不足”，任务干到一半自己截断，输出质量也会下滑。这个值没有经验参数可抄，必须拿你的真实项目跑两轮任务才能定下来。
我调整上下文预算时有个土办法：看任务产出里有多少“重复定义”的痕迹。如果子 Agent 一遍遍重复接口字段，说明上下文里这个信息不够集中，应该加大该项的上下文预算；如果它频繁跑偏去改无关代码，说明预算给多了，噪音字段太多。
4. 完整实操：从任务拆解到多 Agent 并行交付
4.1 拿一个真实需求来走全流程
为了把实操讲清楚，我拿一个虚构但又非常典型的项目需求做例子：某业务系统要把现有的订单模块从单体逻辑重构成独立领域服务，同时前端结算页要重新适配新旧接口切换，日志系统要接入统一的 trace 链路。这是一个标准的跨三模块改造任务。
第一步，在主终端里启动 Claude Code，加载team_config.json，在会话里输入一句话需求：“重构订单模块为独立领域服务，前端适配新接口，日志接入全链路 trace”。主 Agent 收到后不会马上动手写代码，它先做代码库结构扫描，读取模块目录、现有接口定义和测试用例，然后开始拆解任务清单。
它会给出一个分阶段计划：阶段一定义订单领域模型和接口契约；阶段二改造订单服务内部逻辑；阶段三对接接口并跑通回归测试；阶段四前端适配；阶段五补充 trace 链路。这个计划会同步到任务队列里，每个任务都标了依赖关系。
4.2 主 Agent 如何给子 Agent 派发任务
主 Agent 派发任务不是一个简单的字符串拼接，它会把任务描述、相关文件引用、契约文件路径打包成一个结构化的 task package，再推给合适的子 Agent。比如阶段一和阶段二可以并行，因为阶段一的产出（领域模型定义）是阶段三的输入，但阶段二需要阶段一的模型才能动手。所以编排层决定：阶段一先派发，阶段二等阶段一完成，与此同时阶段四的前端适配可以先做起来，因为前端只需要知道新接口的 type 定义即可。
这个动态调度非常关键。我见过一批初学者跑通 agentTeams 后喜欢加一堆硬编码顺序，实际上主 Agent 的决策模型看的是依赖关系而不是顺序清单。你给它明确的依赖声明，它自然会做并行调度。你给它任务清单，它就退化成流水线执行器，少了一半价值。
4.3 子 Agent 的独立工作与阻断上报
子 Agent 接收到 task package 后，会在自己独立的运行面板里开始工作。它先读自己负责的模块代码，再对照 input_contract 理解输入，最后拿着 output_contract 写代码。期间它不会去看其他 Agent 的工作状态，这保证了上下文纯粹。
但子 Agent 遇到它处理不了的问题时，会往 blocker 队列里抛阻断事件。常见的情况有两个：一，它需要的接口定义在另一个模块还没提供；二，它发现自己要改的文件和另一个 Agent 要改的文件存在部分重叠。这两种情况一旦发生，编排层会介入，要么调整任务顺序，要么手动修改共享资源锁，然后再重新派发。
我在实际项目里遇到过最典型的一次阻断：两个子 Agent 的任务边界是“前端适配”和“订单服务改造”，它们都要改同一个契约文件api_types.ts，各自写的版本不一致。主 Agent 收到 blocker 后做了一件事——把契约文件单独抽出来作为一个共享 artifact，声明所有 Agent 只能读不能写，契约统一由主 Agent 自己维护修改。这就从机制上根治了冲突。
4.4 结果合并与校验：怎么保证最终的代码是自洽的
子 Agent 一个接一个把产出写进 artifacts 目录后，主 Agent 进入合并校验阶段。它做的事情比 git merge 复杂得多，因为它要同时验证接口契约一致性、测试覆盖率、残留 TODO 密度。
在我自己的团队配置里，我在artifacts段里加了一个 merge_rules 字段，里面声明“所有产出必须通过一次跨模块编译”和“每个改动文件必须有对应测试文件变更”。这样主 Agent 在合并阶段会额外多跑两个 verify 步骤，任何不一致都会自动退回对应子 Agent 重新修。
校验通过的代码会生成一个统一的 diff 汇总，我会把这个 diff 作为一个 PR 推送到代码仓库。注意，这里推送的是完整改动集，而不是各个子 Agent 零散的 commit。保持一个契约化产物边界，能让 review 成本降到最低。
5. 实战中的关键配置参数与调优策略
5.1 并发数、最大迭代次数与超时
agentTeams 里显式声明的配置项，我梳理成一张速查表：
| 配置项 | 参数位置 | 取值建议 | 说明 |
|---|---|---|---|
| max_concurrency | 编排层 | 4~6 | 并发子 Agent 数，调太大则资源冲突激增 |
| max_retry_steps | 编排层 | 3 | 单个子任务最多重新执行的轮数 |
| task_timeout_seconds | 执行层 | 900 | 子任务超过 15 分钟未结束则强制阻断 |
| context_budget | 执行层 | 8000~16000 | 每个子 Agent 的上下文上限 |
| auto_merge | 合并层 | true | 合并前强制跑校验命令 |
| blocker_policy | 编排层 | escalate | 遇到阻断任务时上报编排层人工介入 |
具体值要跟着项目体量走。小型项目我一般max_concurrency开 4，不调超时；大型项目并发 6，task 超时设置 30 分钟。有个小技巧：把max_retry_steps设成 1 跑一遍看看失败率，如果失败率高于 20%，说明任务拆分或契约定义有问题，不是重试能救的，应该先去改任务包。
5.2 契约文件的作用与维护频率
我对契约文件有一种执念：它是整个 agentTeams 真正运转起来的骨架。没有契约文件，子 Agent 间的接口就是个口头约定，想稳定就纯靠运气。
契约文件我一般放在.agent/contracts/目录下，内容是按服务维度拆分的 API 类型定义和跨模块调用签名。维护频率上，我坚持一个原则：契约文件只能被主 Agent 修改，子 Agent 只读。这个原则能避免 90% 的合并冲突。
也许有人会觉得这样太绕，子 Agent 改契约多方便啊。等你真正跑起来就明白了，任何子 Agent 都有一种“顺手把接口改成自己更好写的形状”的冲动，最后合并的时候接口全变了，返工到怀疑人生。宁可主 Agent 多花一轮迭代去改契约，也不要放这几个执行 Agent 维修改权。
5.3 token 成本优化策略
多 Agent 协作的 token 消耗确实比分几次单 Agent 会话要高一点，但如果你配置得当，总成本反而能拉回来。我主要用三个策略：
第一，子 Agent 的只读工具里强制禁用list_files_recursive，只允许它读路径明确列出的文件。这样它不会顺手把整个项目扫描一遍，上下文干干净净。
第二，任务完成通知里只回传 diff 摘要和测试结果，不让子 Agent 把完整代码回传给编排层。产物在磁盘上，编排层按需去读，不需要在消息里再传一遍。
第三，大项目的中间产物定期归档。每完成一个阶段，主 Agent 会把该阶段的关键决策写入一个stage_summary.md，之后相关细节就可以从上下文里丢弃。这个文件和账单有直接关系，它让上下文永远保持精简，不会随着阶段推进而线性膨胀。
初期上手时建议先开一个低配参数跑小任务，观察 token 消耗记录，再逐步调大项目规模。直接把大项目丢上去，大概率第一次跑就把配额烧掉一半还失败了。
6. 常见问题与现场排查实录
6.1 子 Agent 上下文溢出或精度下降
现象：子 Agent 写到一个中段就开始重复修改同一个文件，或者声称某些代码“可能不属于自己负责的领域”。这个问题几乎都指向一个原因：context_budget给得过大，导致子 Agent 自己额外把不相关的文件读进来了。
我的排查步骤是先看子 Agent 的运行日志里有没有read_file了非任务相关的路径，如果有，就说明它的输入定义太宽松。解决方案是收紧input_contract，明确列出它唯一可读的目录和文件，甚至可以配一个blocklist把无关路径直接禁止读入。
6.2 任务无限循环与递归派发
现象：主 Agent 不断给某个子 Agent 重新派发相同任务，子 Agent 反复报同一个错误，整个流程陷入死循环。这个问题核心是max_retry_steps没设上限，或者 blocker 策略没正确 trigger。
我排查时会先查该任务的输出日志。如果连续三次输出同一个失败原因，基本可以断定不是偶发问题，而是任务包本身有缺陷（比如 input_contract 引用了不存在的文件）。这时不要重试，直接终止该任务，手动修好任务包再重新入队。
6.3 两个子 Agent 互相等待的死锁
现象：Agent A 在等 Agent B 的产物，Agent B 在等 Agent A 的产物，两边都超时，任务队列原地卡死。这种问题靠task_timeout_seconds兜底拦截，但它只能止损，不能防止复现。
要根治，必须在编排层设置强制“非阻塞解耦”。我的做法是：禁止两个任务在未完成时互相引用对方的未提交产物，所有跨模块的偶合都必须走共享契约文件，谁都不能直接依赖谁的私有中间产物。契约文件是唯一的跨 Agent 共享事实源，就不存在两个 Agent 之间会锁死。
6.4 合并后编译失败的排查思路
合并阶段编译失败，优先看是不是两个 Agent 同时改了同一个公共工具函数，又或者契约文件被某个子 Agent 悄悄改了。社区里问这种问题的占大头，而每个答案几乎都要追溯到“契约文件的写权限没有收紧”。
我在团队配置里会在merge_rules中加一条单独校验项：git diff --name-only -- .agent/contracts必须是空输出。只要这个目录有任何改动，直接 fail。这个规则一加上，合并没有因为契约问题失败过，等于把源头掐死。
7. 从单 Agent 到多 Agent 的经验蜕变：一些不太会写进文档的体会
聊完技术细节，说点我自己心里的真实体会。
第一次真正跑通 agentTeams 时，我并没有想象中的成就感。相反，一堆合并错误、上下文丢失、角色混乱让我怀疑这套东西是不是过度设计。后来我把项目换成一个中等规模的内部工具，认真按契约驱动的思路做了一遍任务拆分，才体会到它的价值所在。差别不是“把活干得更快”，而是“把活干得更有确定性”——哪块归谁、哪里有依赖、哪里存在冲突，全部显式可见了。
一个很重要的心理转变是：你要把自己从“命令 AI 干活的人”变成“给 AI 团队设计工作制度的人”。直接下达一句“给商城加个支付”交给单 Agent 没有任何技巧可言，但你要定义三个子 Agent 的任务边界，起草一份契约文件，定好上下文预算和合并规则，这就考验你的系统设计能力了。而真正享受这种掌控感的人，会发现这才是 AI 编程的正确打开方式。
8. 几个实用小抄：方便贴到你的配置里直接改
8.1 一个最小可用配置
保存为team_config.json，改一下orchestrator的模型名就能跑：
{ "team_name": "demo_team", "orchestrator": { "role": "plan_and_merge", "model": "claude-sonnet", "tools": ["read_file", "run_command"] }, "agents": [ { "name": "code_worker_a", "role": "负责模块A的开发", "tools": ["read_file", "write_file"], "context_budget": 10000, "input_contract": ".agent/contracts/module_a_in.md", "output_contract": ".agent/contracts/module_a_out.md" }, { "name": "code_worker_b", "role": "负责模块B的开发", "tools": ["read_file", "write_file"], "context_budget": 10000, "input_contract": ".agent/contracts/module_b_in.md", "output_contract": ".agent/contracts/module_b_out.md" } ], "merge_rules": { "auto_verify": ["npm run build", "npm test"] } }配好后直接在主会话输入“跑我的团队配置，把当前需求拆掉”，主 Agent 会自己接管剩下的事情。这个最小配置我建议新手第一周就只跑它，别加更多花活，先把流程跑顺。
8.2 一些我最常用的 prompt 模版
给主 Agent 的：
加载 team_config.json。这是一个多Agent团队协作环境。 请先分析当前代码库结构，拆解我下面的需求为不超过N个子任务。 每个子任务需要定义input_contract和output_contract。 注意识别数据依赖和资源依赖，能并行的尽量并行。 完成合并前必须运行 merge_rules 里的全部校验命令。给子 Agent 调试用（不直接作用，因为子 Agent 的任务包由编排层生成，但排查时可手工重发）：
重跑刚才失败的任务，忽略上一次已写入的 artifacts。 严格参考 input_contract 的文件定义，禁止读取其他文件。 产出只写到 output_contract 指定的路径，不要改动无关文件。 发现任何不明确的信息，抛 blocker 到队列。这几个 prompt 就是整个 flow 的底层基调，流程跑出问题先回来检查这条基调有没有被遵守。
9. 扩展方向：agentTeams 还能玩出什么花活
9.1 跨语言重构与迁移
老项目做 Python 到 Go 的迁移时，agentTeams 的优势特别明显。拆分成“Python 侧理解服务”和“Go 侧重建服务”两个子 Agent，共享契约是接口定义，前者把 Python 逻辑翻译成接口行为描述，后者按契约用 Go 实现。两边不需要互相读对方代码，但最终的接口契约天然一致。我做过一个模拟迁移，三个模块两天跑完，返工次数压到了个位数。
9.2 文档与代码同步生成
代码 Agent 和文档 Agent 并行跑是另一个常用玩法。代码 Agent 改完核心逻辑后生成一组“行为变更记录”，文档 Agent 读记录自动更新 README 和 API 文档。两者之间不直接依赖，依赖的是变更记录这种中间契约，文档永远跟代码同步更新，不再出现“代码早改了 README 还是旧的”这种老大难。
9.3 测试 Agent 的独立巡逻
让一个专门子 Agent 盯着当前 diff 写测试，而不是每轮合并后手动补测试。它可以基于已有契约独立工作，跟开发 Agent 并行，合并时把两边的产出一起过 merge rules。这支巡逻队能显著提高交付质量的稳定性，成本只多一个 Agent 的 token。
10. 最后再讲一个我踩过的坑：别忽略产物目录的权限设计
我见过很多人把 agentTeams 搭起来跑通后，栽在一个特别不起眼的细节上：artifacts 目录所有 Agent 都可以随便写，最后产物乱成一片，编排层合并时根本不知道哪个才是最新版。你要在共享层把产物目录严格分成inbox/、approved/、rejected/三格。子 Agent 只能写inbox/，主 Agent 校验通过后把文件扫进approved/，退回的进rejected/加备注。这一个习惯，能让你的团队协作逻辑清晰十倍，排查问题的时候心智负担也会小很多。
多 Agent 协作这事，本质上就是给大模型设计一个适合它脑回路运转的组织架构。架构合理了，单个 Agent 的笨拙可以被团队协作掩盖；架构乱了，再强的模型也会被流程消耗淹没。希望这篇从原理到实操的拆解，能让你在下次面对大项目时，不再一个人埋头硬扛，而是带着一整支 AI 队伍上场。
