Claude Code跑通单代理任务之后很多人会卡在同一个地方项目一复杂它就开始东一榔头西一棒子改完前端忘后端查完文档又忘了刚开始的目标。我之前在真实项目里被这个问题折磨了两周后来才意识到问题的根源不是模型不够聪明而是我压根没用好它的多代理协作机制。Claude Code的Agents能力不是为了让你多开几个终端窗口装样子而是实打实地把任务拆解、委托、验收变成一套可执行的工程流程。这篇文章不聊基础安装和HELLO WORLD直接讲清楚多代理协作怎么落进真实项目以及任务委托时最容易翻车的地方。1. 单代理在真实项目里的三个死穴为什么必须要拆网上大部分Claude Code教程都在教你怎么让一个Agent从头干到尾。坦白说demo阶段完全够用但一旦进入真实项目单代理模式很快就会暴露出几个绕不开的问题。先把我实测中踩到的情况摆出来你对照一下自己项目是不是也有类似征兆。1.1 上下文窗口瞬间爆炸模型开始装失忆很多人迷信Claude Code有1M上下文这种宣传语但别忽略一个前提上下文再大也是有代价的。我在一个中型Next.js项目里让单个Agent一口气完成重构API层更新数据库迁移脚本调整前端页面样式不到半小时它的行为就开始飘——明明几轮对话前刚确认过的数据模型定义下一轮它又按旧结构去写代码甚至开始重复读取已经读过的文件。为什么会这样Claude Code的Agent会把你项目中打开的文件、运行过的命令输出、历史对话全部累积进上下文。这个记忆一旦超过有效注意力区间模型就会呈现一种类似装失忆的状态它不是不知道而是重要信息被海量中间过程稀释了。1M上下文给了你能装下的容量但没给模型装下之后还能拎得清优先级的能力。1.2 认知偏离干着干着目标和交付物对不上了单代理执行长任务还有一个特别隐蔽的问题目标漂移。举个例子我让它修复登录接口的鉴权漏洞它会在排查过程中顺手改了路由结构、重构了错误处理中间件甚至把日志库换了一个。你说这些改动有没有道理单独看可能都有道理但作为任务委托方你根本没法控制它的动作边界。这不是模型蠢而是单代理的天然倾向——它会为了达成目标选择我认为最合理的完整路径而不是你要求的最短路径。在代码库足够大的情况下这种倾向会被无限放大。多代理协作最核心的价值之一就是通过拆解把每个Agent的动作边界钉死没有拿到相关委托的Agent不该碰不属于它的文件。1.3 串行执行时间成本按小时算单代理本质上是串行思考的。它在改代码的时候没法同时去查文档、翻历史提交记录、梳理另一个模块的依赖关系。每件事都得排队所有IO操作都在一条链路上串着走。在我们一个多模块的后端项目里这种串行带来的体验就是一个看似不复杂的任务Agent要花好几轮对话的时间把所有相关信息温习一遍才开始动手。引入多代理之后最直观的变化是可以把探索信息写代码审查代码这些环节分给不同角色的Agent并行推进整体完成时间能压缩掉大概一半。当然并行不等于万能后面我会讲哪些场景适合拆出去并行哪些反而更该串着来。2. 多代理协作的核心机制Task指令与Subagent的委托链聊明白了为什么要拆接下来就是怎么拆的问题。Claude Code的多代理能力不是让你在系统层面开多个进程而是通过内置的Task指令和Subagent机制来实现任务委托。理解这套机制是玩好转委托的第一步。2.1 Claude Code的Subagent到底是个什么存在在Claude Code的语境里Subagent是一次性任务的执行单元。它有一个明确的目标描述一个受限的工具集以及相对独立的小上下文环境。你可以把它理解为你临时招进来干活的外包工程师你给它一份清晰的需求文档目标描述限定它只能用哪些工具可用工具集然后把任务丢出去等它干完或者到时间限制再向你的主Agent汇报结果传递回一个摘要性的输出。这里有个特别重要的点Subagent不继承主Agent的完整对话历史。它是拿着任务书必要的参考文件进入一个新环境的。恰恰是这种隔离让它能专注于一件事。很多人在实践多代理时有个误区觉得Subagent也要从头到尾了解项目的全部上下文才能干活。其实恰恰相反——你对它说太多它可能会独走偏锋而且主代理要把大量上下文传给每个子代理成本极高。它和主Agent的实际关系可以参考这个表格维度主AgentSubagent上下文环境继承完整对话历史仅携带委托任务书和指定参考文件工具范围默认全量工具集可在委托时显式限制生命周期贯穿整个会话任务完成即销毁职责定位全局调度、最终决策单点执行、局部探索汇报方式直接向用户汇报将任务摘要汇报给主Agent2.2 委托链怎么串起来的一次完整的任务委托过程一次典型的任务委托长这样主Agent在评估任务后认为某个子任务可以独立出去执行于是通过Task指令发起委托。委托内容包含任务说明、期望输出格式、补充参考文件路径以及一个明确的验收标准。Subagent接手后开始独立干活期间它的操作不打扰主Agent的上下文环境。干完活之后返回一个结构化的摘要结果主Agent根据这个结果决定下一步动作。实际跑下来最有价值的是在委托书里加验收标准和禁止事项两块。打个比方我在委托Subagent去整理一个API接口清单时会明确写输出的交付物必须是Markdown表格每个接口必须包含请求方法、路径、参数定义、返回值结构和错误码说明特别禁止输出示例代码或修改任何源文件。限定得越清楚Subagent的产出就越接近可直接用的状态后续主Agent整合的成本就越低。2.3 为什么Task要设计成一次性的而不是常驻多轮对话熟悉了Claude Code的交互之后很多新人会问能不能让几个Subagent之间直接对话形成一个Agent团队聊天室这样共享信息不是更方便吗理论上很美实操上很痛。一旦让两个Subagent自由对话它们的上下文环境就开始互相污染你根本没法控制消息传播的方向和内容边界最后的结果大概率是各说各话主Agent在里面当传话筒反而白白消耗大量上下文资源。现在Claude Code里的Subagent设计成了一次性任务执行单元信息流动方向是严格单向的主Agent下发任务Subagent执行并汇报主Agent做裁决再决定下一步。这种星型拓扑虽然看起来不如网状拓扑那么自由但在工程实践中是最稳的。想清楚这一层你会发现任务委托的核心不是「把任务丢出去」而是「把任务拆成一个个边界清晰、验收明确的一次性执行单元」。3. 四种亲测有效的工作流模式从三角色到流水线知道了Subagent机制是怎么回事真正难的部分才刚开始——怎么设计委托结构。同一个项目不同的拆解方式效率差距能差出好几倍。下面这四种模式是我在这些项目的实践里真正跑通过并沉淀下来的每种模式都对应着不同的任务类型。3.1 三角色模式架构师、实现者与审查者这是最容易上手、也是最推荐新手团队先跑起来的模式。既然是三角色自然是将一个功能迭代拆成三个阶段分别交给三种角色定位的Agent。架构师Agent先读项目文档和关键模块源码输出一份详细的技术实施方案包括涉及的文件清单、改动点、风险和依赖关系。它不写具体业务代码只做拆解和规划。实现者Agent拿着架构师给的技术方案聚焦在指定文件上做具体编码实现。因为方案清晰它的上下文可以规划得很小不容易偏差。审查者Agent不直接参与编码而是读实现者改动的diff、跑静态检查、审视边界条件和潜在回归风险输出一份审查报告。主Agent根据报告决定直接合并还是退回修改。这个模式最大的价值在于把「方案制定」和「方案执行」彻底解耦。实际项目里架构师Agent输出的技术方案往往还能反过来倒逼你自己想清楚一些设计细节——很多时候我们觉得项目代码烂不是因为写代码的人不行而是动手前就没有一份被认真执行过的方案。3.2 并行探索模式信息收集阶段的加速器这个模式适合用在任务前期比如梳理这个模块的完整依赖关系或查一下线上Bug可能跟哪些配置文件有关。这类任务天然是可并行拆分的——查API层归查API层查定时任务归查定时任务彼此互不干扰。我在一个Rust服务端的Bug排查里用过这个模式。当时有个偶发500错误涉及HTTP路由、数据库连接池和工作队列三个模块。我让三个Subagent分别去对应模块里收集相关信息各自输出一份带有日志分析和代码路径推断的报告。三份报告回来后主Agent拼在一起问题定位范围一下子缩小到了数据库连接池和队列消费并发之间的竞态问题。并行探索模式需要注意一个纪律每个Subagent只读不改。探索阶段一旦允许了写操作很容易出现两个Subagent同时改同一个配置文件的尴尬局面轻则覆盖重则把项目环境改得一团糟。3.3 流水线模式一个Agent的输出就是另一个Agent的输入流水线模式的核心思路是将一个长流程拆成多个阶段每个阶段由一个子Agent负责后一个子Agent拿到的输入是前一个子Agent的输出。每一个阶段内的上下文都是干净的产出物也是格式统一的可以理解成软件工程里的管道过滤器架构。我用它做的最典型的场景就是从旧代码到新架构的迁移。第一阶段Agent负责解析旧代码逻辑并输出行为描述清单第二阶段Agent拿着清单设计新架构下的模块划分和接口定义第三阶段Agent基于接口定义写新代码实现第四阶段Agent对比新旧行为做差异审查。每一阶段传递的都是文档和清单而不是让一个Agent去理解旧代码是什么样、新架构是什么样、怎么改这一大坨东西。流水线模式最需要注意的问题是交接物的格式约定。每阶段的输出文档如果没有强格式约束下一阶段的Agent就得花大量推理成本去猜反而容易出问题。我自己的做法是在每个阶段的委托书里明确写上输出必须包含XXX小节、采用Markdown格式、名词术语必须与项目现有用语一致。3.4 沙箱隔离模式高风险任务的保险箱如果有人让你来维护一个牵一发动全身的核心模块沙箱隔离模式就是你的保险丝。原理很简单把某个可能引起大范围改动的重构任务丢给一个Subagent在隔离环境中去做让它输出一份完整的改动计划、风险点和回滚策略但不让它直接碰主分支的代码。这个模式特别适合激进但必要的重构。比如把一个老旧的全局状态管理改成新的数据流方案这种改动在单代理模式下经常失控——它可能会因为顺手而为改出来的结果和你想的大相径庭。沙箱模式下Subagent只能基于一个指定的代码快照去设计并验证改动方案最终你拿到一个安全兜底过的方案再手动决定是否应用。对比下来四种模式的适用场景可以这样归纳模式适用场景核心关注点三角色功能迭代、新模块开发方案先行、前后置解耦并行探索信息收集、问题初诊只读不改、并发隔离流水线代码迁移、全链路重构交接物格式、阶段验收沙箱隔离高风险重构、核心模块变更风险控制、变更计划评审4. 任务委托书怎么写决定Subagent产出质量的关键笔杆有一个非常容易被忽略的真相Subagent的能力上限高不高取决于你那份委托书写得好不好。我在实战中见过太多委托之后完全跑偏的案例回看委托书基本都是帮我看看这个模块怎么改比较合理这种一句话需求。这就相当于你给一个外包工程师连个PRD都不发就说你看着弄吧——他自己看着弄最后你就只能自己看着改。4.1 委托书的五要素结构一份能用的委托书至少应该包含这么五块内容角色定义、任务背景、交付物标准、验收条件、禁区红线和约束。我在给自己的实践制定模板时差不多是下面这种写法。任务角色你是资深前端工程师专门负责UI组件库的代码重构不修改业务逻辑。 任务背景项目当前使用的xx组件已废弃需要替换为新的yy组件。 具体任务将src/components/目录下所有引用了xx的组件文件清单见attachments/component-list.md迁移到yy。 交付物标准输出一份改动文件清单含diff摘要并附上替换过程中遇到的问题记录。 验收条件所有组件迁移后TypeScript类型检查通过build产物体积无异常增长。 禁止事项不得修改任何业务逻辑代码不得改动与本次替换无关的配置文件不得运行lint --fix命令。看到最后那条禁止事项了吗这是很多人完全不会想到要写的。没有它Subagent可能会在执行过程中顺手优化一些不该动的代码。这让它的输出变得面目模糊。4.2 补全背景信息不要吝啬为什么委托书里最容易缺失的是背景信息。只说把A接口改成B接口是远远不够的因为Subagent不理解为什么要改就无法判断改到什么程度算成功。你需要在背景里补充一句本次改造是因为旧接口存在并发写入丢失数据的问题新方案采用乐观锁重试机制因此调用的超时参数和异常处理也需要同步调整这才能让Subagent在碰到边界情况时做出正确判断。但注意背景信息要克制。不要把所有历史包袱都倒给它只需要提供「完成这个任务所必需的最少背景」就足够了。信息给多了一是浪费上下文二是增加它跑偏的概率。4.3 设定可验证的验收标准而不是模糊形容词最常见的无效验收条件就是确保代码质量没问题——这种话Subagent看了一脸懵。验收标准必须量化到可以机械验证的程度。举例说确保所有改动文件通过eslint检查且无新增Console.log、确保单元测试覆盖率不低于80%、确保新模块在本地build可以一次通过——当验收标准可以被具体命令或工具机械验证时Subagent的行动就会收敛得多。有些时候我甚至会在委托书里让它自己先跑验证命令再把结果放进交付物里。这既能减少主Agent后续整合时的工作量也让Subagent在面对自己产出时更有主人翁意识。5. 多代理协作的调度与防失控技巧主Agent的驾驶课委托机制和委托书都就位之后真正的驾驶才刚刚开始。多代理协作能不能稳定产出取决于主Agent的调度能力以及你对失控风险的预判和兜底。这一部分全部来自我在真实项目里吃过的教训。5.1 当多个Agent要动同一份文件冲突管理的三个原则多代理最刺激的失误现场就是两个Subagent同时改同一个文件。我自己就经历过一次一个Agent在重构错误处理中间件另一个Agent在往同一文件里加日志埋点结果后完成的直接把先完成的改动覆写了跑完之后发现中间件逻辑丢了。后来我总结了三条原则来规避。第一在同一时间窗口内一个文件只能分配给一个Agent写即使是不同目录的文件如果有相互依赖也要写进委托书里标明依赖方。第二能做只读处理的信息收集任务一律用只读模式写权限只在拿到明确的写任务时才授予。第三不同Agent的改动文件范围之间要有隔离边界并统一由主Agent或你人工做最终合并。5.2 上下文精简是这个系统里最值钱的技能为什么有的多代理项目跑得很顺有的跑成了资源黑洞区别通常不在模型能力而在你到底往每个Subagent的上下文里塞了什么。很多调度者习惯把一段很长的分析报告原封不动传给下一个Agent觉得这样信息完整。但事实是信息完整不等于信息有效。过长的上下文不但增加延迟和成本还会稀释重点让Subagent抓不住关键细节。我的做法是主Agent只向下传「精简后的任务摘要」而不传原始分析长文。信息传下去之前做一个格式化压缩把结论、关键文件路径、验证命令、验收标准打包成结构化卡片再传原始分析留在主Agent自己的上下文里备查。这套习惯养成之后整体效率和稳定性至少上了一个台阶。5.3 失控预判什么时候该人工刹车多代理系统不是完全放养就行的。就算委托书写得再清楚Subagent也可能做出你完全没预料到的操作。所以主Agent需要一套失控判据一旦命中就主动暂停并寻求人工确认。我常用的判据包括改动文件数量超过委托书预估范围出现了委托书禁区里提到的文件路径Agent连续执行了多个写操作但没有对应更新交付物清单它开始自行启动重型命令如依赖安装、全局配置变更。任何一个条件命中最正确的动作不是让Agent继续自说自话地纠偏而是立刻停住把它的操作记录展出来由人来做一次快速判断。6. 从能用到好用搭一套基本的协作规范写到这里你已经掌握了多代理机制、委托书写法、调度防失控技巧。但这些都是单点能力真正让多代理协作产生稳定价值的是你把它们固化成一整套可复用的协作规范。规范的粒度不需要很重但一定要让每个人都能照着做并且让方案在团队里复制起来。6.1 在CLAUDE.md里固化你的协作约定Claude Code本身有CLAUDE.md这个记忆文件。多代理实践下来我最推荐的操作是把协作规范直接写进CLAUDE.md。比如写明默认情况下Subagent在执行任务前必须列出将要修改的文件清单并经过主Agent确认、禁止任何Agent执行会修改全局配置文件的操作、任务验收必须附上实际验证命令及其输出结果。这些约定一旦进了CLAUDE.md每次启动Claude Code会话时都会被自动加载相当于给每个新开的Agent都上了一课我们团队是怎么协作的。省去了每轮对话都要口头强调的烦恼也给了Agent一个强约束。6.2 让每个Subagent带上项目上下文卡除了全局约定我还习惯在项目里维护一份AGENTS.md或者类似的项目上下文卡里面包含项目的核心目录结构、技术栈、测试命令、构建方式以及常见的代码组织约定。每次委托时主Agent先把这份卡片摘出与任务相关的内容传入委托书这样Subagent不用翻遍整个仓库就能快速建立我该从哪里入手的认知大幅度减少前期探索成本。这个习惯的运行原理跟新员工入职一样——先把公司组织架构和常用工具链给他配上他才能快速进入干活状态而不是先花三天弄清楚我们这的代码往哪儿放。6.3 收集一次真实运行的数据用数字验证收益最后说一点关于做技术决策的态度。任何一套工作流都不是感觉好用就行把收益量化出来才能判断协作规范到底朝着正确方向演进。我之前在一个包含前后端的中型项目里做过对照组记录同一个「新增用户反馈导出功能」的需求单Agent模式总耗时接近1小时中途出现一次目标偏移换成三角色模式跑一遍耗时压到30分钟以内且交付物边界完全控制在需求范围内。类似这种数字比十句感觉高效多了更有说服力。而多代理带来的另一个隐性收益其实被很多人低估因为每个任务都有清晰的验收标准和独立的执行记录整个项目的可追溯性大大提升。哪一步做了什么、谁做的、依据是什么都有据可查。这在大项目里价值甚至比执行速度本身还高。最后关于工具和实践的边界我自己的体会是很多多代理不太行的结论往往是因为使用者的委托方式还停留在单代理时代的说一句话等结果的交互习惯上。把任务拆清楚、把边界钉死、把验收量化剩下的就是让这套系统替你完成那些重复性高、规则清晰的繁重工作。往后每接触一个新项目我会先花一个小时把协作规范搭出来再让Agent们进场。这一个小习惯是我目前能想到的最值得推荐给开始尝试多代理协作的人的一个开始。