1. 从单线程对话到多人并行协作用Claude Code写过一阵子项目的人大概率都会碰到同一个瓶颈一个对话窗口干到底前面聊需求、后面写方案、再往后修bug、顺手还要做代码审查所有事情挤在同一条上下文里。结果就是改到一半发现初始设定被冲淡了或者一个简单的重构审查模型把前面几十轮的历史都翻出来看了一遍又慢又浪费。我自己就踩过这个坑一个中型的全栈项目做到第五天的时候明显感觉到对话太沉重了——每条指令都在背着整个项目历史负重前行。Claude Code的Agent Teams代理团队就是为了解决这个问题出现的。它的本质很简单不再让一个Agent从头到尾包办一切而是为一个项目同时拉起多个独立的Agent每个Agent扮演一个专家角色各自有独立任务、独立上下文、独立工作目录在同一个代码库里并行干活。你只需要一个总控入口把它们组织起来。说人话就是以前是一个人左手改后端右手改前端顾此失彼现在是后端工程师、前端工程师、代码审查员各就各位各干各的活你只当那个项目经理。这个玩法特别适合几类场景一是复杂度已经上来的存量项目比如既有业务代码要改、又要拆模块、又要保证测试不挂二是需要强隔离的并发任务比如两块功能互相不依赖硬塞进同一个上下文里反而是负担三是代码审查重度用户——你完全可以安排一个专职审查Agent盯着主开发Agent产出的diff。也有一部分人拿它当团队协作的模拟器用让多个Agent扮演不同角色互相辩论方案用来做技术选型推演。这篇文章我打算从原理讲到实战包括Agent Teams的工作机制、怎么配置、怎么声明子代理、常见的协作模式以及我实际跑项目时遇到的那些坑和排查思路。环境部分我放在前面说因为后面所有操作都依赖这个基础。如果你已经装好Claude Code并用过一段时间可以直接跳到第3章看协作模式。2. 环境与配置基础先把团队会议室搭起来2.1 安装与登录没有进入门槛但有隐藏约束Claude Code目前官方支持macOS、Linux和Windows三大平台安装方式非常统一——一行命令。我之前在Ubuntu 22.04和Windows 11上各跑过一套流程基本一致。macOS和Linux用curl脚本安装Windows上装好Node.js之后建议用npm全局安装这样后续升级也方便。# macOS / Linux curl -fsSL https://claude.ai/install.sh | bash # Windows先确保有Node.js 18 npm install -g anthropic-ai/claude-code装完之后在项目根目录跑claude就会进入交互式终端。第一次启动会让你登录账号这一步在国内网络环境下偶尔会出现登录页加载比较慢的情况换个网络环境基本就正常了。登录成功之后Claude Code会把凭证存到本机下次启动直接可用。这里有个很多人忽略的点——Agent Teams能力依赖你的账号订阅类型和模型权限。有些企业组织账号虽然能用Claude Code但管理员默认关闭了Claude Subscription的API通道你会在启动时看到 your organization has disabled claude subscription access for claude code 之类的提示这种情况下Agent Teams基本用不了因为子代理调度本身消耗的就是订阅额度里的扩展调用。个人订阅账号一般没这个问题但如果你在公司环境用最好先跟管理员确认一下权限。2.2 与编辑器集成VSCode和桌面的差异热词里有人在搜Claude Code桌面版和Claude Code for VS Code这俩其实是同一个东西的两个形态。Claude Code桌面版本质上是把终端版包了一层GUI壳适合不习惯纯命令行的人VSCode集成则是以插件形式嵌入编辑器边写代码边调Claude Code会比较顺手。我个人的建议是主用终端版编辑器插件用来辅助。原因在于Agent Teams的粒度控制主要还是靠CLI参数和配置文件终端里操作起来最直接。VSCode插件适合做代码编辑的即时交互比如选中代码块让它改一改、解释一下但拉起多个Agent并行干活这种重操作还是终端里看得清楚。插件安装方式很简单VSCode扩展商店搜Claude Code安装装完在侧边栏就能看到对话面板、会话历史、Agent运行状态。配置上有个细节Claude Code在VSCode里和终端版共用同一套配置文件也就是项目根目录的.claude/文件夹。这意味着你在终端里建好的Agent团队配置、角色设定VSCode插件里一样能读到不需要重复配置。2.3 本地模型接入lmstudio的适配思路热词里claude code 调用lmstudio的本地模型这条我在实际项目里也试过——Claude Code本身依赖Claude API但它的很多调度逻辑可以借ANTHROPIC_BASE_URL这个环境变量指向兼容接口。换句话说如果你有本地跑的模型服务比如lmstudio起的OpenAI兼容端点理论上可以把它当成后端模型来用。# 在 .bashrc 或 项目 .env 中设置 export ANTHROPIC_BASE_URLhttp://localhost:1234/v1但这里我必须说实话Agent Teams对模型能力的要求远高于普通对话。本地小模型做简单代码补全没问题但让多个Agent并行协作、维护各自上下文、按角色执行复杂任务本地模型的能力经常扛不住。我用lmstudio试过一轮子代理之间的指令理解偶尔会跑偏尤其是指令里带多条件约束的时候。如果你只是想在本地简单体验一下Agent模式可以跑但想正经用于生产项目建议还是用Claude官方接口——这不是劝你花钱是效率上确实差着一大截。2.4 项目的团队配置理解.claude目录Claude Code的配置采用项目级目录第一时间读取的方式。项目根目录下的.claude/文件夹里至少会关心两个文件一个是全局的CLAUDE.md项目说明书Claude Code每次启动都会自动加载另一个是你可以手动创建的settings.json控制权限、钩子、自定义命令。Agent Teams的配置分散在这两个文件里CLAUDE.md里写团队角色的定义和协作规矩settings.json里可以声明可用子代理及权限策略。我在本地的一个示例项目里建过这样一个目录结构project-root/ ├── .claude/ │ ├── CLAUDE.md # 项目说明书 团队规则 │ ├── settings.json # 权限与子代理声明 │ └── agents/ │ ├── frontend.md # 前端专家角色定义 │ ├── backend.md # 后端专家角色定义 │ └── reviewer.md # 代码审查专家角色定义 └── src/这样做的优势在于团队配置跟代码库走换机器、换人协作只要clone项目下来整个团队的配置也跟着下来。不需要每个人在自己终端里重新写一遍角色定义。3. Agent Teams核心机制为什么多个专家比一个全才更靠谱3.1 会话与子代理你看到的其实是总控执行单元Claude Code的Agent Teams在形态上是一个总控会话派生多个子代理会话。总控会话由你直接交互它负责理解你的意图、拆解任务、把任务分派给对应的子代理每个子代理被创建时会有一个独立的上下文窗口、独立的工作目录和独立的任务描述。子代理干完活在总控会话里汇报结果。这个东西其实类似你在终端里同时开了多个Claude Code实例但由一个主入口统一管理不需要你自己切来切去。创建子代理通常用/agent命令也可以在工作流里通过触发规则让Claude Code自动拉起子代理。每个Agent启动时会自带一份persona文件比如frontend.md里面写清楚它的职责边界、擅长什么、不碰什么、输出格式要求。跟大家想的不一样的是子代理并不是低配版Claude它们用的是同一套底层模型能力区别只在于视角和角色约束。你可以把总控会话理解成一个拥有全局视野的项目经理它知道整个项目在做什么子代理则是被植入了你只管前端、后端的事不要碰这种心智的专项工程师任务完成度反而更高因为它的上下文里不会被无关信息污染。3.2 上下文隔离与共享信息不会串台Agent Teams最值钱的设计是上下文的隔离和定向共享。总控会话掌握全局背景比如项目目标、技术栈、整体架构决策子代理只拿自己需要的片段比如前端Agent只知道UI相关的组件树和接口协议不会看到数据库迁移脚本的历史记录。这样带来两个直接收益上下文窗口利用效率更高同样的任务量消耗的token更少信息不串台后端Agent的决策不会被前端的对话历史干扰。在任务过程中子代理之间不能直接通信它们只能通过总控会话间接传递信息。这有点像实际公司里部门之间的协作——前端要对接后端得通过项目经理协调而不是两个工程师私下拉群。这个设计在提高可控性的同时也让总控会话的prompt设计变得格外重要——你写清楚分派规则协作才有秩序。3.3 权限与执行边界每个子代理默认继承总控会话的权限配置但你可以针对每个Agent单独调整。比如前端Agent只允许读取代码文件和运行单元测试无权执行部署命令审查Agent只能读不能写后端Agent可以执行数据库迁移类命令。这种按角色控制权限的模型跟真实团队里的分权一个逻辑——谁也不能左手写代码右手就上线。在settings.json里可以针对Agent声明权限规则用一个简单的示例说明{ permissions: { allow: [ Read, Glob, Bash(npm run test:unit) ], deny: [ Bash(rm -rf *), Bash(git push) ] }, agents: { frontend: { permissions: { deny: [Bash(npx tsc)] } } } }实际落地时你会发现权限模型的控制粒度直接决定了这个团队好不好用。权限太宽子代理可能做出你想不到的破坏性操作权限太窄它干点啥都来问你又失去并行的意义。我的经验是先给偏紧的权限跑几轮之后看哪些操作频繁被拒再针对性放开比一开始就给全权限安全得多。4. 三种主流协作模式从简单到复杂的实操路径4.1 模式一并行分工——互不依赖的任务最好用这是最直观也是最容易上手的一种模式。项目里有两块功能互不依赖比如一个负责重构旧的登录模块另一个负责新增用户设置页。正常一个人干得线性地做完一件再做另一件并行分工模式下你拉起两个子代理同时开工总控会话统一汇报进度。实操步骤在总控会话里用/init初始化项目上下文确保Claude Code知道项目结构用/agent拉起第一个子代理指派重构登录模块任务再拉起第二个子代理指派新增用户设置页任务两个子代理并行工作完成后各自汇报你在总控会话里查看diff合并提交。这里有一个非常重要的细节给子代理派活时任务描述要包含明确的完成标准。单说重构登录模块是不够的子代理可能不知道什么叫重构完。至少要包含改动范围哪些文件、约束不能改变对外接口、验收测试通过。比如你负责重构src/auth/目录下的登录模块。目标是把重复的验证逻辑抽到src/auth/validators.ts保持对外接口不变。完成后运行npm run test:unit -- auth确保测试通过。只修改src/auth/内的文件。任务描述写清楚了子代理的产出质量才有保障这也是并行协作里最值得花时间打磨的地方。很多人用不好Agent Teams问题不在工具本身而在派活太随意。4.2 模式二研究先行实施跟进第二种模式是我个人用得最多的让一个Agent专门做研究产出落地方案再由另一个Agent根据方案写代码。这解决的痛点是很多情况下方案还没想清楚就冲进代码改改到一半发现方向错了整个上下文被浪费了。具体流程拉起研究型Agent让它分析项目现状。任务描述示例分析src/下的所有API调用找出和auth相关的所有模块评估改成token刷新机制的影响范围输出一份分析报告。不要修改任何代码。研究Agent直接跑脚本、读文件、画依赖关系对它可以调用终端工具产出一份报告放在docs/下总控会话拿到报告后再拉起实施Agent把报告里提出的方案转化为实际代码改动。这套模式的关键优势在于研究报告与代码改动之间的信息传递是通过文档完成的而不是靠上下文硬塞。研究者看全貌实施者做落地天然匹配人的思维习惯。而且研究Agent的独立上下文保证了它分析时不被原本想做的改动带偏——很多bug就是来自先入为主的修改意图。4.3 模式三开发审查的流水线这个模式适合对代码质量有要求的项目特别是团队多人协作前想先把关一遍的场景。思路是开发Agent负责写代码审查Agent负责挑刺两者通过总控会话传递diff。实际操作时我会先让开发Agent完成一个功能的编码然后总控会话把产出文件列表交给审查Agent。审查Agent的persona里我会写清楚它的关注点类型安全、边界条件、潜在性能问题、与既有代码风格是否一致。审查完之后输出一份review清单标注每个问题的严重等级和修改建议再由开发Agent按清单逐项修正。循环可以跑两三轮直到审查Agent给出的问题列表为空或者只剩最低级别建议。这个过程最开始会比较慢因为审查Agent会鸡蛋里挑骨头但跑几个任务之后你会摸清它的胃口把常见误报的检查项在persona里禁掉效率就起来了。实际上这也是Coding Agent协作流水线的经典形态——写代码的人不审查自己的代码强制引入第二视角效果比我试过的任何lint工具都来得实质。4.4 团队角色的人设编写一份可复用的样板不管哪种协作模式角色的persona文件都直接决定产出质量。我贴一份自己用的前端专家persona模板大家可以在项目里直接改你是一名资深前端工程师负责项目中所有与用户界面相关的开发工作。 你的职责范围 - 修改 src/ui/ 目录下的Vue/React组件 - 调整样式与交互逻辑 - 确保浏览器兼容性 你不需要处理 - 数据库相关的任何操作 - 后端API的实现逻辑但可以查看接口文档 你的工作准则 1. 所有样式改动必须走CSS变量体系不能硬编码颜色值 2. 组件必须保持TypeScript类型完整不允许出现 any 3. 代码提交前必须运行 npm run lint 并保证无错误 完成标准 - 实现功能需求中的全部交互 - 视觉表现与设计稿一致 - lint与类型检查通过这个persona本质上是在告诉这个Agent三件事它是什么身份、它的边界在哪、它的验收标准是什么。角色定义越具体产出偏差越小。写角色时宁可多花十分钟把边界说清楚也不要写一个万金油人设然后寄希望于大模型的自觉。5. 实操实录一个全栈项目的三分法协作5.1 项目背景与任务拆解这个项目当时是一个内部工具技术栈是Node.js React PostgreSQL。我接到的需求是把现有的数据看板重构一版同时加上权限管理功能而且时间上比较紧。如果按老方法我会在同一个对话里先改API再写前端再调权限中间件——交互多、上下文重而且中途一旦改了一版方案前面所有历史都变成干扰。现在我把任务拆成了三个AgentBackend Agent负责重构REST API加上基于角色的访问控制中间件Frontend Agent负责重写数据看板页面对接新的API协议Reviewer Agent负责审查前两个Agent的产出重点是安全边界和类型完整性。总控会话只负责两件事传达整体需求边界、汇总各Agent的产出和审查意见。三个Agent之间不直接交互信息全部通过总控会话周转。5.2 子代理的独立工作方式与产出实测下来Backend Agent和Frontend Agent可以完全并行工作。我在总控会话里分别给它们派活然后观察各自的输出日志。Backend Agent最先完成了API重构Between写完新的路由文件后还顺手跑了npm run test:apiFrontend Agent改完组件树后用tsc --noEmit做了类型检查。两个Agent在完成各自部分时上下文里都没有对方的干扰信息这一点很关键——改后端的时候不会被前端组件名是什么这种问题打扰。Reviewer Agent是在两者完成后才被拉起来的。我把变更文件列表传给它它逐文件审重点看了Auth中间件的实现——防止越权的逻辑、token校验的异常处理。最后给了一份报告指出3个中等级别的问题和2个建议项。我转给Backend Agent逐条修完Reviewer复看确认无遗漏整个流程结束。5.3 观察记录token消耗与时间收益把这次实测的Token消耗细节写一下方便大家估算成本。三个Agent加总控整体消耗约44万token。其中两个开发Agent占八成Reviewer Agent占不到两成。时间上整个协作流程约15分钟而传统单会话改同样规模的代码我估算至少要多花一倍时间且上下文污染风险高。有意思的是Token总量并没有因为并行而暴涨。原因也简单——每个Agent各自的上下文都比全知全能模式小得多单Agent上下文规模小了反而省token。这也是工作组模式被人低估的价值它不是简单地把活拆开而是通过缩小单次上下文来提升整体效率。5.4 过程中的沟通节奏与总控介入时机实操中总控会话的介入时机也很讲究。如果介入太频繁等于又把并行活拉回线性如果完全放手可能等子代理跑完了你才发现方向错了。我个人的节奏是派活前花5分钟把任务边界、完成标准、涉及目录说清楚派活后等子代理第一轮输出先确认方向对不对再让它继续跑中途只在子代理主动询问或任务依赖另一方产出时才介入结束前统一看Reviewer的清单一次性转给开发Agent修正。这个节奏有点像现实里带人的感觉。方向定了之后尽量少在过程里反复横跳才能让并行真正发生。6. 常见问题与排查技巧实录6.1 子代理不按预期执行问题定位的通用思路子代理跑偏是Agent Teams使用中最常见的问题没有之一。起因大多是任务描述过于笼统给Agent留了太多自由发挥空间。比如优化一下性能它可能去改了一堆无关的配置文件或者重构支付模块却不告诉它不能改数据库结构结果它把schema动了。排查思路分三步第一步看任务描述是否包含了边界、完成标准、验收方式第二步查persona文件看角色定义有没有跟任务冲突的地方典型冲突是前端Agent的persona里写了可以修改任何代码但实际任务只给了UI目录第三步看子代理的执行日志定位是理解偏差还是执行错误。理解偏差就改描述重跑执行错误就修权限或改约束。6.2 上下文过载的征兆与应对策略上下文过载发生的场景比你想的多。比如一个Agent连续处理了几十个文件或者任务里塞了过长的README它的工作记忆会逐渐失真——具体表现是前面几轮严格执行的角色约束后面开始淡化输出的代码风格逐渐偏离persona设定甚至开始重复已经修过的问题。遇到这种征兆最直接的应对是把这个Agent杀掉重建一个新的实例新实例会重新加载persona文件拿到最新的报告后继续干活。不要在一个老会话里硬撑撑到后面只会产出越来越多的垃圾结果。另一个习惯是定期让Agent把阶段性成果落盘成文档然后在新Agent启动时把文档路径放进上下文用读文件代替记住推理过程。6.3 权限拒绝频繁合理调整而非一刀切放开子代理干活时偶尔会弹出权限确认跑多了会烦。很多人选择直接把权限调成全部allow这个操作我强烈不建议。更合理的做法是观察被拒的操作列表把那些确实安全且高频的命令加入允许名单比如前端Agent高频使用npm run lint后端Agent高频使用npx prisma migrate逐个加白。留几个高危操作始终拦截比如git push、rm -rf这样既顺畅又不失边界。6.4 多Agent串扰与协作矛盾Agent Teams的子代理默认上下文独立不会直接“看见”彼此的会话内容但跨Agent串扰仍然可能存在根源在共享文件系统——一个Agent改了src/api/types.ts另一个Agent正在读同一份文件。这种现象我遇到过解法是在分派任务前明确文件所有权每个Agent的任务描述里写清你只能写以下文件和目录总控会话负责在派活时检查重叠区。如果两个Agent不可避免地要碰同一份文件那就只能串行安排或者明确一个主、一个只读。6.5 一份常用问题速查表现象可能原因处理方式子代理行为越来越偏离要求上下文过长导致角色淡化杀掉重建Agent落地中间结果后重开任务做一半停住等确认权限配置过窄查看被拒操作将安全命令加入白名单两个Agent改了同一文件导致冲突文件所有权未声明重跑前明确各Agent的写权限目录Authority报错无法创建Agent账号权限被限制检查订阅状态与组织策略本地模型下指令理解偏差大模型能力不足换官方接口或降低任务复杂度总控会话繁忙、响应变慢多个Agent同时汇报分批派活错开子代理启动时间7. 我个人的一些经验心得这套Agent Teams方案我现在已经用成了默认工作方式尤其是研究先行实施跟进和开发审查组合。跟最早用Claude Code单会话连轴转相比最大的变化不是跑得快了多少而是脑力负担真的降下来了——我不需要在一次对话里同时记住一堆决策和修改点把它们分给专职Agent之后我自己只需要把握方向和审查最终产出。最后分享一个小技巧给每个子代理起一个容易识别的名字并且在总控会话里用固定句式派活。比如总是用你负责X目标是Y边界是Z完成后汇报W这种格式时间长了你会形成一套自己的派活模板翻开历史记录一眼就能看懂当时每个Agent被安排去做什么。对于写代码的人来说Agent Teams本质上不是多个AI的堆砌而是一套如何把工程任务拆成能并行的单元的方法论。工具会迭代这个拆解的思路短期不会过时。