如果你用 Claude Code 跑过稍微大一点的工程任务大概率会碰到同一个问题单代理干活虽然麻利但所有事情都得排队改完一个文件才能去碰下一个。遇到那种“这里改完、那里才能动工”的耦合流程一蹲就是一整天。这篇文章想聊的不是怎么把单个 Claude Code 用得更熟而是怎么把多个 Claude Code Agents 组织起来用多代理协作的方式拆解任务、并行推进真正把并行任务自动化跑起来。我自己是在处理一次中型项目重构时动了这个念头。那次重构涉及十几个模块如果只开一个 Claude Code 实例它会老老实实地按顺序处理先读 A 模块再改 B 模块中途还要回头确认之前的结果。明明很多模块之间根本没有依赖却硬是被串行执行拖慢了节奏。后来我花了一周时间把多代理协作的流程跑通同样的工作量三四个 Agent 并行作业整体耗时压缩了将近一半。这篇文章适合两类人一类是用过 Claude Code 基础命令、想进一步提升开发效率的工程师另一类是对 AI Agent 多代理协作模式感兴趣、想知道怎么落地而不是只看概念的技术爱好者。我会从多代理能解决什么说起再讲 Claude Code 的 Agent 配置、并行任务拆解原则、两种实操方案最后把我在实际项目中踩过的坑和排查方法全部列出来。建议你跟着第三部分的实操步骤走一遍大概两个小时就能搭出自己的一支 AI 小队。1. 为什么单代理不够用——多代理协作解决的问题1.1 单代理模式的三个瓶颈单代理不是不好用而是当你把任务规模抬到一定程度之后它会出现几个非常明显的瓶颈。第一个瓶颈是上下文负担。Claude Code 在单次会话里会不断积累项目的阅读内容、文件修改记录、命令执行输出。任务一长早期处理过的模块细节就会被后续内容冲淡代理开始“忘记”自己前面改过什么甚至出现前后矛盾的操作。我见过最典型的场景是代理先重构了一个公共工具函数后来在另一个文件里又按照旧签名调用它结果编译直接报错。这就是上下文窗口被长任务撑爆后的常见副作用。第二个瓶颈是串行等待。单代理只有一对眼睛、一双手它处理完一个子任务才会开始下一个。可现实中的工程任务往往是网状的前端页面、后端接口、数据库迁移脚本这三件事之间没有严格先后关系完全可以同时做。但在单代理模式下不管你愿不愿意它们都被排成一条直线总耗时就是所有子任务耗时的累加。第三个瓶颈是任务切换开销。有人会说那我让单代理先做一部分再切去做另一部分不就行了可以但代理每一次“切换”都得重新读取对应模块的代码、回忆之前的上下文这个重新理解的过程会消耗大量 token 和时间。切换几次之后你会发现它光“热身”就花掉了不少成本实际产出反而下降。1.2 多代理协作的本质把大任务拆成可并行的子任务多代理协作的思路其实非常简单既然一个代理干不完、干得慢那就开多个代理每个代理只负责一块边界清晰的任务大家同时开工最后再合到一起。这就好比一个人装修房子只能按顺序刷墙、铺地、装灯但如果让一个团队同时进场刷墙的人、铺地的人、装灯的人各干各的工期自然大幅缩短。不过这里有个关键前提多代理并行不是简单地把同一个 Claude Code 开好几个窗口。如果两个代理同时去改同一个文件、同一个函数那不是在并行而是在制造冲突。真正有效的多代理协作要求每个代理都有独立的职责范围、独立的上下文记忆、独立的产出物只在约定的接口处发生交集。我总结下来Claude Code 场景下的多代理协作有三种典型模式。第一种是并行执行模式多个代理各自处理互不依赖的模块最后合并这是最常见的用法。第二种是流水线模式代理 A 的输出作为代理 B 的输入比如代理 A 生成接口文档代理 B 基于文档实现代码代理 C 再基于实现写测试。第三种是主从委派模式一个主代理负责拆解任务、分派给多个子代理并汇总结果这种模式更接近 Claude Code 里 Subagents 的原生玩法。这三种模式各有适用场景但不管哪种核心都是同一件事把任务边界划清楚。边界越清晰代理之间的协作成本越低并行效率越高。2. Claude Code Agents 基础配置与前期准备2.1 安装与环境要求先说安装这块其实很简单。Claude Code 官方支持 macOS、Windows 和 Linux只要你本机有 Node.js 18 以上版本一条命令就能装好npm install -g anthropic-ai/claude-code安装完成后在终端里执行claude就能进入交互式界面首次启动会让你登录 Anthropic 账号并完成认证。如果你更习惯图形化操作也可以在 VS Code 的扩展市场里搜索 Claude Code 安装插件在编辑器底部打开 Claude Code 面板和终端里用起来没有本质区别。官方还提供了桌面版客户端下载安装后同样可以操作。这里有一个很多新手会忽略的点Claude Code 默认走的是 Anthropic 官方 API需要账号里有对应的 API 额度或订阅权限。社区里也有不少朋友通过兼容层配置把模型接入到 DeepSeek、GLM 这类服务上适合对成本敏感的场景。不过我不建议在刚开始玩多代理时就切换模型先用默认配置跑通流程再说否则出了问题很难定位是模型的问题还是你配置的问题。2.2 理解核心概念CLAUDE.md、Subagents、权限模型在动手配置多代理之前有三个核心概念必须先弄清楚CLAUDE.md、Subagents 和权限模型。CLAUDE.md 是 Claude Code 的项目记忆文件放在项目根目录下。每次启动代理时它都会自动读取这个文件相当于给代理一份“项目说明书”。你可以在这个文件里写清楚项目的架构、代码规范、常用命令、目录结构、各模块职责甚至包括代理之间需要遵守的协作约定。我见过不少团队把 CLAUDE.md 写得像一份迷你版设计文档效果非常好代理犯低级错误的概率明显下降。Subagents 是 Claude Code 里专门用于委派任务的子代理机制。主代理在对话过程中可以根据需要把某个子任务转交给一个专职子代理来处理。每个子代理可以有自己的角色定义、系统提示词、可用工具集合。比如你可以定义一个“代码审查子代理”它的职责只负责审查代码质量工具只开放读文件和运行静态检查不给它修改文件的权限。这种角色分离让协作结构更清晰也让主代理的压力大大减轻。权限模型则是安全底线。Claude Code 对代理能执行的操作做了分级控制分成允许、拒绝、询问三种策略。你可以在启动时通过命令行参数指定比如--permission-mode acceptEdits表示自动接受对已有文件的编辑--permission-mode plan则让代理只规划不执行。对于需要人工把关的关键操作保留询问模式是最稳妥的做法。2.3 创建自定义 Agent 与能力边界设定理解完概念就可以开始创建自己的 Agent 了。Claude Code 支持在项目里的.claude/agents目录下定义自定义子代理每个代理用一个 Markdown 文件描述格式大致是这样的--- name: backend-developer description: 负责后端接口开发与单元测试编写适合处理 API、数据库相关任务 tools: Read, Write, Edit, Bash model: claude-sonnet-4-5 --- 你是一名资深后端工程师。在收到任务时先阅读项目中相关模块的代码理解现有架构 然后按 CLAUDE.md 中的规范实现功能。要求 1. 每个新增接口必须补充单元测试 2. 代码风格遵循项目既有约定 3. 完成后输出变更文件清单和测试结果这里的name是子代理的唯一标识description告诉主代理什么时候该把任务委派给这个子代理tools限制了它可用的工具范围model可以指定不同的模型版本。系统提示词部分则是你给这个代理定的人设和做事规范。我觉得创建代理时最值得花心思的是两点。第一点是职责要窄。一个代理只干一类事不要搞一个“全能代理”。你越想把所有能力塞进去它在具体任务上的表现就越平庸。后端代理就只管后端前端代理就只管前端文档代理就只管文档泾渭分明。第二点是工具权限要收得紧。不要给代理开无限制的 Bash 权限尤其当它要处理的是生产环境相关任务时。我自己的习惯是默认只给读写文件权限需要执行命令时单独开放并让关键操作走询问模式。这样即使代理跑偏了也不会造成不可挽回的破坏。3. 并行任务自动化的设计与实操3.1 任务拆解原则什么任务适合并行、什么不适合多代理并行的第一步不是启动代理而是拆任务。任务拆得好不好直接决定并行是加速还是灾难。适合并行的任务有三个特征。第一是依赖关系清晰。两个子任务之间要么没有依赖要么只通过一个明确的接口依赖。比如“前端调用后端接口”这种依赖只要双方先约定好接口格式前端就可以用 mock 数据先开发后端按约定实现两边完全可以同时推进。第二是没有共享写入冲突。两个代理不要同时修改同一个文件。如果必须改同一份代码那要么把文件拆开要么约定好先后顺序要么让其中一个代理只做代码审查而不做修改。我在实战中吃过这个亏两个代理同时改一个工具类一个加了新方法一个改了旧方法签名合并代码时冲突多到我怀疑人生。第三是验收标准可量化。每个子任务完成后能有一个明确的东西证明它做完了测试通过了、接口返回了预期结果、文档生成了。这个“明确的验收标准”是多代理并行的基石没有它你就无法判断代理到底干完没有。不适合并行的任务也不少。强顺序依赖的流程比如“先设计数据库表结构再写业务逻辑”这种后者依赖前者的任务强行并行只会导致返工。需要全局综合判断的任务也不适合比如“统一重构整个项目的错误处理机制”这种事单代理做反而更协调多代理各改各的只会改出一堆风格不一致的代码。3.2 实操方案一多终端多个 Claude 进程手动并行最轻量的多代理并行方案是手动开多个终端每个终端里启动一个 Claude 进程各自负责一个子任务。这种方式不需要写任何代码适合临时性的并行需求和小型项目。具体做法是先给每个子任务建独立的工作目录或者独立的 git 分支避免文件冲突。比如开发一个新功能我通常会拉三个分支feature/api、feature/frontend、feature/db。然后在三个终端里分别执行cd /path/to/project git checkout feature/api claude --permission-mode acceptEdits每个终端里的 Claude 会读取各自分支下的代码互不干扰。完成一个子任务后提交代码、合并分支再启动下一轮。这种方式的好处是灵活、直观随时能看到每个代理在干什么。坏处是没法同时对超过四五个代理做精细管理而且每个终端占用一个窗口操作多了之后容易乱。我一般会用一个简单的 bash 脚本把启动过程固化下来省得每次手动敲#!/bin/bash # 并行启动三个代理分别处理 api、frontend、db 三个子任务 tasks(api frontend db) for task in ${tasks[]}; do gnome-terminal -- bash -c cd /path/to/project git checkout feature/$task claude --permission-mode acceptEdits; exec bash done注意这里我用的是gnome-terminal你在 macOS 上可以换成osascript或者直接用 iTerm2 的 split pane 手动开窗口效果一样。3.3 实操方案二基于 Claude Agent SDK 编排多代理如果你需要的是更程序化、可重复执行的并行流程那就要用 Claude Agent SDK。官方提供了 TypeScript 和 Python 两种版本我日常用 Python 比较多因为做工程自动化脚本方便。先安装 SDKpip install anthropic-agent-sdk然后可以用类似下面的代码在同一进程里并发启动多个代理任务import asyncio from anthropic_agent_sdk import Agent async def run_backend_task(): agent Agent( namebackend-developer, modelclaude-sonnet-4-5, cwd/path/to/project, permission_modeacceptEdits, ) result await agent.query( 在 backend 模块新增用户注册接口 /api/v1/register参考 CLAUDE.md 中的接口规范并补充单元测试 ) return result async def run_frontend_task(): agent Agent( namefrontend-developer, modelclaude-sonnet-4-5, cwd/path/to/project, permission_modeacceptEdits, ) result await agent.query( 在 frontend 模块新增注册页面调用 /api/v1/register 接口先使用 mock 数据 ) return result async def main(): results await asyncio.gather(run_backend_task(), run_frontend_task()) for r in results: print(任务完成耗时:, r.duration_seconds) print(输出摘要:, r.result[:200]) if __name__ __main__: asyncio.run(main())这段代码的核心是asyncio.gather它会让两个代理同时开始执行整体耗时约等于最慢的那一个而不是两者之和。每个Agent实例都有独立的工作目录、独立的系统提示词、独立的会话上下文互不干扰。用 SDK 的好处是灵活你可以在代码里写各种逻辑任务失败自动重试、按依赖关系串行编排、收集所有子任务结果后统一汇总。坏处是初次上手要写点代码对完全没有编程基础的人来说门槛稍高。但如果你想做真正的“并行任务自动化”SDK 这条路早晚要趟一遍。3.4 并行过程中的上下文隔离与共享机制多代理并行还有一个绕不开的问题上下文怎么隔离、信息怎么共享。隔离的目的一是防止代理之间互相干扰二是控制每个代理的上下文长度避免它读太多无关内容导致性能下降。我通常的做法是在 CLAUDE.md 里写清楚每个模块的边界并在给代理的任务描述里明确指定它只需要关注哪些目录。比如后端代理的任务描述里直接写“只读取 backend/ 目录下的代码不要修改 frontend/ 目录”这样代理就不会越界。共享的关键则是契约先行。两个代理要做的事情如果有交集那这个交集必须提前固定下来。最典型的就是前后端接口约定。我在实战中会让后端代理先产出一份 OpenAPI 规范的接口文档提交到仓库然后前端代理严格按这个文档开发而不是靠猜。这个接口文档就是两个代理之间的“合同”谁也不能单方面改。另外一个实用技巧是给每个代理独立的日志文件。SDK 模式下可以在启动代理时配置日志输出路径这样每个子任务的执行过程都有据可查。手动模式下就让每个终端窗口的日志分别重定向到不同文件。出了问题不看猜测直接看日志就行。4. 多代理协作实战复盘一次前后端并行开发记录理论说了不少我拿一次真实做过的功能开发来复盘整个过程。这个功能是给一个内部管理系统增加“用户积分流水查询”页面涉及数据库、后端接口和前端页面三块内容非常典型。第一步是定义契约。我没有急着让代理开工而是自己先把积分流水表的结构、需要用到的几个接口路径、请求参数和返回字段列出来整理成一份 OpenAPI 文档放在docs/api/points-flow.yaml。这个步骤大概花了我四十分钟但它为后面所有并行工作奠定了基矗。第二步是拆分任务并分派给三个代理。数据库代理负责写迁移脚本新增points_flow表并造几条测试数据后端代理负责实现GET /api/v1/points-flow接口按 OpenAPI 文档实现附带单元测试前端代理负责写查询页面调用这个接口在接口没通之前用 fixture mock 数据渲染。三个任务之间除了那份 OpenAPI 文档之外没有任何交集完全可以并行。第三步是启动并行执行。我用的是 SDK 方式写了类似上一节里的脚本三个代理同时跑。整个执行过程大概持续了九分钟后端代理最快完成前端代理其次数据库代理因为要执行真实迁移慢了几分钟。三个代理都完成后我检查了各自的产出物迁移脚本能正确建表后端接口返回的数据结构符合契约前端页面的样式和交互都对得上。合并代码时出了问题。前端代理在我约定的字段里使用了一个createdAt但后端代理在实现时把时间字段命名成了createTime。两个代理都严格遵循了各自看到的契约但契约文档本身存在一处不一致。这种问题在人工开发时也会出现好在有代码审查环节兜底我让前端代理按后端实际返回值做了一次适配修复几分钟就解决了。第四步是联调验证。接口通了之后我让一个专门的测试代理只干一件事根据需求描述写端到端测试脚本直接调用真实接口、操作真实页面验证整个流程是否完整。测试代理还顺手发现了一个边界问题积分流水为空时接口返回的total字段是0但前端页面没有做空态处理会显示一个空表格而不是“暂无数据”的提示。这个问题交给前端代理修复效率很高。这次复盘给我的感受是多代理并行真正节省的不是编码时间而是“等待时间”。传统串行开发里前端要等后端接口好了才能联调数据库要等表结构定稿才能动手这些等待在并行模式下都被压缩掉了。但前提是契约阶段的工作必须做扎实契约不牢后面并行越快返工越多。5. 常见问题与排查技巧实录5.1 高频问题速查表多代理并行做了几轮之后我整理了一份高频问题速查表基本覆盖了大多数会踩的坑问题现象可能原因解决方案两个代理改了同一文件合并冲突任务拆分时没做文件隔离拆分任务时明确每个代理可写的目录和文件接口联调时字段对不上OpenAPI 契约文档本身不一致在契约阶段做好接口文档评审所有代理严格以此为唯一标准某个代理长时间无响应上下文窗口太长模型处理变慢检查代理是否有读入无关内容减少任务范围多个代理同时调用 API 被限流超出账号的并发请求限制降低并行数或错峰启动任务代理不按约定输出、自由发挥系统提示词约束不足在任务描述中明确输出格式和验收标准一个任务失败后其他任务白做任务之间存在隐性依赖并行执行前梳理依赖图有硬依赖的任务不要并行5.2 排查方法与避坑心得排查多代理问题我的经验是“先看日志再看契约最后看代码”。每个代理的执行过程都有日志日志里能看到它读了哪些文件、执行了哪些命令、输出是什么。很多问题从日志里一眼就能看出来比如代理把项目根目录当成工作目录导致找不到文件或者它执行了一个构建命令然后陷入死循环这些都是热词云里提到过的常见翻车现场。另一个心得是让小代理先出计划再干活。我在任务描述里通常会让代理在执行前先输出一个简短的实施计划比如“我打算先阅读什么文件再修改什么文件最后如何验证”。这个计划一出来我就能判断它的思路对不对。如果思路不对直接中止重来比让它埋头干完再返工省太多时间。还有一个避坑技巧是关于并行数量的。很多新手容易走入一个误区觉得并行代理开得越多越好。实际上并行数量受三个因素约束API 速率限制、项目文件竞争度、任务拆分质量。我自己测下来的经验是普通中型项目同时跑三到五个代理是比较舒适的区间超过这个数量代理之间互相踩脚的概率会指数级上升。并行不是目的稳定地完成自动化才是目的。最后不得不提的是安全风险。多代理并行意味着工具的调用面变大了攻击面也跟着变大。特别是当代理需要访问网络上不可信的内容时存在 prompt injection 的风险外部输入里可能夹带恶意指令诱导代理执行非预期操作甚至把这套指令再传给其他代理。这个方向在安全顶会 NDSS 2026 也有专门研究讲的就是针对 LLM Agent 工具选择的注入攻击。我的实操原则很简单不信任不可信来源的输入网络权限能收窄就收窄关键操作一律开人工确认。宁可牺牲一点自动化程度也不能把执行权完全交给一个可能被带偏的代理。我在实际使用中还有一个体会多代理协作真正难的从来不是技术配置而是任务边界的划分和管理。代理本身再聪明面对一个职责模糊、依赖混乱的任务也会变成无头苍蝇。与其花时间调更多的参数不如多在任务拆分和契约定义上下功夫。这两件事做好了Claude Code Agents 的威力才会真正发挥出来。最后再分享一个小技巧初期可以从两个代理并行开始练手比如“写代码的和写测试的各一个”跑通之后再逐步加码。这个节奏能让你的任务拆解能力跟着一起成长——它才是你在这条路上收获的最值钱的东西。
Claude Code多代理协作实战：并行任务自动化提速方案
如果你用 Claude Code 跑过稍微大一点的工程任务大概率会碰到同一个问题单代理干活虽然麻利但所有事情都得排队改完一个文件才能去碰下一个。遇到那种“这里改完、那里才能动工”的耦合流程一蹲就是一整天。这篇文章想聊的不是怎么把单个 Claude Code 用得更熟而是怎么把多个 Claude Code Agents 组织起来用多代理协作的方式拆解任务、并行推进真正把并行任务自动化跑起来。我自己是在处理一次中型项目重构时动了这个念头。那次重构涉及十几个模块如果只开一个 Claude Code 实例它会老老实实地按顺序处理先读 A 模块再改 B 模块中途还要回头确认之前的结果。明明很多模块之间根本没有依赖却硬是被串行执行拖慢了节奏。后来我花了一周时间把多代理协作的流程跑通同样的工作量三四个 Agent 并行作业整体耗时压缩了将近一半。这篇文章适合两类人一类是用过 Claude Code 基础命令、想进一步提升开发效率的工程师另一类是对 AI Agent 多代理协作模式感兴趣、想知道怎么落地而不是只看概念的技术爱好者。我会从多代理能解决什么说起再讲 Claude Code 的 Agent 配置、并行任务拆解原则、两种实操方案最后把我在实际项目中踩过的坑和排查方法全部列出来。建议你跟着第三部分的实操步骤走一遍大概两个小时就能搭出自己的一支 AI 小队。1. 为什么单代理不够用——多代理协作解决的问题1.1 单代理模式的三个瓶颈单代理不是不好用而是当你把任务规模抬到一定程度之后它会出现几个非常明显的瓶颈。第一个瓶颈是上下文负担。Claude Code 在单次会话里会不断积累项目的阅读内容、文件修改记录、命令执行输出。任务一长早期处理过的模块细节就会被后续内容冲淡代理开始“忘记”自己前面改过什么甚至出现前后矛盾的操作。我见过最典型的场景是代理先重构了一个公共工具函数后来在另一个文件里又按照旧签名调用它结果编译直接报错。这就是上下文窗口被长任务撑爆后的常见副作用。第二个瓶颈是串行等待。单代理只有一对眼睛、一双手它处理完一个子任务才会开始下一个。可现实中的工程任务往往是网状的前端页面、后端接口、数据库迁移脚本这三件事之间没有严格先后关系完全可以同时做。但在单代理模式下不管你愿不愿意它们都被排成一条直线总耗时就是所有子任务耗时的累加。第三个瓶颈是任务切换开销。有人会说那我让单代理先做一部分再切去做另一部分不就行了可以但代理每一次“切换”都得重新读取对应模块的代码、回忆之前的上下文这个重新理解的过程会消耗大量 token 和时间。切换几次之后你会发现它光“热身”就花掉了不少成本实际产出反而下降。1.2 多代理协作的本质把大任务拆成可并行的子任务多代理协作的思路其实非常简单既然一个代理干不完、干得慢那就开多个代理每个代理只负责一块边界清晰的任务大家同时开工最后再合到一起。这就好比一个人装修房子只能按顺序刷墙、铺地、装灯但如果让一个团队同时进场刷墙的人、铺地的人、装灯的人各干各的工期自然大幅缩短。不过这里有个关键前提多代理并行不是简单地把同一个 Claude Code 开好几个窗口。如果两个代理同时去改同一个文件、同一个函数那不是在并行而是在制造冲突。真正有效的多代理协作要求每个代理都有独立的职责范围、独立的上下文记忆、独立的产出物只在约定的接口处发生交集。我总结下来Claude Code 场景下的多代理协作有三种典型模式。第一种是并行执行模式多个代理各自处理互不依赖的模块最后合并这是最常见的用法。第二种是流水线模式代理 A 的输出作为代理 B 的输入比如代理 A 生成接口文档代理 B 基于文档实现代码代理 C 再基于实现写测试。第三种是主从委派模式一个主代理负责拆解任务、分派给多个子代理并汇总结果这种模式更接近 Claude Code 里 Subagents 的原生玩法。这三种模式各有适用场景但不管哪种核心都是同一件事把任务边界划清楚。边界越清晰代理之间的协作成本越低并行效率越高。2. Claude Code Agents 基础配置与前期准备2.1 安装与环境要求先说安装这块其实很简单。Claude Code 官方支持 macOS、Windows 和 Linux只要你本机有 Node.js 18 以上版本一条命令就能装好npm install -g anthropic-ai/claude-code安装完成后在终端里执行claude就能进入交互式界面首次启动会让你登录 Anthropic 账号并完成认证。如果你更习惯图形化操作也可以在 VS Code 的扩展市场里搜索 Claude Code 安装插件在编辑器底部打开 Claude Code 面板和终端里用起来没有本质区别。官方还提供了桌面版客户端下载安装后同样可以操作。这里有一个很多新手会忽略的点Claude Code 默认走的是 Anthropic 官方 API需要账号里有对应的 API 额度或订阅权限。社区里也有不少朋友通过兼容层配置把模型接入到 DeepSeek、GLM 这类服务上适合对成本敏感的场景。不过我不建议在刚开始玩多代理时就切换模型先用默认配置跑通流程再说否则出了问题很难定位是模型的问题还是你配置的问题。2.2 理解核心概念CLAUDE.md、Subagents、权限模型在动手配置多代理之前有三个核心概念必须先弄清楚CLAUDE.md、Subagents 和权限模型。CLAUDE.md 是 Claude Code 的项目记忆文件放在项目根目录下。每次启动代理时它都会自动读取这个文件相当于给代理一份“项目说明书”。你可以在这个文件里写清楚项目的架构、代码规范、常用命令、目录结构、各模块职责甚至包括代理之间需要遵守的协作约定。我见过不少团队把 CLAUDE.md 写得像一份迷你版设计文档效果非常好代理犯低级错误的概率明显下降。Subagents 是 Claude Code 里专门用于委派任务的子代理机制。主代理在对话过程中可以根据需要把某个子任务转交给一个专职子代理来处理。每个子代理可以有自己的角色定义、系统提示词、可用工具集合。比如你可以定义一个“代码审查子代理”它的职责只负责审查代码质量工具只开放读文件和运行静态检查不给它修改文件的权限。这种角色分离让协作结构更清晰也让主代理的压力大大减轻。权限模型则是安全底线。Claude Code 对代理能执行的操作做了分级控制分成允许、拒绝、询问三种策略。你可以在启动时通过命令行参数指定比如--permission-mode acceptEdits表示自动接受对已有文件的编辑--permission-mode plan则让代理只规划不执行。对于需要人工把关的关键操作保留询问模式是最稳妥的做法。2.3 创建自定义 Agent 与能力边界设定理解完概念就可以开始创建自己的 Agent 了。Claude Code 支持在项目里的.claude/agents目录下定义自定义子代理每个代理用一个 Markdown 文件描述格式大致是这样的--- name: backend-developer description: 负责后端接口开发与单元测试编写适合处理 API、数据库相关任务 tools: Read, Write, Edit, Bash model: claude-sonnet-4-5 --- 你是一名资深后端工程师。在收到任务时先阅读项目中相关模块的代码理解现有架构 然后按 CLAUDE.md 中的规范实现功能。要求 1. 每个新增接口必须补充单元测试 2. 代码风格遵循项目既有约定 3. 完成后输出变更文件清单和测试结果这里的name是子代理的唯一标识description告诉主代理什么时候该把任务委派给这个子代理tools限制了它可用的工具范围model可以指定不同的模型版本。系统提示词部分则是你给这个代理定的人设和做事规范。我觉得创建代理时最值得花心思的是两点。第一点是职责要窄。一个代理只干一类事不要搞一个“全能代理”。你越想把所有能力塞进去它在具体任务上的表现就越平庸。后端代理就只管后端前端代理就只管前端文档代理就只管文档泾渭分明。第二点是工具权限要收得紧。不要给代理开无限制的 Bash 权限尤其当它要处理的是生产环境相关任务时。我自己的习惯是默认只给读写文件权限需要执行命令时单独开放并让关键操作走询问模式。这样即使代理跑偏了也不会造成不可挽回的破坏。3. 并行任务自动化的设计与实操3.1 任务拆解原则什么任务适合并行、什么不适合多代理并行的第一步不是启动代理而是拆任务。任务拆得好不好直接决定并行是加速还是灾难。适合并行的任务有三个特征。第一是依赖关系清晰。两个子任务之间要么没有依赖要么只通过一个明确的接口依赖。比如“前端调用后端接口”这种依赖只要双方先约定好接口格式前端就可以用 mock 数据先开发后端按约定实现两边完全可以同时推进。第二是没有共享写入冲突。两个代理不要同时修改同一个文件。如果必须改同一份代码那要么把文件拆开要么约定好先后顺序要么让其中一个代理只做代码审查而不做修改。我在实战中吃过这个亏两个代理同时改一个工具类一个加了新方法一个改了旧方法签名合并代码时冲突多到我怀疑人生。第三是验收标准可量化。每个子任务完成后能有一个明确的东西证明它做完了测试通过了、接口返回了预期结果、文档生成了。这个“明确的验收标准”是多代理并行的基石没有它你就无法判断代理到底干完没有。不适合并行的任务也不少。强顺序依赖的流程比如“先设计数据库表结构再写业务逻辑”这种后者依赖前者的任务强行并行只会导致返工。需要全局综合判断的任务也不适合比如“统一重构整个项目的错误处理机制”这种事单代理做反而更协调多代理各改各的只会改出一堆风格不一致的代码。3.2 实操方案一多终端多个 Claude 进程手动并行最轻量的多代理并行方案是手动开多个终端每个终端里启动一个 Claude 进程各自负责一个子任务。这种方式不需要写任何代码适合临时性的并行需求和小型项目。具体做法是先给每个子任务建独立的工作目录或者独立的 git 分支避免文件冲突。比如开发一个新功能我通常会拉三个分支feature/api、feature/frontend、feature/db。然后在三个终端里分别执行cd /path/to/project git checkout feature/api claude --permission-mode acceptEdits每个终端里的 Claude 会读取各自分支下的代码互不干扰。完成一个子任务后提交代码、合并分支再启动下一轮。这种方式的好处是灵活、直观随时能看到每个代理在干什么。坏处是没法同时对超过四五个代理做精细管理而且每个终端占用一个窗口操作多了之后容易乱。我一般会用一个简单的 bash 脚本把启动过程固化下来省得每次手动敲#!/bin/bash # 并行启动三个代理分别处理 api、frontend、db 三个子任务 tasks(api frontend db) for task in ${tasks[]}; do gnome-terminal -- bash -c cd /path/to/project git checkout feature/$task claude --permission-mode acceptEdits; exec bash done注意这里我用的是gnome-terminal你在 macOS 上可以换成osascript或者直接用 iTerm2 的 split pane 手动开窗口效果一样。3.3 实操方案二基于 Claude Agent SDK 编排多代理如果你需要的是更程序化、可重复执行的并行流程那就要用 Claude Agent SDK。官方提供了 TypeScript 和 Python 两种版本我日常用 Python 比较多因为做工程自动化脚本方便。先安装 SDKpip install anthropic-agent-sdk然后可以用类似下面的代码在同一进程里并发启动多个代理任务import asyncio from anthropic_agent_sdk import Agent async def run_backend_task(): agent Agent( namebackend-developer, modelclaude-sonnet-4-5, cwd/path/to/project, permission_modeacceptEdits, ) result await agent.query( 在 backend 模块新增用户注册接口 /api/v1/register参考 CLAUDE.md 中的接口规范并补充单元测试 ) return result async def run_frontend_task(): agent Agent( namefrontend-developer, modelclaude-sonnet-4-5, cwd/path/to/project, permission_modeacceptEdits, ) result await agent.query( 在 frontend 模块新增注册页面调用 /api/v1/register 接口先使用 mock 数据 ) return result async def main(): results await asyncio.gather(run_backend_task(), run_frontend_task()) for r in results: print(任务完成耗时:, r.duration_seconds) print(输出摘要:, r.result[:200]) if __name__ __main__: asyncio.run(main())这段代码的核心是asyncio.gather它会让两个代理同时开始执行整体耗时约等于最慢的那一个而不是两者之和。每个Agent实例都有独立的工作目录、独立的系统提示词、独立的会话上下文互不干扰。用 SDK 的好处是灵活你可以在代码里写各种逻辑任务失败自动重试、按依赖关系串行编排、收集所有子任务结果后统一汇总。坏处是初次上手要写点代码对完全没有编程基础的人来说门槛稍高。但如果你想做真正的“并行任务自动化”SDK 这条路早晚要趟一遍。3.4 并行过程中的上下文隔离与共享机制多代理并行还有一个绕不开的问题上下文怎么隔离、信息怎么共享。隔离的目的一是防止代理之间互相干扰二是控制每个代理的上下文长度避免它读太多无关内容导致性能下降。我通常的做法是在 CLAUDE.md 里写清楚每个模块的边界并在给代理的任务描述里明确指定它只需要关注哪些目录。比如后端代理的任务描述里直接写“只读取 backend/ 目录下的代码不要修改 frontend/ 目录”这样代理就不会越界。共享的关键则是契约先行。两个代理要做的事情如果有交集那这个交集必须提前固定下来。最典型的就是前后端接口约定。我在实战中会让后端代理先产出一份 OpenAPI 规范的接口文档提交到仓库然后前端代理严格按这个文档开发而不是靠猜。这个接口文档就是两个代理之间的“合同”谁也不能单方面改。另外一个实用技巧是给每个代理独立的日志文件。SDK 模式下可以在启动代理时配置日志输出路径这样每个子任务的执行过程都有据可查。手动模式下就让每个终端窗口的日志分别重定向到不同文件。出了问题不看猜测直接看日志就行。4. 多代理协作实战复盘一次前后端并行开发记录理论说了不少我拿一次真实做过的功能开发来复盘整个过程。这个功能是给一个内部管理系统增加“用户积分流水查询”页面涉及数据库、后端接口和前端页面三块内容非常典型。第一步是定义契约。我没有急着让代理开工而是自己先把积分流水表的结构、需要用到的几个接口路径、请求参数和返回字段列出来整理成一份 OpenAPI 文档放在docs/api/points-flow.yaml。这个步骤大概花了我四十分钟但它为后面所有并行工作奠定了基矗。第二步是拆分任务并分派给三个代理。数据库代理负责写迁移脚本新增points_flow表并造几条测试数据后端代理负责实现GET /api/v1/points-flow接口按 OpenAPI 文档实现附带单元测试前端代理负责写查询页面调用这个接口在接口没通之前用 fixture mock 数据渲染。三个任务之间除了那份 OpenAPI 文档之外没有任何交集完全可以并行。第三步是启动并行执行。我用的是 SDK 方式写了类似上一节里的脚本三个代理同时跑。整个执行过程大概持续了九分钟后端代理最快完成前端代理其次数据库代理因为要执行真实迁移慢了几分钟。三个代理都完成后我检查了各自的产出物迁移脚本能正确建表后端接口返回的数据结构符合契约前端页面的样式和交互都对得上。合并代码时出了问题。前端代理在我约定的字段里使用了一个createdAt但后端代理在实现时把时间字段命名成了createTime。两个代理都严格遵循了各自看到的契约但契约文档本身存在一处不一致。这种问题在人工开发时也会出现好在有代码审查环节兜底我让前端代理按后端实际返回值做了一次适配修复几分钟就解决了。第四步是联调验证。接口通了之后我让一个专门的测试代理只干一件事根据需求描述写端到端测试脚本直接调用真实接口、操作真实页面验证整个流程是否完整。测试代理还顺手发现了一个边界问题积分流水为空时接口返回的total字段是0但前端页面没有做空态处理会显示一个空表格而不是“暂无数据”的提示。这个问题交给前端代理修复效率很高。这次复盘给我的感受是多代理并行真正节省的不是编码时间而是“等待时间”。传统串行开发里前端要等后端接口好了才能联调数据库要等表结构定稿才能动手这些等待在并行模式下都被压缩掉了。但前提是契约阶段的工作必须做扎实契约不牢后面并行越快返工越多。5. 常见问题与排查技巧实录5.1 高频问题速查表多代理并行做了几轮之后我整理了一份高频问题速查表基本覆盖了大多数会踩的坑问题现象可能原因解决方案两个代理改了同一文件合并冲突任务拆分时没做文件隔离拆分任务时明确每个代理可写的目录和文件接口联调时字段对不上OpenAPI 契约文档本身不一致在契约阶段做好接口文档评审所有代理严格以此为唯一标准某个代理长时间无响应上下文窗口太长模型处理变慢检查代理是否有读入无关内容减少任务范围多个代理同时调用 API 被限流超出账号的并发请求限制降低并行数或错峰启动任务代理不按约定输出、自由发挥系统提示词约束不足在任务描述中明确输出格式和验收标准一个任务失败后其他任务白做任务之间存在隐性依赖并行执行前梳理依赖图有硬依赖的任务不要并行5.2 排查方法与避坑心得排查多代理问题我的经验是“先看日志再看契约最后看代码”。每个代理的执行过程都有日志日志里能看到它读了哪些文件、执行了哪些命令、输出是什么。很多问题从日志里一眼就能看出来比如代理把项目根目录当成工作目录导致找不到文件或者它执行了一个构建命令然后陷入死循环这些都是热词云里提到过的常见翻车现场。另一个心得是让小代理先出计划再干活。我在任务描述里通常会让代理在执行前先输出一个简短的实施计划比如“我打算先阅读什么文件再修改什么文件最后如何验证”。这个计划一出来我就能判断它的思路对不对。如果思路不对直接中止重来比让它埋头干完再返工省太多时间。还有一个避坑技巧是关于并行数量的。很多新手容易走入一个误区觉得并行代理开得越多越好。实际上并行数量受三个因素约束API 速率限制、项目文件竞争度、任务拆分质量。我自己测下来的经验是普通中型项目同时跑三到五个代理是比较舒适的区间超过这个数量代理之间互相踩脚的概率会指数级上升。并行不是目的稳定地完成自动化才是目的。最后不得不提的是安全风险。多代理并行意味着工具的调用面变大了攻击面也跟着变大。特别是当代理需要访问网络上不可信的内容时存在 prompt injection 的风险外部输入里可能夹带恶意指令诱导代理执行非预期操作甚至把这套指令再传给其他代理。这个方向在安全顶会 NDSS 2026 也有专门研究讲的就是针对 LLM Agent 工具选择的注入攻击。我的实操原则很简单不信任不可信来源的输入网络权限能收窄就收窄关键操作一律开人工确认。宁可牺牲一点自动化程度也不能把执行权完全交给一个可能被带偏的代理。我在实际使用中还有一个体会多代理协作真正难的从来不是技术配置而是任务边界的划分和管理。代理本身再聪明面对一个职责模糊、依赖混乱的任务也会变成无头苍蝇。与其花时间调更多的参数不如多在任务拆分和契约定义上下功夫。这两件事做好了Claude Code Agents 的威力才会真正发挥出来。最后再分享一个小技巧初期可以从两个代理并行开始练手比如“写代码的和写测试的各一个”跑通之后再逐步加码。这个节奏能让你的任务拆解能力跟着一起成长——它才是你在这条路上收获的最值钱的东西。
