最近一次跨模块改造我差点被自己的代码绕晕。需求并不复杂但一会儿要确认订单模块的数据出口一会儿要去库存模块补索引改到一半还得回头检查自己刚才的改动有没有把老接口带崩。当时的感受就是活不重乱是真乱。后来我把整套流程丢给 Claude Code 的 Agent Teams 模式去跑——说白了就是把一个任务拆给多个各司其职的 Agent让它们像一个小团队那样协作——整个节奏立刻清楚了。这篇内容不是官方文档翻译而是我自己把 Agent Teams 模式用进真实项目后的使用思路和样例复盘。适合几类人看已经在用 Claude Code 但总觉得单 Agent 改大项目力不从心的听说过 Agent Teams 但不知道怎么定义角色、怎么启动的以及那些被多 Agent 并行神话吸引、又怕配置太复杂迟迟没动手的。我会从最朴素的出发点讲起为什么单 Agent 不够用、角色怎么分、配置怎么落、样例怎么跑通最后再讲几个实际运行中才会遇到的坑。1. 你真正的瓶颈不是单Agent能力而是串行角色混乱先别急着讨论配置。我得先把 Agent Teams 要解决的问题讲透否则你照着配好角色跑起来还是一团乱。很多人第一次用 Claude Code 时的感受是小功能改得飞快一碰到跨模块、跨文件的大改动就开始胡言乱语——前面改好的东西后面忘了或者评审自己写的代码怎么都觉得没问题。我以前也以为是上下文不够长后来发现真正的问题出在两个方面。1.1 单Agent串行改大项目时的三类卡点第一类是顾此失彼。一个 Agent 同时承担着理解需求、设计方案、写代码、自查、修 bug五件事它的注意力在不断切换。就像一个人既当产品经理又当开发又当测试每切换一次角色都要重新翻一遍上下文。改到后期它很可能把最开始定下的约束条件给丢了比如不能动老接口的返回字段这种关键约定到第三轮修改时就完全不在视野里。第二类是自我评审失灵。让同一个 Agent 检查自己刚写的代码它很容易陷入路径依赖——它知道自己想实现什么所以看代码时会不自觉地补全逻辑觉得这里虽然没写但意思到了。你让它在代码评审时挑自己的毛病十次有八次只能挑出缩进和命名问题真正的逻辑漏洞反而被它自己脑补掉了。这个现象和真人写代码时的审稿疲劳一模一样。第三类是串行等待的浪费。一个 Agent 从需求分析一路做到最终实现所有步骤排成一条线。哪怕中间有一个环节只是等确认整条线就卡住了。而实际上一个稍大的需求天然可以切成几块互相独立的任务A 负责接口定义B 负责数据层查询C 负责测试用例。如果让一个人包圆这三块工作只能轮着来时间翻倍还增加上下文的记忆负担。1.2 Agent Teams不是让Agent更聪明而是让协作更有结构Agent Teams 的核心思路不是换一个更强的模型也不是把上下文无限加长而是把一个人干所有事变成一个团队各管一摊。它借鉴的是软件开发里最古老也最有效的组织方式角色分工、任务交接、阶段评审。在这个模式下每个 Agent 的角色被明确写死。规划者只管拆需求、定任务卡、列验收标准执行者只负责按任务卡写代码评审者只负责挑毛病、对照验收标准打回集成者负责汇总所有改动、处理文件冲突、跑最终验证。各角色之间通过任务卡 状态记录协作互不抢活。这样做的好处是执行者不需要关心需求到底为什么这样定它只需要看任务卡评审者不需要从零理解整个项目它只需要对照验收标准检查产出规划者不需要陷入某个函数的具体实现它只需要保证拆解出的任务边界清晰。每个人看到的上下文都变窄了反而在自己那一环上更专注。这里要先说一句大实话Agent Teams 的定位不是全自动开发小组不是你在旁边喝着咖啡看它自己把项目写完。它的定位是帮你把混乱的软件过程变成有节奏的协作流。人工的重点从写每一行代码转移到定义角色、审核任务卡、拍板冲突。我自己用下来这是思维上最大的转变。2. Agent Teams的分工逻辑规划者、执行者、评审者、集成者你可能会问一个团队到底需要几个角色我的答案是别贪多。初期最稳定的是四个角色规划者Planner、执行者Implementer、评审者Reviewer、集成者Integrator。有些场景还会加一个文档员但四个已经能覆盖大部分开发流程。2.1 四个角色的职责边界与协作关系我这里用一句话概括每个角色方便你理解各自的边界规划者把模糊需求变成任务卡。它要定义做什么、做到什么程度算完成、产出放在哪个目录、和哪些已有模块有依赖。它不写业务代码。执行者只认任务卡。按规划者给出的验收标准实现功能不自作主张扩展范围。评审者对照验收标准检查改动。它不负责修代码只负责发现问题并打回。集成者在所有人完成后汇总。它处理多个执行者同时改动同一文件的冲突跑完整测试产出最终合并结果。这四个角色的顺序是规划者先开工接着多个执行者并行每个执行者完成后评审者介入最后集成者收尾。你可以把它脑补成一个传送带每个角色只处理自己这一段。2.2 协作机制任务卡、状态记录与阶段门禁角色分好了还得有共同语言。我建议三个机制配合使用第一个机制是任务卡Task Card。规划者输出的核心产物格式我习惯这样组织任务编号: T-001 需求来源: 跨模块查询功能-阶段1 任务描述: 定义统一的聚合查询请求/响应数据结构 验收标准: 1. Request包含分页参数与超时配置 2. Response包含三个子模块的数据块与错误标记 3. 新结构不修改已有模块的对外入参 依赖任务: 无 输出位置: src/common/query_lib/任务卡最大的价值是把模糊变成可验证。执行者拿到任务卡后不需要猜测评审者拿同一个任务卡去验收标准一致不会出现我觉得差不多了这种扯皮。第二个机制是状态记录。我习惯在项目里留一个agent_status.md每个 Agent 完成任务后追加一行任务编号、完成时间、涉及文件列表、自测结果。这个东西不是摆设它让集成者可以快速知道哪些任务完成了、哪些还在执行者手里、哪些被评审打回了。没有状态记录多 Agent 一跑起来很快就会有人改同一个文件。第三个机制是阶段门禁。严格执行执行者产出 - 评审者通过 - 集成者合并的门禁顺序。执行者绝不能自己改完顺手就合并。我看到很多失败的多 Agent 协作都是因为省略了评审步骤导致问题积累到最后一次性爆发。2.3 什么时候不该用Agent Teams加了这么多结构自然要付出成本。所以我也说说反例什么时候不要硬套 Agent Teams。第一一次改动量少于两百行、只涉及一两个文件时用单 Agent 直接改反而更快。这时候搞任务卡、评审、合并纯粹是给简单问题增加流程负担。第二需求本身极其模糊、连你自己都没想清楚要什么的时候不适合启动 Teams。规划者需要一个相对明确的方向去拆解如果你自己都只有一句话拆出来的任务卡大概率是空中楼阁。这种情况建议先用普通对话把需求聊清楚。第三团队里没有人工仲裁者的时候也别硬上。多个 Agent 的评审意见一旦互相冲突总得有人拍板。如果你做不到在关键时刻看一遍冲突上下文、决定听谁的那流程就会卡死。Agent Teams 不是把你的判断力替代掉而是帮你把判断力用在最关键的地方。3. 手把手搭一套Agent Teams配置、启动与第一次并行讲完理念进入实操。我会给出自己当前项目里的配置思路和操作顺序。要特别说明具体语法和可用的配置项建议以你本机 Claude Code 版本的帮助说明为准我这边只示范配置的组织结构和交互逻辑。3.1 第一步先整理项目基线再定义角色很多人犯的错是上来就定义 Agent 角色忽略了项目基线。如果你的项目里没有一份准确的说明文件任何 Agent包括单 Agent都会靠猜来理解项目。我在启用 Agent Teams 之前会先确认CLAUDE.md里至少写清楚这几件事项目是干什么的、整体目录结构如何用什么语言、什么构建命令、什么测试命令项目里关键的编码约定比如所有对外接口必须保持向后兼容哪些目录属于核心逻辑改动需特别谨慎。基线越清楚后面每个角色的判断就越有依据。这个文件是所有 Agent 共享的团队章程。接下来定义角色。我习惯在项目里用一个独立段落来声明 Agent Team格式大致如下你按需调整## Agent Team: feature-team members: planner, implementer, reviewer, integrator ### planner 职责: 将需求拆解为任务卡定义验收标准与依赖关系 可用工具: read, grep, bash 操作范围: docs/, requirements/ 行为约束: 不写业务代码每个任务卡必须包含验收标准 ### implementer 职责: 按任务卡实现功能完成后运行单测 可用工具: read, edit, bash 操作范围: src/, tests/ 行为约束: 严格按任务卡实现不修改与任务无关的文件不自作主张扩大范围 ### reviewer 职责: 对照验收标准检查改动输出问题清单 可用工具: read, grep, bash 操作范围: 全项目可读 行为约束: 不直接修改代码问题清单需逐条对应验收标准 ### integrator 职责: 合并所有通过评审的改动处理冲突运行完整测试 可用工具: read, edit, bash 操作范围: 全项目 行为约束: 只合并通过评审的任务冲突处需明确记录处理原因这样配置的核心目的是给每个 Agent 划清能干什么、不能干什么、能碰哪些目录。尤其是操作范围和行为约束这两条能避免执行者 A 顺手改了执行者 B 负责的文件这种惨剧。3.2 第二步启动一次多Agent会话的标准动作配置写好了接下来是启动流程。我的标准动作分五步顺序基本固定先开一个普通会话把需求背景和约束完整描述一遍让规划者产出任务卡。认真人工审核任务卡。这一步不要偷懒任务卡拆得不好后面全乱。我一般重点看验收标准是否可验证和任务边界是否清晰。确认任务卡后让执行者开始并行实现。如果工具支持并行子会话就让多个执行者同时开工如果不支持就按依赖顺序逐个启动。每个执行者完成后立刻把评审者拉进来对照验收标准审查。评审通过才进入下一步。全部通过后交给集成者合并。合并完成后跑一次完整测试并人工抽查关键改动。这里有个心得不要让执行者自己汇报完成就完事。执行者的完成信号只是它觉得做完了必须要有评审者的独立确认。我把这个当作铁律因为吃过太多次亏。3.3 第三步第一轮并行前的人工确认清单第一次跑 Agent Teams 前我会用下面这张表自查一遍避免一轮就跑崩检查项具体问题通过标准项目基线项目行为说明是否够执行者直接上手新角色能从文档理解构建与测试命令角色边界每个角色是否清楚自己的操作范围不存在两个角色都能改同一关键目录的情况任务卡质量验收标准是否可验证每条标准能对应到一个测试或一个明确检查动作依赖关系任务之间是否有隐式依赖无依赖的任务才并行有依赖的排好先后仲裁安排冲突时你是否有时间介入提前预留人工裁决窗口不在忙乱时开跑我建议你把这张表记到项目文档里每次开新的一轮都对照一遍。它不是形式主义而是把多 Agent 协作容易失控的根源逐个堵上。4. 样例拆解跨模块查询功能从任务卡到合并验收这一节我用一个具体的样例把 Agent Teams 的完整流程走一遍。场景是一个内部数据平台要新增一个跨模块查询接口需要同时从订单模块、库存模块、用户模块取数聚合成统一结果返回。这个需求涉及三个模块、多个文件、还有老接口兼容问题非常适合演示多 Agent 协作。4.1 需求背景与初始约束原始需求只有一句话做一个聚合查询接口前端一次调用能同时拿到订单、库存、用户三个模块的数据。听起来简单但深入一想全是细节三个模块的数据格式不一样查询超时时间不一样分页方式也不一样。而且老系统已有各自的查询入口不能破坏它们现有的调用方式。我把这些约束写在需求说明里然后交给规划者。规划者产出的任务卡如下任务编号: T-001 任务描述: 定义聚合查询请求/响应数据结构 验收标准: 1. Request 包含分页参数与超时配置 2. Response 包含三个独立数据块与整体错误标记 3. 不修改三个模块现有的对外入参 输出位置: src/common/query_lib/ 任务编号: T-002 任务描述: 梳理订单模块现有数据访问层提供只读查询函数 验收标准: 1. 输出订单模块可复用的查询函数签名 2. 函数不改变原有事务边界 输出位置: src/modules/order/ 任务编号: T-003 任务描述: 梳理库存模块现有数据访问层提供只读查询函数 验收标准: 同 T-002针对库存模块 输出位置: src/modules/inventory/ 任务编号: T-004 任务描述: 实现聚合逻辑按请求组装三个模块结果 验收标准: 1. 任一模快超时或出错时返回该模块错误标记不影响其他模块数据 2. 分页规则为整体统一分页各模块内部查询按数据量适配 输出位置: src/common/query_lib/ 依赖任务: T-001, T-002, T-003 任务编号: T-005 任务描述: 编写聚合接口的单元测试覆盖超时与部分失败场景 验收标准: 1. 单测覆盖三个模块全部正常 2. 单测覆盖一个模块超时、其他两个正常 3. 单测覆盖全部模块超时 输出位置: tests/query_lib/ 依赖任务: T-004注意 T-001、T-002、T-003 之间没有依赖关系可以并行T-004 依赖前三者必须等它们完成T-005 依赖 T-004。这个依赖关系是规划者最重要的产出之一它决定了并行的粒度。4.2 执行者的产出与评审者的追问三个并行执行者各自开工。T-001 的执行者先在src/common/query_lib/下定义了数据结构产出文件types.goT-002 和 T-003 的执行者分别梳理了订单和库存模块各自给出只读查询函数。这里我特别想讲评审者的作用。T-004 的执行者实现聚合逻辑时自测通过觉得自己写得没问题。但评审者对照验收标准检查时发现了一个关键漏洞当订单模块超时返回错误标记后整体响应的错误标记字段虽然被置为了 true但前端拿到的订单数据块是空对象而验收标准里明确说明不影响其他模块数据——前端根本无法区分订单模块超时和订单真的没有数据。这是两种完全不同的业务含义。评审者直接打回并在问题清单里写明错误标记需要拆分成整体标记和模块级详细错误码模块超时时模块数据块应包含明确的错误码而不是空对象。执行者起初还辩解说自己看的是 T-001 的数据结构字段设计里确实有一个错误码位只是没在超时分支里填值。评审者回应验收标准第一条的意图就是模块错误要能被调用方识别空对象不满足意图。这个来回特别典型。如果没有评审者这一步这个 bug 会带着测试全绿的光环合入主干直到前端联调时才暴露。我自己单 Agent 写代码时很容易在我知道这里留了错误码字段的心理暗示下忽略实际赋值但评审者没有这种暗示它只看结果。4.3 集成阶段的冲突处理与最终合并所有任务通过评审后集成者开始合并。此时出现了最常见的冲突T-001 在src/common/query_lib/types.go里定义了聚合请求结构T-002 的在梳理订单模块时顺手在订单模块的公共导出文件里加了一个注释说明而 T-004 在实现聚合逻辑时也改了同一个types.go给错误码补赋值。好消息是改动方向一致没有逻辑冲突但文件层面需要集成者做一次干净合并。集成者把改动汇总后跑完整测试。这里还有一个意外T-005 的测试用例里有一个模拟库存模块超时的用例因为 mock 的方式和 T-003 实现的查询函数签名不完全匹配在集成环境里失败了。集成者没有直接改测试代码来让测试变绿而是定位到是签名不匹配导致的编译期错误回头检查 T-003 是否符合任务卡约定。最终发现 T-003 的执行器为了让函数更通用私自多加了第二个参数偏离了 T-002/T-003 任务卡要求的签名。这就是我在前面强调的不自作主张扩大范围的实际教训。处理方式是要求 T-003 的执行者回到任务卡约定修正签名重新通过评审后再让集成者跑一轮完整测试。最终全绿聚合接口合并完成。这个样例整体跑下来给我的感觉是慢在开始任务卡、评审、返工但快在收尾合并后问题很少。对比之前单 Agent 一把梭写完再修 bug 的方式流程时间可能差不多但质量上的确定性完全不同——你清楚每一个环节的状态而不是反正最后测出 bug 再改。5. 实际跑起来才会遇到的坑和处理思路配置和样例都讲完了但我知道你真正关心的可能是实际用起来到底有哪些坑这些东西不跑几轮是遇不到的我按自己的经验逐个列出来每个都附上我现在采用的处理思路。5.1 角色定义模糊导致的全员抢活第一轮跑的时候我把角色定义写得特别粗比如执行者只写了负责实现功能。结果就是做 T-002 的执行者在模块目录里发现了一个可以顺手优化的地方直接把重构做了另一个执行者看到测试目录里有个陈旧的测试顺手改成了新接口。等到集成阶段关于这些顺手的改动到底该不该保留吵成一团。现在我给每个执行者加了一条硬约束禁止修改与当前任务卡无关的文件如果发现需要顺手处理的关联问题写入任务卡备注交给规划者决定。这条约束花不了多少字但能挡掉大部分越界操作。尽量把意外发现交给规划者统一决策而不是让执行者现场即兴发挥。5.2 评审流于形式没有标准的评审是无效的评审者如果只是看一眼代码觉得风格还行那这个角色就是摆设。我见过很多配置了评审者的团队跑起来跟没配置一样——评审者的意见都是看起来没问题然后所有 bug 还是留到了集成阶段。我的解决办法是评审者必须逐条对应验收标准输出结论。每个验收标准要么通过要么不通过不通过时必须写出具体的反例或复现路径。比如不能只说这个数据结构设计不合理要说对照验收标准第2条模块超时后数据块返回空对象调用方无法判断是超时还是无数据。把评审从印象派变成条文派质量立刻上一个台阶。5.3 上下文污染共享记忆与隔离策略多 Agent 协作最容易忽略的是上下文污染。我一开始用一个共享的status.md来记录所有进展本意是方便结果发现执行者会跑去读整份文件把很多跟自己无关的历史信息都加载进来反而稀释了注意力甚至被其他模块的问题带偏。我现在采用分层共享策略CLAUDE.md里只放所有角色都必须知道的项目基线任务卡里只放该执行者需要知道的信息agent_status.md只记录哪个任务完成、结果概述不放详细技术方案。每个 Agent 默认只读自己需要的那一层避免不必要的上下文扩张。这个思路和代码分层很像——该隔离的隔离该共享的共享。5.4 成本与节奏控制并行不等于无限加速多 Agent 并行是有成本的。每个 Agent 都是独立的一次会话都要消耗模型调用次数。刚开始跑的时候我让规划者把所有任务往细了拆最多一次并行五个执行者结果一轮下来 token 消耗翻了三倍而收益并不比三个执行者并行高多少。我现在的控制原则是并行数量控制在三个以内可拆可不拆的任务优先不拆同一模块内的改动尽量归并到同一个执行者避免两个人同时改相邻文件。节奏上我会先让一个执行者做最核心的任务跑通主干再放其他执行者并行做周边任务。这个先主干后分支的顺序能规避大量无谓的合并冲突。5.5 仲裁者缺位Agent们吵起来谁来拍板多角色协作必然出现意见冲突而冲突不一定都能被自动消解。比如评审者认为超时策略应该直接抛出异常而执行者认为应该返回降级数据两边在任务卡范围内都有道理。这种解释性冲突不能靠自动规则解决必须有一个人拍板。我现在会在启动前就跟自己约法三章一旦出现解释性冲突我必须亲自看一遍两边刚才引用的上下文然后给出明确结论。不要寄希望于再问一次 Agent 就能自动达成一致它们会在各自的路径里越论证越坚定。你在关键时刻站出来反而是最省钱、最省时的做法。6. 用了一段时间之后我现在的选择逻辑最后讲一讲我现在的真实选择逻辑也算是给前面这些内容做一个收束。凡是改动面大于两个模块、或者需求里有明确的接口兼容数据一致性这类约束时我会主动切到 Agent Teams 模式并且严格按照规划者拆卡、执行者实现、评审者打回、集成者合并的流程走。哪怕前期准备花十分钟后面也能在收尾阶段省回来。凡是一次改动就是一个文件内的问题或者只是重构单个函数、补个测试我就直接用单 Agent 快速改完不上 Teams 流程。这不是对 Agent Teams 的不信任而是工具和人一样在合适的场景里才有效率。你自己把判断力留在什么时候用、怎么分配角色、怎么拍板冲突这三个点上剩下的机械执行和标准检查尽量交给流程。另外一个可以继续扩展的方向是把 Teams 的配置积累成项目内部模板。我在几个不同技术栈的项目里都维护了一份角色定义模板新项目启动时直接复制过去再按项目特点微调目录范围和验收标准。第一次配置花的时间比较多但迭代两三次之后这套东西会越来越顺手——这大概也是 Agent Teams 和单 Agent 使用体验上最明显的分水岭。