把一个大项目直接丢给 Claude Code 单线程硬肝是很多人刚接触 Agent 编程时都会踩的坑。你让它一边重构后端、一边写前端页面、一边还要盯着测试跑结果就是上下文越来越臃肿它开始前面说过的话全忘了改一处接口另外三个文件跟着崩最后你不得不在一堆半成品里手动收拾残局。我就是从这种狼狈状态里走过来的后来认真研究了 Claude Code Agents 的多代理协作与任务委托机制才算是把 AI 编程的单人模式升级成了团队作战模式。这篇内容我会讲清楚多代理协作到底是怎么回事、什么样子的任务值得拆出去交给子代理、怎么在 Claude Code 里配置自定义 Agent 和 Skills、以及一次完整任务委托的实战复盘和常见问题排查。适合已经用过 Claude Code、但觉得单会话不够用的人也适合正在研究 Agent 工程化、想把 AI 编程从玩具推向生产力工具的开发者。读完你会发现多代理协作的核心其实不在多而在边界切得清楚。1. 多代理协作的本质从单兵作战到团队分工1.1 单会话的瓶颈为什么需要把任务交出去先说一个我在真实项目里反复撞见的场景。有一次我给 Claude Code 派了个任务让它给一个中等规模的 Web 项目加订单导出功能同时顺手把相关测试补一补。刚开始它跑得挺顺畅写了后端接口、改了前端按钮但当一个对话里的 token 越积越多它就开始精神涣散一会儿觉得订单字段应该用order_no一会儿又改回id测试文件里引用了一个根本不存在的导出函数它还信誓旦旦说已通过验证。这不是模型变笨了而是单个会话的上下文像一个越堆越乱的办公桌。所有历史内容——包括中间过程、错误尝试、无关讨论——都堆在主对话里模型每次生成都要在这个混乱现场里找线索出错率自然指数上升。更现实的问题是一个会话只能串行干活写接口的时候它没法同时去跑测试整体耗时被拉得很长。所以多代理协作不是锦上添花而是把一个人干所有事改成项目经理分派任务。Claude Code 里的主代理primary agent保留全局视野负责理解你的总目标、拆解任务、分派给合适的子代理、再收集结果做决策。子代理subagent则在一个隔离的上下文里专注干一件事干完把结果摘要交回来。1.2 子代理机制是怎么运转的Claude Code 的 Agents 体系里有两类子代理。第一类是内置的通用子代理比如专门负责代码搜索、文件读取、网页抓取、命令执行的角色它们在日常操作里会被主代理自动调用。第二类是你自己定义的项目级 Agent放在项目目录的.claude/agents/下每个 Agent 就是一份带 YAML 头部信息的 Markdown 文件定义了它的名字、职责描述、可调用的工具和模型。调度的核心逻辑并不神秘主代理拿到你的指令后会先判断当前任务是否匹配某个 Agent 的description描述如果匹配并且它认为这个任务适合隔离处理就会通过Task工具把这个子任务连同必要上下文一起交出去。子代理在执行过程中是单线程专注的看不见主对话里的历史也不受其他子代理干扰。多个互不依赖的子代理甚至可以并行启动各查各的、各写各的最后把结果汇总回主代理手里做集成判断。这种两段式结构很像真实团队里的汇报机制子代理不需要知道整个公司的商业机密只需要知道自己那一亩三分地的任务、输入和产出标准就够了。上下文隔离听着像是技术限制实际上省掉了大量互相干扰的噪声——这恰恰是任务准确率提升的关键。1.3 任务委托对应的现实分工模型用现实职场来类比你的主代理就是那个什么都要懂一点的项目经理子代理是各领域的专家。项目经理的职责不是把代码全部自己写完而是拆解需求、评估工作量、把设计文档甩给后端、把页面需求甩给前端、让测试人员去跑回归、最后把大家的产出拼起来看整体效果。这个类比帮我想通了一个关键问题项目经理最怕的不是专家能力弱而是任务边界模糊。你让前端专家去改数据库表结构让后端去调 CSS结果就是大家都在猜、都在返工。所以委托的本质是把正确的事交给正确的人而在 Agent 语境里正确的人由description描述和tools权限一起定义正确的事则由你在任务描述里给的上下文和验收标准定义。理解了这个模型再看 Claude Code 的多代理协作就很清楚了。它不是一个让你喊一句就全自动完成的魔法而是一个需要你亲手设计任务边界、定义验收标准、控制权限范围的工作流工具。把这个基础打牢后面所有配置和实操才有意义。2. 场景设计与任务拆解哪些活适合交给子代理2.1 适合委托的三种典型任务形态不是所有任务都适合拆出去。我的经验是适合委托的任务通常能归进下面这三种形态。第一种是可独立验证的探查型任务。比如在整个代码库里找出所有调用旧版sendEmail函数的位置并列出调用方的文件和行号搜索项目里所有硬编码的数据库连接串读一遍payment_service.py并总结它的错误处理逻辑。这类任务输入输出非常明确、不依赖外部状态子代理可以拿着文件路径自己去找找完汇报结果就行。我经常同时开两三个这种探查型子代理一个查 API 路由、一个查数据库模型、一个查前端调用链效率比我自己慢慢grep高出一大截。第二种是专一职责的实现型任务。像根据docs/contract.md里的字段定义实现order_export.py的导出逻辑给src/components/Chart.tsx写一个空状态样式用 Vitest 给utils/format.ts写完整单测——这类任务范围收敛、有清晰的代码文件作为边界子代理可以在隔离上下文里全力实现不会跑偏去改无关代码。第三种是按模板批量处理的机械化任务。把locales/zh-CN.json里所有缺失的 key 按英文文案补到locales/en-US.json给项目里所有*.stories.tsx文件补上Meta前置注释——重复性强、规则明确的任务特别适合让子代理批量执行省得主代理在对话里一遍遍重复相同指令。2.2 任务边界划分的四条实操原则拆任务时我踩了不少坑后来总结出四条原则基本能覆盖大多数情况。第一输入输出必须可描述。主代理在委托之前要能在任务描述里说清楚你从哪些文件开始、参考什么契约、最终产出什么格式的结果。如果这个任务连你自己都描述不清楚输入输出子代理只会更糊涂。我见过有人给子代理下优化一下这个项目这种命令子代理回复了一篇泛泛而谈的建议书等于没干。第二不依赖高频协同。两个子任务如果需要在执行过程中频繁同步状态——比如后端边改接口、前端边调接口、两边还要实时对齐字段——那就不适合拆开。拆出去的结果必然是两边各猜各的最后对不上。真正的多代理协作是任务之间有明确契约而不是任务之间有实时依赖。第三结果可验收。你或者主代理必须有一种方式判断子代理干得对不对比如编译通过、测试通过、diff 符合预期、文件内容包含关键字段。不可验收的任务委托出去之后你只会得到一封我干完了的假报告。第四权限边界清晰。给子代理配置tools时先想清楚它需要哪些工具。探查型任务只给Read和Grep实现型任务给Read、Write、Edit、Bash(Read-only)需要跑测试时再加执行权限。权限越窄误操作空间越小。2.3 粒度控制别把子代理当成万能执行器粒度问题是多代理协作里最容易犯的错而且犯错了代价很高。任务拆得太粗子代理面对一堆模糊目标只能按照自己的世界观去猜猜对了是你运气好猜错了就是一轮又一轮的追问和返工。任务拆得太细比如每三行代码修改就叫一次子代理调度开销和上下文切换损耗可能比你自己直接做还大。我个人的经验值是一次委托对应一个能在十分钟到二十分钟内完成、并且产出一个可以直接检查的成果的任务。举例来说给InvoiceService补上税率计算逻辑并附带单测是一档合理的任务重构整个订单模块并把前后端都改一遍就太粗了把total subtotal * 1.13改成total subtotal * (1 TAX_RATE)这种又太细。太粗的任务心里没底太细的任务又烦人所以我在实际操作中经常做一个预拆动作先让主代理输出一个任务拆解清单我把每个子任务在心里评估一遍如果是我本人来做需要多久、产出是什么超过二十分钟的继续拆不足五分钟的就合并。这个习惯帮我省了大量跟 Agent 纠缠的时间。3. 环境配置与自定义子代理实现3.1 安装与基础环境准备Claude Code 的安装方式有不少最常用的一路是走 npm 全局安装。终端里执行npm install -g anthropic-ai/claude-code装完运行claude进入交互界面首次使用需要完成账号登录或配置 API Key。除了命令行终端官方也有桌面端以及 VS Code 插件这几个渠道底层打通的是同一套 Agent 机制不影响后续多代理配置。如果你更习惯编辑器内开发装个插件直接侧边栏里开会话也很方便。关于模型接入多说一句Claude Code 默认连 Anthropic 的服务但如果你有特殊需要比如想接 DeepSeek 或者其他兼容 Anhtropic 接口格式的模型服务也可以通过设置ANTHROPIC_BASE_URL这类环境变量来指向兼容端点。这个思路适合想尝试不同模型的开发者但要注意一点Claude Code 的 Agent 工具链依赖模型自身的工具调用能力不是所有模型都能完整、稳定地执行多步 Agent 流程。实际体验下来专用模型配合专用工具框架才是最稳的第三方接入更适合做调研和成本对比。多代理相关的几个配置参数里我特别提醒一个子代理的并行数量和上下文策略在不同版本里有过调整升级 Claude Code 后最好重新翻一下官方文档不要拿旧版的经验直接套新版。我遇到过升级之后任务委托行为变了、排查半天才发现是版本差异的情况。3.2 自定义 Agent 的配置结构自定义 Agent 的核心落在.claude/agents/目录。每个 Agent 是一个 Markdown 文件文件名无所谓但文件开头的 YAML frontmatter 里有几个字段会直接决定调度行为我用一个例子说明。--- name: code-reviewer description: 负责代码审查擅长发现潜在 bug、安全问题、逻辑漏洞和可维护性隐患。当用户提交新代码、要求审查某个模块或检查合并请求质量时使用本代理。 tools: Read, Grep, Glob, Bash(Read-only) model: sonnet ---这个name是子代理在对话中显示和调用的标识。description最关键——主代理就是靠读这段描述来判断当前任务是否该委托给这个 Agent。所以描述里一定要写清楚什么情况下触发我最好包含明确的关键词和场景词。tools决定子代理能调用哪些工具控制它不会乱动手修改代码。model可以留空继承默认也可以单独指定更快或更强的模型实现分级调度。frontmatter 下面是正文就是子代理的系统提示词。你可以在这里面写清楚角色的目标、工作流程、输出格式、以及最重要的不要做什么。比如 code-reviewer 的正文我会写你的任务是审查而非修复代码不要主动修改任何文件只需输出结构化审查报告。我在第一次配置时犯过一个典型错误把description写得特别抽象比如一个帮助开发的助手结果主代理几乎任何任务都会考虑它反而干扰了调度判断。后来把description改成高度具体的触发描述调度才变得精准。我这里再强调一次触发词要具体到什么场景而不是什么角色。3.3 用 Skills 给子代理追加专项技能自定义 Agent 定义了谁来干Skills 则定义了怎么干。Claude Code 的 Skills 目录放在.claude/skills/下每个 Skill 是一个包含SKILL.md的文件夹头部同样带 YAML frontmatter声明技能的名称和描述正文则写清楚操作流程、代码模板、注意事项等。比如我给项目配置了一个生成单元测试的 Skill内容就是这套流程先读源文件识别需要覆盖的分支和边界条件按照项目既有的测试风格生成测试文件最后运行测试并汇报覆盖率变化。有了这个 Skill 之后不管哪个子代理负责写测试它都能按统一的流程执行不会自己发明一套风格。Agent 和 Skill 的组合方式是灵活多变的。你可以给一个后端实现Agent 挂上生成接口文档Skill让它在写完接口后顺手产出文档也可以给一个文档维护Agent 挂上多个 Skill让它承担不同文档类型的生成。我的经验是Agent 负责定义角色和权限边界Skill 负责定义操作细节和项目规范。项目规范放进 Skill 里还有一个好处——团队其他同事拉取项目后自动获得同样的技能不需要再口头交代。3.4 委托指令的落地Task、 提及与主代理调度配置好自定义 Agent 后实际委托有几种触发方式。第一种是对话里直接agent名 任务描述比如code-reviewer 请审查一下 feature/export 分支上 src/services/export.ts 的改动。这种方式显式指定了子代理适合你心里已经清楚该让谁干活的情况。主代理收到这个指令后会把任务转交给对应 Agent子代理拿到必要上下文后开始执行。第二种是隐式调度。你不对着某个 Agent 说话而是在主对话里提出一个总目标主代理会根据自己的判断把任务拆开、分派给不同 Agent。这要求你的自定义 Agent 描述写得足够清楚主代理才能做出正确决策。我实际用下来隐式调度更适合探索型任务显式提及更适合你已经明确了边界和归属的执行型任务。第三种是Task工具。主代理在调用工具的时候会动态构造一个任务描述附上需要的文件路径和上下文交给你指定的子代理。这个工具可以嵌套调用也就是说子代理自己也能再委托给其他子代理但我不建议过度嵌套层级越深、调度链路越长出错概率越大而且调试成本翻倍。无论哪种触发方式主代理最后都会收集子代理的结果摘要再基于全局上下文做整合判断。所以在实际操作中你更多的精力应该放在任务描述本身的质量上——描述越精确结果越可靠。4. 多代理协作实战一次完整任务的委托过程复盘4.1 项目背景与总任务拆解纸上谈兵说再多不如完整走一遍流程。我拿最近一个真实项目来复盘一个内部使用的订单管理系统用 TypeScript 写的后端 Node.js 服务和前端 React 应用代码在同一个仓库里跑。需求就一句话——添加订单导出功能支持按日期范围筛选并补好测试和文档。这句话如果直接丢给单会话去干结果就是我开头说过的那种混乱状态。所以我把总任务拆成四块后端接口实现、前端页面与下载交互、自动化测试、README 和 API 文档更新。前三个可以并行文档可以在接口完全定稿后再写避免文档跟着代码反复改。拆完的委托清单长这样backend-agent在src/routes/下新增/api/orders/export接口按查询参数startDate和endDate筛选订单导出 CSV 格式文件。frontend-agent在订单列表页新增导出按钮点击后调用后端接口并处理文件下载需要做加载状态和错误提示。tester-agent为后端导出接口编写集成测试mock 订单数据覆盖正常导出、空结果、日期格式错误三个场景。docs-agent更新 README 中的功能列表新增 API 文档段落说明接口参数和返回格式。4.2 三个子代理的并行执行与结果回收实际执行时我先在 Claude Code 里显式调用了三个实现型子代理backend-agent、frontend-agent、tester-agent把各自的输入上下文给足——后端拿到订单数据模型的字段定义、前端拿到按钮应该插入的位置和 API 地址格式、测试拿到接口的预期行为描述。三个子代理并行跑起来之后主对话的负载立刻降下来了。我不用再看一堆中间过程输出只要等待结果摘要回收。子代理们各自在隔离上下文里写代码、跑工具也不会互相污染。比如前端子代理在改组件样式时完全不会碰到后端子代理正在调整路由代码的这种问题。最后三份结果差不多同时回收后端接口实现完成、前端按钮和下载逻辑就位、测试文件写好了但测试还没跑。这里有个关键操作——我让主代理先汇总三方的产出用 Git diff 快速检查一遍改动范围确认每个子代理都没越界改动不属于自己职责的文件。责任心是有了但我的检查步骤不能省。4.3 从失败中修正委托边界调整的两次迭代这次实战不是一次成功的。第一轮委托结束后我跑到前端页面一测下载发现导出的 CSV 里日期格式跟后端序列化格式不一致——前端期望YYYY-MM-DD后端给的是 ISO 格式。问题不在模型笨而在我拆任务时没把日期格式这个契约写进任何一方的任务描述里后端子代理按自己的理解实现前端子代理也按自己的理解解析两边自然对不上。第二轮修正就很简单了我先让backend-agent把接口输出字段中的date改成YYYY-MM-DD格式并在任务描述里明确写上前端会按该格式解析不允许其他格式然后让前端子代理重新跑一遍下载流程做验证。这次修正只花了十几分钟而如果是在单会话里干我恐怕要翻遍上下文找到底哪一步约定丢了。我印象最深的教训是多代理协作的失败大多数时候不是模型执行能力不足而是任务描述里缺失了契约信息。后来我养成了一个习惯每个委托任务描述里都加一句输入格式是什么、输出格式是什么、两边靠什么契约对齐这个习惯把跨代理协作的失败率压下来一大半。补完测试之后我还做了一次整体验收让tester-agent运行全部测试让docs-agent根据最终代码状态更新 README最后自己手动跑了一遍导出流程确认功能可用。整个过程耗时比单会话串行做快了差不多一半而且每个环节的结果都可独立检查出了问题也定位得快。5. 常见问题与排查技巧实录5.1 委托不生效description 字段没写好有段时间我的自定义 Agent 几乎不会被主代理主动调起来查了半天问题全在description上。最开始我写的是负责后端开发的助手这个描述太宽泛了主代理判断什么任务都想塞给它反而导致选择困难最后干脆自己干了。后来我把描述改成当需要新增后端 API 路由、修改数据库模型字段定义、编写服务层业务逻辑时使用主代理立刻就能精准匹配了。如果你也遇到委托不生效先检查三件事Agent 文件是否放在项目根目录的.claude/agents/下而不是子目录里描述里是否包含当前任务相关的场景关键词以及新会话有没有加载最新的 Agent 列表。改完配置建议重开一个会话让主代理重新读一遍项目配置。5.2 上下文隔离与结果回收问题上下文隔离是子代理最大的优点但也带来一个反作用——主代理拿到的通常只是摘要细节会丢失。我遇到过子代理自信满满地报告测试全部通过但我一查日志发现它根本没运行测试只是做了个静态检查就下了结论。解决方案是明确要求子代理把关键产出写进文件或者把关键 diff 贴回来。我的做法是在 Agent 的正文提示词里加一句输出结果时必须提供具体文件的 diff 摘要或执行日志中的关键输出禁止只汇报结论。这样主代理才能拿到可验证的中间产物而不是一个不可信的口头汇报。另外如果某次协作需要完整保留子代理的上下文而不想被摘要截断可以考虑让它把完整结果写入一个临时文件主代理需要时再读取。5.3 模型适配与费用控制经验多代理协作会显著消耗更多的 token因为每个子代理都在独立的上下文里工作这些上下文在任务结束后会被释放但释放前的消耗是要付费的。如果你是 API 计费模式又不做控制月底账单会让人心疼。我的费用控制策略是分级调度探查型、总结型、搜索型任务用体积小、速度快的模型跑因为这类任务不需要太强的推理能力实现型、重构型、代码审查型任务才用最强模型。这个策略在自定义 Agent 时就可以落地每个 Agent 的model字段单独指定费用效率比统一用最强模型提升很多。还有一个容易被忽略的点并行子代理虽然省时间但 token 消耗是同时发生的。如果项目预算紧张可以限制并行的子代理数量一次只放两个出去而不是一股脑全开。多代理协作省下来的时间如果折算成开发成本通常还是划算的但你心里得有一本账。5.4 多代理协作的快问快答速查表问题表现可能原因解决方案主代理从不调用自定义 Agentdescription太宽泛模糊主代理难以匹配重写描述用具体场景词和触发关键词Agent 改了职责之外的文件tools权限过宽收紧tools只保留 Read/Edit 等必要权限子代理汇报成功但结果不可用正文没有要求输出可验证的中间产物在提示词中要求返回 diff、日志或写入文件跨代理协作后字段/格式对不上任务描述里缺少契约约定给每个相关 Agent 写明输入输出格式并行跑完 token 消耗暴增并行数量太多、模型选择过重限制并行数按任务类型分配快慢模型新配置的 Agent 在新会话里用不了Agent 文件放错目录或没重开会话确认在项目根目录.claude/agents/下并重开这个表里的每一条都是我实际踩过或者帮同事排查过的你可以把它当成一份排查手册存在手边。写在最后的实践心得我实际用下来的体会是让多代理协作真正变稳的核心不是把任务描述写得多花哨、也不是把 Agent 配置得多复杂而是你愿意在前置拆解上花多少时间。宁可多花十分钟把边界、契约和验收标准写清楚也不要省这十分钟、后面花一个小时在返工里追悔。还有一个我觉得特别有用的小技巧每个子代理的任务描述里开头第一句先写不要做什么再写要做什么。比如 不要修改任何与导出功能无关的文件不要在回复里粘贴完整源码只返回 diff 摘要。这个反向约束的效果出奇得好因为模型在开放式任务里最容易出的问题不是能力不足而是发散和越界提前划好禁区比事后纠正高效得多。多代理协作这套玩法后续还可以继续扩展比如把 Agent 的配置做成团队共享的仓库模板让所有同事拿到项目后自动获得一致的分工规范或者把 Skills 文档化沉淀成项目资产让新上手的人也能快速理解每个角色该干什么。我在项目里已经开始这么做了效果比我预期得还要好。希望这份经验也能帮你把 Claude Code 从单线程聊天工具真正变成能打硬仗的团队伙伴。
