最近在研究多代理协作开发时被同一个问题反复绊倒单靠一个 Claude Code 实例处理跨模块需求经常出现改完 A 文件忘了 B 文件依赖的情况。后来我把项目拆给多个代理并行处理效率提升非常明显。这篇内容就把我配置 Agent Team 的完整过程、踩过的坑和最终沉淀下来的方案整理出来希望能帮到正在折腾 Claude Code 多代理模式的朋友。Agent Team 是 Claude Code 里用于组织多个子代理协同工作的配置机制。它不改变底层模型能力而是通过一套任务拆解、角色定义和工作流编排让多个代理各司其职。这套机制比较适合中型以上的代码库、跨文件重构、全栈功能开发这类任务。如果你是刚开始接触 Claude Code建议先跑通单代理的基础用法再进入 Team 模式否则排查问题时会混淆到底是模型能力问题还是编排问题。1. Agent Team 到底解决了什么问题很多人在刚接触 Agent Team 时第一反应是这不就是把多个 AI 窗口拼在一起吗。实际用下来差距很大。单窗口的 AI 助手是线性逻辑你给它一个任务它从头做到尾过程中的每个决策都由同一个上下文推导。这种模式在任务范围明确、涉及文件少时没问题但一旦任务跨度变大比如给整个项目增加权限系统 重构所有接口错误处理单代理就会暴露出明显的短板。1.1 单个 Agent 的上下文瓶颈Claude Code 的单代理在同一时刻只能维护一份上下文状态。当对话轮次变多、文件改动范围变大时早期对话里确定的设计决策会被慢慢遗忘或者被后续的信息覆盖。我实测过一个 30 分钟以上的长会话代理开始出现前后矛盾的操作比如先确定了接口返回结构{code, data, message}处理到后半程又按老结构{status, result}去写前端调用。这种问题不是模型笨是上下文窗口有限导致的必然衰减。1.2 并行与专精的差距Agent Team 的核心价值在于两点并行和专精。所谓并行是指多个子代理可以同时处理互不依赖的任务。比如一个代理负责数据库模型设计另一个代理同时写 API 路由还有一个代理做前端页面骨架。三个任务并行推进总耗时不再是单代理那种线性累加。所谓专精则体现在角色定位上。你可以给子代理注入专属的系统提示词和工具白名单比如后端代理只能读写server/目录下的文件、不允许修改前端代码这种硬性边界在单代理模式下几乎做不到——你叮嘱它别碰前端代码它十有八九还是会碰。1.3 什么样的任务适合上 Team按照我现在的经验以下场景适合配置 Agent Team跨模块全栈功能开发比如从数据库到 API 再到前端页面的完整链路大规模重构需要同时修改数十个文件且保持风格统一批量任务比如一套数据迁移脚本需要在多个环境跑需要多角色审查的流程比如编码完成后立刻有独立代理做 code review反之如果只是改个文案、调一个接口参数、修个简单 bug用单代理就好。为这些轻量任务配置 Agent Team配置成本反而比节省的时间更高。2. 从零装好 Claude Code 并完成基础验证在聊配置之前先把安装这步理清楚。Claude Code 目前提供命令行工具和 VS Code 插件两种形态两者可以同时使用共享同一份配置。2.1 CLI 安装方式命令行工具基于 Node.js 发行安装前先确认本机 Node 版本。我建议 Node 18 以上实测 Node 16 也能跑但部分新功能会有兼容告警。# 检查 node 版本 node -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证安装 claude --version安装完成后直接输入claude会进入交互式会话。首次运行需要登录授权按提示跳转到浏览器完成认证认证通过后会自动生成本地凭据后续使用时不需要重复登录。如果你用的是 macOS 或 Linux还可能需要给claude命令配置 PATH 环境变量。npm 全局安装的目录通常在/usr/local/bin或$(npm prefix -g)/bin遇到command not found时优先检查这个路径。2.2 VS Code 插件集成VS Code 插件的方式更适合日常编码场景。在扩展市场搜索 Claude Code 或 Claude Code for VS Code安装后会在侧边栏生成一个聊天面板。插件的好处是能直接读取当前打开的工作区文件配合编辑器的上下文做修改时代理对项目结构的理解比纯 CLI 模式更准确。需要注意VS Code 插件和 CLI 共用同一份配置文件。如果你已经用 CLI 配置过 Agent Team插件侧可以直接继承配置不需要重复设置。2.3 版本升级Claude Code 的迭代频率很高新功能基本都是随版本更新发布。升级方式很简单npm update -g anthropic-ai/claude-code我在实践中遇到过一个典型问题配置了 Agent Team 后发现部分子代理行为异常查了半天发现是本地的 Claude Code 版本太旧某些加载配置时用到的解析能力在旧版本没有。所以遇到诡异问题第一件事先升级版本看看能不能解决。2.4 关于地区可用性的说明在安装或运行过程中如果看到类似 Claude Code might not be available in your country 的提示说明你当前所在的网络环境不在官方支持范围内。遇到这种情况请直接查看 Anthropic 官方文档中列出的支持国家/地区列表以官方说明为准。务必通过正规渠道核实与操作不要使用任何非官方手段绕过限制这既影响账户安全也存在使用风险。3. Agent Team 的运行机制拆解配置 Agent Team 之前先搞清楚它内部是怎么工作的。理解了运行机制后面配置时就知道每个字段的意义了。3.1 主代理与子代理的关系在 Claude Code 的 Team 模式中存在一个主代理Lead Agent和若干子代理Subagents。主代理是入口它接收你的初始任务决定如何拆解、是否委派、以及如何汇总结果。子代理是执行单元。每个子代理有独立的上下文窗口和独立的系统提示词它们之间的对话历史不共享。这意味着子代理 A 改了什么文件子代理 B 并不会自动知道只能通过主代理转述任务要求、或通过读取共享文件来获取信息。这个设计有一个重要含义不要让两个子代理同时修改同一个文件。如果 A 和 B 都在编辑config.ts后写入的一方会覆盖前者的成果而且还不会报错——因为两个代理之间没有消息互通。3.2 任务委派流程一个典型的 Agent Team 任务流程大致如下主代理收到用户请求给用户模块增加导出 Excel 功能主代理判断需要改动server/下的导出接口和web/下的导出按钮主代理把接口任务委派给后端子代理把按钮和前端逻辑委派给前端子代理两个子代理并行开始处理各自维护独立会话子代理完成回传结果后主代理汇总、验证、给出最终交付说明实际运行中主代理不一定等待所有子代理全部完成才收尾它可能先拿到 A 的结果就基于这个结果决定下一步是继续指派还是直接结束。这种动态调度能力是 Team 模式和单纯并行发多个请求的本质区别。3.3 核心配置字段解读Claude Code 的 Agent Team 配置由 JSON 文件承载通常存放在项目根目录下的.claude/目录中。配置文件里字段不多但每个字段都直接决定子代理的行为边界。我用一个简化示例说明核心字段{ name: api-backend-agent, description: 负责后端 API 接口开发与数据库模型设计, tools: [Read, Edit, Bash, Glob], prompt: 你是一个资深后端工程师只负责 server/ 目录下的开发工作。不得修改 web/ 目录下的任何文件。, model: opus }name子代理标识主代理委派任务时用它来指定目标代理description描述这个代理擅长什么。主代理会读这段文字来决定是否把任务委派给它tools允许代理使用的工具白名单不给的它就用不了prompt系统提示词定义代理的角色、职责边界和风格model可选字段指定该子代理使用哪个模型。不同模型成本、能力差异较大可以根据任务重要程度分开配置在实际配置中description和prompt往往决定 Team 协作质量的一半。描述写得越精准主代理的调度判断就越准确提示词约束得越明确子代理越不容易越界。4. 搭建第一支 Agent Team 的完整过程理论讲完下面进入实操。我会用一个前后端分离项目作为示例完整演示三角色 Agent Team 的配置过程。4.1 项目背景与角色划分假设现在有一个项目server/是 Node.js 后端web/是 React 前端根目录还有一份部署脚本。目标是把配置过程做成三个子代理backend-agent负责后端 API、数据库相关开发frontend-agent负责前端组件、页面开发review-agent负责代码审查不直接写代码只读不改为什么不把部署脚本也单独建一个代理因为脚本规模通常较小主代理顺手就能处理。代理数量并非越多越好协作中的沟通开销是实打实的成本这一点后面再展开。4.2 编写三个子代理的配置先在项目根目录创建.claude/agents/目录存放子代理配置文件。mkdir -p .claude/agents cd .claude/agents第一个文件backend.json{ name: backend-agent, description: 负责 server/ 目录下的所有开发任务包括 API 接口、数据库模型、中间件熟悉 Express 和 PostgreSQL, tools: [Read, Edit, Bash, Glob, Grep], prompt: 你是一名资深 Node.js 后端工程师。严格遵守以下规则1. 只能修改 server/ 目录下的文件2. 接口返回格式统一为 { code, data, message }3. 修改数据库模型前必须检查现有迁移文件4. 完成后输出变更文件列表、新增接口说明、需要前端配合的字段变更。 }这个配置里有两个关键设计。第一tools中给了Bash因为后端开发经常要跑测试、执行迁移命令第二prompt里强制规定了输出格式这能让主代理在汇总结果时直接拿到结构化的信息减少无谓的追问成本。第二个文件frontend.json{ name: frontend-agent, description: 负责 web/ 目录下的前端开发包括 React 组件、页面、状态管理、样式熟悉 Ant Design 和 Tailwind, tools: [Read, Edit, Glob, Grep], prompt: 你是一名资深前端工程师。只负责 web/ 目录下的内容。调用后端接口时统一走 src/api/ 目录禁止在其他位置直接写 fetch。组件样式优先使用 Tailwind 类不新建 CSS 文件。完成后输出变更组件列表、接口调用点、对后端接口格式的任何假设。 }注意frontend-agent的tools里我没有给Bash。这是刻意为之——前端子代理不需要执行终端命令不给Bash能避免它自作主张跑构建命令占用资源也减少误操作风险。第三个文件review.json{ name: review-agent, description: 负责代码审查只读不改重点检查逻辑正确性、安全隐患、风格一致性, tools: [Read, Glob, Grep], prompt: 你是一名严格的代码审查员。只能读取文件绝对不能修改任何文件。审查时关注1. 是否有明显逻辑错误2. 是否在文件中硬编码密钥3. 是否违反项目统一规范4. 变更是否超出任务范围。输出格式问题列表按严重程度排序、每个问题的文件位置和修改建议。没有问题时明确说明。 }审查代理不给编辑工具是安全边界设计的一部分。让审查代理只读可以有效避免它顺手修复引入新问题——审查和修改应该是两个分离的动作。4.3 配置主代理的调度规则子代理就绪后还需要在主配置中声明这些代理。.claude/settings.json是 Claude Code 的主配置文件里面可以设置代理列表和默认行为{ agents: { backend-agent: { description: 后端开发子代理使用场景API 开发、数据库变更, model: opus }, frontend-agent: { description: 前端开发子代理使用场景页面开发、组件调整, model: opus }, review-agent: { description: 代码审查子代理使用场景功能完成后检查质量, model: sonnet } } }主配置里的description与子代理文件里的description可以相互补充。主配置里的描述更侧重什么时候该用——它帮助主代理理解调度策略子代理文件里的描述更侧重我是谁——它塑造子代理的执行角色。model字段我给了不同的值两个开发代理用能力更强的模型审查代理用成本更低的模型。审查任务是只读分析对模型的推理深度要求没那么极端成本控制在这个环节最值得做。4.4 验证配置与首次调用配置完成后在项目根目录启动 Claude Codeclaude进入交互界面后输入/agents应该能看到刚配置的三个子代理。之后可以直接下达任务比如给用户模块增加导出Excel功能后端代理负责接口前端代理负责按钮和下载逻辑完成后由审查代理检查变更主代理会按配置中的职责描述自动拆解并分别调用对应子代理。从指令下达方式可以看出你不需要手动逐个唤起子代理只需描述目标主代理负责编排。4.5 各文件在项目中的位置把涉及的路径和职责汇总成一张表方便对照检查文件路径作用.claude/agents/backend.json定义后端子代理角色、工具边界与系统提示词.claude/agents/frontend.json定义前端子代理角色、工具边界与系统提示词.claude/agents/review.json定义审查子代理角色、只读工具边界与审查规则.claude/settings.json声明代理列表、调度描述与模型选择所有配置文件都应该提交到版本库。这样团队其他成员克隆项目后无需额外设置即可复用同一套 Agent Team 配置。5. 对接第三方 API 模型的配置经验不少团队在实际使用中会希望让 Claude Code 的 Agent Team 跑在其他模型上比如 DeepSeek、Qwen、GLM 这类开放接口的模型。这个需求本身是合理的出于成本、数据合规或已有供应商协议等考虑。但在实际操作前有几个基础概念必须先说清楚。5.1 修改模型接入点的方式Claude Code 默认连接 Anthropic 的官方 API 接口。要切换到其他兼容端点通常用环境变量指定 Base URL 和 API Keyexport ANTHROPIC_BASE_URLhttps://your-endpoint.example.com export ANTHROPIC_AUTH_TOKENyour-token claude设置完成后再启动 Claude Code请求就会打到新端点上。这种做法的前提是目标服务提供的 API 与 Anthropic 的接口格式保持兼容。兼容层做得好的服务跑起来基本无感兼容层只覆盖了部分功能的就需要实测确认哪些能力可用、哪些不可用。5.2 使用网关工具管理多模型手动改环境变量略显繁琐如果想在多个模型之间来回切换网关类工具会更顺手。这类工具通常提供一个本地中转服务统一管理各家 API 的 Key 和路由规则。目前社区里比较常见的选择包括各类开源 API 网关用它们也能实现类似 CC Switch 那种图形化切换的效果。我用网关工具的感受是切换速度比改环境变量快很多尤其是在对比不同模型在相同 Agent Team 配置下的表现时来回切几次就能得出结论。但成本也需要注意——网关本身多一跳网络转发在请求量大时延迟会有小幅上升。5.3 第三方模型下的 Agent Team 表现差异把同一个 Team 配置切换到不同模型上运行后我观察到的差异主要有三类。第一类是工具调用稳定性差异。Agent Team 的运行高度依赖主代理正确调用Task工具来完成子代理委派。部分模型在单轮对话里表现不错但进入多轮工具调用循环后偶尔出现忘了正在做任务的断片现象。这类问题只能通过更换模型或缩小任务粒度来缓解。第二类是提示词遵循度差异。prompt中定义的输出格式、禁止修改的目录等硬性约束在不同模型身上的遵守程度不一样。表现好的模型能全程守住边界表现弱一点的中间会走出约束范围需要主代理拉回来。这会导致同一套配置换模型后效果打折的现象。第三类是上下文管理效率差异。子代理回传的任务结果如果信息密度高、结构清晰主代理汇总时就很省事反过来如果子代理输出啰嗦、重点埋藏深主代理的上下文就会被无效信息填满出现类似长会话后忘记早期决策的问题。5.4 我的选择建议如果你所在的环境用不了官方模型或者你想降低成本我的建议是先保持官方架构不变只替换底层模型接口不要一上来就大改配置。换句话说优先用环境变量或网关方式做兼容接入先跑通一个子代理再做整个 Team 的验证。如果你对比了多个模型发现 Agent Team 的模式在某个第三方模型上频繁出错不要急着骂工具先回到单代理模式测一下同一个任务是否流畅运行。单代理都有问题的模型团队模式下只会放大问题。6. 我踩过的坑和沉淀下来的经验配置 Agent Team 不是一蹴而就的事我前后折腾了两周才找到顺手的工作流。过程中踩了不少坑挑几个最关键的分享出来。6.1 子代理职责边界不清晰的教训最开始配置子代理时我把description写得比较宽泛比如负责用户模块相关开发。实际运行时出现了一个问题主代理把涉及用户模块的所有任务都委派给同一个代理包括前端、后端甚至部署脚本的修改。结果这个代理虽然名为主力开发实际却干成了全能角色而且因为职责过宽它的上下文消耗速度极快任务中途就开始遗忘前期约定。后来我把每个子代理的边界改成目录级约束比如只负责server/目录、只负责web/目录并配合prompt里的硬性禁止项情况才好转。职责边界定义得越细主代理的调度准确率越高。6.2 并行冲突问题这是我踩过最贵的一个坑。两个子代理同时被委派任务各自都不知情地修改了同一个公共工具文件src/utils/request.ts结果后写入的代理覆盖了前一个代理的改动。最棘手的是被覆盖的那部分改动完全没有日志提示等到运行测试报错才追溯出来。解决方案有两步。第一在prompt中给每个子代理明确规定可写目录公共文件的修改权限收归主代理第二任务下达时如果预判两个子代理可能触及同一文件就改成串行处理——先让 A 改完再让 B 基于新结果继续。6.3 审查代理形同虚设的问题起初我把审查代理和开发代理放在同一轮任务里期望开发完成后自动触发审查。实操发现审查代理经常在开发中途就被唤起此时代码还没改完它审查了一版半成品输出的问题列表毫无价值。调整方式是在任务描述中明确处理顺序比如后端代理开发完成后再让审查代理检查另一个办法是审查代理单独一轮启动专门审查已完成且经过测试的变更。审查这个动作必须以完整、运行不报错的代码为输入否则就是浪费一次回调成本。6.4 上下文与 Token 成本控制Agent Team 虽然并行高效但 Token 消耗也是并行的。跑一个三代理任务总体 Token 消耗可能是单代理的 2 到 3 倍。如果你对成本敏感我建议审查类只读任务用成本更低的模型开发类任务用强模型子代理prompt里要求输出精炼的结果摘要不要回传大段完整代码减少主代理上下文占用任务粒度控制在单个子代理单轮能完成的范围内避免过度拆分导致调度开销大于执行开销我最后的方案是把普通功能开发维持在单代理只有确需并行的大任务才启用完整 Team成本和效率才达到平衡。6.5 给新手的上手建议如果你之前完全没接触过 Agent Team我建议按这个顺序渐进推进先用单代理完成日常开发熟悉 Claude Code 的交互节奏配置一个最简子代理比如只做一个代码审查角色跑通委派流程增加第二个子代理形成两个开发角色的简单分工再逐步加入第三个、第四个同时观察各模块的 Token 消耗和任务完成质量每个阶段都先拿小型任务验证不要一上来就编排五六个代理跑一个大型重构那会让问题排查变得非常困难尤其是当问题可能出在配置、模型、任务描述三个环节中的任何一个时。结束前的最后几点体会回头看我配置 Agent Team 的整个过程最大的感受是这个功能的价值不在多个代理同时干活这个表面现象而在于它逼迫你把项目边界和任务流程想清楚。把文件目录、职责范围、输出格式这些约束写进配置后代理的执行质量变得可预期这本身就是一种工程化收益。最后再分享一个小技巧配置文件的prompt不是写一次就完事的建议每次任务结束后根据主代理的汇报内容反向调整措辞。如果它经常漏掉某个约束就把那条约束写得再显眼一点如果某个输出格式总是不稳定就在后面补一句必须严格按此格式输出不得遗漏字段。模型对提示词的理解是动态的配置也需要跟着实际效果迭代。
Claude Code Agent Team 多代理协作完整配置指南
最近在研究多代理协作开发时被同一个问题反复绊倒单靠一个 Claude Code 实例处理跨模块需求经常出现改完 A 文件忘了 B 文件依赖的情况。后来我把项目拆给多个代理并行处理效率提升非常明显。这篇内容就把我配置 Agent Team 的完整过程、踩过的坑和最终沉淀下来的方案整理出来希望能帮到正在折腾 Claude Code 多代理模式的朋友。Agent Team 是 Claude Code 里用于组织多个子代理协同工作的配置机制。它不改变底层模型能力而是通过一套任务拆解、角色定义和工作流编排让多个代理各司其职。这套机制比较适合中型以上的代码库、跨文件重构、全栈功能开发这类任务。如果你是刚开始接触 Claude Code建议先跑通单代理的基础用法再进入 Team 模式否则排查问题时会混淆到底是模型能力问题还是编排问题。1. Agent Team 到底解决了什么问题很多人在刚接触 Agent Team 时第一反应是这不就是把多个 AI 窗口拼在一起吗。实际用下来差距很大。单窗口的 AI 助手是线性逻辑你给它一个任务它从头做到尾过程中的每个决策都由同一个上下文推导。这种模式在任务范围明确、涉及文件少时没问题但一旦任务跨度变大比如给整个项目增加权限系统 重构所有接口错误处理单代理就会暴露出明显的短板。1.1 单个 Agent 的上下文瓶颈Claude Code 的单代理在同一时刻只能维护一份上下文状态。当对话轮次变多、文件改动范围变大时早期对话里确定的设计决策会被慢慢遗忘或者被后续的信息覆盖。我实测过一个 30 分钟以上的长会话代理开始出现前后矛盾的操作比如先确定了接口返回结构{code, data, message}处理到后半程又按老结构{status, result}去写前端调用。这种问题不是模型笨是上下文窗口有限导致的必然衰减。1.2 并行与专精的差距Agent Team 的核心价值在于两点并行和专精。所谓并行是指多个子代理可以同时处理互不依赖的任务。比如一个代理负责数据库模型设计另一个代理同时写 API 路由还有一个代理做前端页面骨架。三个任务并行推进总耗时不再是单代理那种线性累加。所谓专精则体现在角色定位上。你可以给子代理注入专属的系统提示词和工具白名单比如后端代理只能读写server/目录下的文件、不允许修改前端代码这种硬性边界在单代理模式下几乎做不到——你叮嘱它别碰前端代码它十有八九还是会碰。1.3 什么样的任务适合上 Team按照我现在的经验以下场景适合配置 Agent Team跨模块全栈功能开发比如从数据库到 API 再到前端页面的完整链路大规模重构需要同时修改数十个文件且保持风格统一批量任务比如一套数据迁移脚本需要在多个环境跑需要多角色审查的流程比如编码完成后立刻有独立代理做 code review反之如果只是改个文案、调一个接口参数、修个简单 bug用单代理就好。为这些轻量任务配置 Agent Team配置成本反而比节省的时间更高。2. 从零装好 Claude Code 并完成基础验证在聊配置之前先把安装这步理清楚。Claude Code 目前提供命令行工具和 VS Code 插件两种形态两者可以同时使用共享同一份配置。2.1 CLI 安装方式命令行工具基于 Node.js 发行安装前先确认本机 Node 版本。我建议 Node 18 以上实测 Node 16 也能跑但部分新功能会有兼容告警。# 检查 node 版本 node -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证安装 claude --version安装完成后直接输入claude会进入交互式会话。首次运行需要登录授权按提示跳转到浏览器完成认证认证通过后会自动生成本地凭据后续使用时不需要重复登录。如果你用的是 macOS 或 Linux还可能需要给claude命令配置 PATH 环境变量。npm 全局安装的目录通常在/usr/local/bin或$(npm prefix -g)/bin遇到command not found时优先检查这个路径。2.2 VS Code 插件集成VS Code 插件的方式更适合日常编码场景。在扩展市场搜索 Claude Code 或 Claude Code for VS Code安装后会在侧边栏生成一个聊天面板。插件的好处是能直接读取当前打开的工作区文件配合编辑器的上下文做修改时代理对项目结构的理解比纯 CLI 模式更准确。需要注意VS Code 插件和 CLI 共用同一份配置文件。如果你已经用 CLI 配置过 Agent Team插件侧可以直接继承配置不需要重复设置。2.3 版本升级Claude Code 的迭代频率很高新功能基本都是随版本更新发布。升级方式很简单npm update -g anthropic-ai/claude-code我在实践中遇到过一个典型问题配置了 Agent Team 后发现部分子代理行为异常查了半天发现是本地的 Claude Code 版本太旧某些加载配置时用到的解析能力在旧版本没有。所以遇到诡异问题第一件事先升级版本看看能不能解决。2.4 关于地区可用性的说明在安装或运行过程中如果看到类似 Claude Code might not be available in your country 的提示说明你当前所在的网络环境不在官方支持范围内。遇到这种情况请直接查看 Anthropic 官方文档中列出的支持国家/地区列表以官方说明为准。务必通过正规渠道核实与操作不要使用任何非官方手段绕过限制这既影响账户安全也存在使用风险。3. Agent Team 的运行机制拆解配置 Agent Team 之前先搞清楚它内部是怎么工作的。理解了运行机制后面配置时就知道每个字段的意义了。3.1 主代理与子代理的关系在 Claude Code 的 Team 模式中存在一个主代理Lead Agent和若干子代理Subagents。主代理是入口它接收你的初始任务决定如何拆解、是否委派、以及如何汇总结果。子代理是执行单元。每个子代理有独立的上下文窗口和独立的系统提示词它们之间的对话历史不共享。这意味着子代理 A 改了什么文件子代理 B 并不会自动知道只能通过主代理转述任务要求、或通过读取共享文件来获取信息。这个设计有一个重要含义不要让两个子代理同时修改同一个文件。如果 A 和 B 都在编辑config.ts后写入的一方会覆盖前者的成果而且还不会报错——因为两个代理之间没有消息互通。3.2 任务委派流程一个典型的 Agent Team 任务流程大致如下主代理收到用户请求给用户模块增加导出 Excel 功能主代理判断需要改动server/下的导出接口和web/下的导出按钮主代理把接口任务委派给后端子代理把按钮和前端逻辑委派给前端子代理两个子代理并行开始处理各自维护独立会话子代理完成回传结果后主代理汇总、验证、给出最终交付说明实际运行中主代理不一定等待所有子代理全部完成才收尾它可能先拿到 A 的结果就基于这个结果决定下一步是继续指派还是直接结束。这种动态调度能力是 Team 模式和单纯并行发多个请求的本质区别。3.3 核心配置字段解读Claude Code 的 Agent Team 配置由 JSON 文件承载通常存放在项目根目录下的.claude/目录中。配置文件里字段不多但每个字段都直接决定子代理的行为边界。我用一个简化示例说明核心字段{ name: api-backend-agent, description: 负责后端 API 接口开发与数据库模型设计, tools: [Read, Edit, Bash, Glob], prompt: 你是一个资深后端工程师只负责 server/ 目录下的开发工作。不得修改 web/ 目录下的任何文件。, model: opus }name子代理标识主代理委派任务时用它来指定目标代理description描述这个代理擅长什么。主代理会读这段文字来决定是否把任务委派给它tools允许代理使用的工具白名单不给的它就用不了prompt系统提示词定义代理的角色、职责边界和风格model可选字段指定该子代理使用哪个模型。不同模型成本、能力差异较大可以根据任务重要程度分开配置在实际配置中description和prompt往往决定 Team 协作质量的一半。描述写得越精准主代理的调度判断就越准确提示词约束得越明确子代理越不容易越界。4. 搭建第一支 Agent Team 的完整过程理论讲完下面进入实操。我会用一个前后端分离项目作为示例完整演示三角色 Agent Team 的配置过程。4.1 项目背景与角色划分假设现在有一个项目server/是 Node.js 后端web/是 React 前端根目录还有一份部署脚本。目标是把配置过程做成三个子代理backend-agent负责后端 API、数据库相关开发frontend-agent负责前端组件、页面开发review-agent负责代码审查不直接写代码只读不改为什么不把部署脚本也单独建一个代理因为脚本规模通常较小主代理顺手就能处理。代理数量并非越多越好协作中的沟通开销是实打实的成本这一点后面再展开。4.2 编写三个子代理的配置先在项目根目录创建.claude/agents/目录存放子代理配置文件。mkdir -p .claude/agents cd .claude/agents第一个文件backend.json{ name: backend-agent, description: 负责 server/ 目录下的所有开发任务包括 API 接口、数据库模型、中间件熟悉 Express 和 PostgreSQL, tools: [Read, Edit, Bash, Glob, Grep], prompt: 你是一名资深 Node.js 后端工程师。严格遵守以下规则1. 只能修改 server/ 目录下的文件2. 接口返回格式统一为 { code, data, message }3. 修改数据库模型前必须检查现有迁移文件4. 完成后输出变更文件列表、新增接口说明、需要前端配合的字段变更。 }这个配置里有两个关键设计。第一tools中给了Bash因为后端开发经常要跑测试、执行迁移命令第二prompt里强制规定了输出格式这能让主代理在汇总结果时直接拿到结构化的信息减少无谓的追问成本。第二个文件frontend.json{ name: frontend-agent, description: 负责 web/ 目录下的前端开发包括 React 组件、页面、状态管理、样式熟悉 Ant Design 和 Tailwind, tools: [Read, Edit, Glob, Grep], prompt: 你是一名资深前端工程师。只负责 web/ 目录下的内容。调用后端接口时统一走 src/api/ 目录禁止在其他位置直接写 fetch。组件样式优先使用 Tailwind 类不新建 CSS 文件。完成后输出变更组件列表、接口调用点、对后端接口格式的任何假设。 }注意frontend-agent的tools里我没有给Bash。这是刻意为之——前端子代理不需要执行终端命令不给Bash能避免它自作主张跑构建命令占用资源也减少误操作风险。第三个文件review.json{ name: review-agent, description: 负责代码审查只读不改重点检查逻辑正确性、安全隐患、风格一致性, tools: [Read, Glob, Grep], prompt: 你是一名严格的代码审查员。只能读取文件绝对不能修改任何文件。审查时关注1. 是否有明显逻辑错误2. 是否在文件中硬编码密钥3. 是否违反项目统一规范4. 变更是否超出任务范围。输出格式问题列表按严重程度排序、每个问题的文件位置和修改建议。没有问题时明确说明。 }审查代理不给编辑工具是安全边界设计的一部分。让审查代理只读可以有效避免它顺手修复引入新问题——审查和修改应该是两个分离的动作。4.3 配置主代理的调度规则子代理就绪后还需要在主配置中声明这些代理。.claude/settings.json是 Claude Code 的主配置文件里面可以设置代理列表和默认行为{ agents: { backend-agent: { description: 后端开发子代理使用场景API 开发、数据库变更, model: opus }, frontend-agent: { description: 前端开发子代理使用场景页面开发、组件调整, model: opus }, review-agent: { description: 代码审查子代理使用场景功能完成后检查质量, model: sonnet } } }主配置里的description与子代理文件里的description可以相互补充。主配置里的描述更侧重什么时候该用——它帮助主代理理解调度策略子代理文件里的描述更侧重我是谁——它塑造子代理的执行角色。model字段我给了不同的值两个开发代理用能力更强的模型审查代理用成本更低的模型。审查任务是只读分析对模型的推理深度要求没那么极端成本控制在这个环节最值得做。4.4 验证配置与首次调用配置完成后在项目根目录启动 Claude Codeclaude进入交互界面后输入/agents应该能看到刚配置的三个子代理。之后可以直接下达任务比如给用户模块增加导出Excel功能后端代理负责接口前端代理负责按钮和下载逻辑完成后由审查代理检查变更主代理会按配置中的职责描述自动拆解并分别调用对应子代理。从指令下达方式可以看出你不需要手动逐个唤起子代理只需描述目标主代理负责编排。4.5 各文件在项目中的位置把涉及的路径和职责汇总成一张表方便对照检查文件路径作用.claude/agents/backend.json定义后端子代理角色、工具边界与系统提示词.claude/agents/frontend.json定义前端子代理角色、工具边界与系统提示词.claude/agents/review.json定义审查子代理角色、只读工具边界与审查规则.claude/settings.json声明代理列表、调度描述与模型选择所有配置文件都应该提交到版本库。这样团队其他成员克隆项目后无需额外设置即可复用同一套 Agent Team 配置。5. 对接第三方 API 模型的配置经验不少团队在实际使用中会希望让 Claude Code 的 Agent Team 跑在其他模型上比如 DeepSeek、Qwen、GLM 这类开放接口的模型。这个需求本身是合理的出于成本、数据合规或已有供应商协议等考虑。但在实际操作前有几个基础概念必须先说清楚。5.1 修改模型接入点的方式Claude Code 默认连接 Anthropic 的官方 API 接口。要切换到其他兼容端点通常用环境变量指定 Base URL 和 API Keyexport ANTHROPIC_BASE_URLhttps://your-endpoint.example.com export ANTHROPIC_AUTH_TOKENyour-token claude设置完成后再启动 Claude Code请求就会打到新端点上。这种做法的前提是目标服务提供的 API 与 Anthropic 的接口格式保持兼容。兼容层做得好的服务跑起来基本无感兼容层只覆盖了部分功能的就需要实测确认哪些能力可用、哪些不可用。5.2 使用网关工具管理多模型手动改环境变量略显繁琐如果想在多个模型之间来回切换网关类工具会更顺手。这类工具通常提供一个本地中转服务统一管理各家 API 的 Key 和路由规则。目前社区里比较常见的选择包括各类开源 API 网关用它们也能实现类似 CC Switch 那种图形化切换的效果。我用网关工具的感受是切换速度比改环境变量快很多尤其是在对比不同模型在相同 Agent Team 配置下的表现时来回切几次就能得出结论。但成本也需要注意——网关本身多一跳网络转发在请求量大时延迟会有小幅上升。5.3 第三方模型下的 Agent Team 表现差异把同一个 Team 配置切换到不同模型上运行后我观察到的差异主要有三类。第一类是工具调用稳定性差异。Agent Team 的运行高度依赖主代理正确调用Task工具来完成子代理委派。部分模型在单轮对话里表现不错但进入多轮工具调用循环后偶尔出现忘了正在做任务的断片现象。这类问题只能通过更换模型或缩小任务粒度来缓解。第二类是提示词遵循度差异。prompt中定义的输出格式、禁止修改的目录等硬性约束在不同模型身上的遵守程度不一样。表现好的模型能全程守住边界表现弱一点的中间会走出约束范围需要主代理拉回来。这会导致同一套配置换模型后效果打折的现象。第三类是上下文管理效率差异。子代理回传的任务结果如果信息密度高、结构清晰主代理汇总时就很省事反过来如果子代理输出啰嗦、重点埋藏深主代理的上下文就会被无效信息填满出现类似长会话后忘记早期决策的问题。5.4 我的选择建议如果你所在的环境用不了官方模型或者你想降低成本我的建议是先保持官方架构不变只替换底层模型接口不要一上来就大改配置。换句话说优先用环境变量或网关方式做兼容接入先跑通一个子代理再做整个 Team 的验证。如果你对比了多个模型发现 Agent Team 的模式在某个第三方模型上频繁出错不要急着骂工具先回到单代理模式测一下同一个任务是否流畅运行。单代理都有问题的模型团队模式下只会放大问题。6. 我踩过的坑和沉淀下来的经验配置 Agent Team 不是一蹴而就的事我前后折腾了两周才找到顺手的工作流。过程中踩了不少坑挑几个最关键的分享出来。6.1 子代理职责边界不清晰的教训最开始配置子代理时我把description写得比较宽泛比如负责用户模块相关开发。实际运行时出现了一个问题主代理把涉及用户模块的所有任务都委派给同一个代理包括前端、后端甚至部署脚本的修改。结果这个代理虽然名为主力开发实际却干成了全能角色而且因为职责过宽它的上下文消耗速度极快任务中途就开始遗忘前期约定。后来我把每个子代理的边界改成目录级约束比如只负责server/目录、只负责web/目录并配合prompt里的硬性禁止项情况才好转。职责边界定义得越细主代理的调度准确率越高。6.2 并行冲突问题这是我踩过最贵的一个坑。两个子代理同时被委派任务各自都不知情地修改了同一个公共工具文件src/utils/request.ts结果后写入的代理覆盖了前一个代理的改动。最棘手的是被覆盖的那部分改动完全没有日志提示等到运行测试报错才追溯出来。解决方案有两步。第一在prompt中给每个子代理明确规定可写目录公共文件的修改权限收归主代理第二任务下达时如果预判两个子代理可能触及同一文件就改成串行处理——先让 A 改完再让 B 基于新结果继续。6.3 审查代理形同虚设的问题起初我把审查代理和开发代理放在同一轮任务里期望开发完成后自动触发审查。实操发现审查代理经常在开发中途就被唤起此时代码还没改完它审查了一版半成品输出的问题列表毫无价值。调整方式是在任务描述中明确处理顺序比如后端代理开发完成后再让审查代理检查另一个办法是审查代理单独一轮启动专门审查已完成且经过测试的变更。审查这个动作必须以完整、运行不报错的代码为输入否则就是浪费一次回调成本。6.4 上下文与 Token 成本控制Agent Team 虽然并行高效但 Token 消耗也是并行的。跑一个三代理任务总体 Token 消耗可能是单代理的 2 到 3 倍。如果你对成本敏感我建议审查类只读任务用成本更低的模型开发类任务用强模型子代理prompt里要求输出精炼的结果摘要不要回传大段完整代码减少主代理上下文占用任务粒度控制在单个子代理单轮能完成的范围内避免过度拆分导致调度开销大于执行开销我最后的方案是把普通功能开发维持在单代理只有确需并行的大任务才启用完整 Team成本和效率才达到平衡。6.5 给新手的上手建议如果你之前完全没接触过 Agent Team我建议按这个顺序渐进推进先用单代理完成日常开发熟悉 Claude Code 的交互节奏配置一个最简子代理比如只做一个代码审查角色跑通委派流程增加第二个子代理形成两个开发角色的简单分工再逐步加入第三个、第四个同时观察各模块的 Token 消耗和任务完成质量每个阶段都先拿小型任务验证不要一上来就编排五六个代理跑一个大型重构那会让问题排查变得非常困难尤其是当问题可能出在配置、模型、任务描述三个环节中的任何一个时。结束前的最后几点体会回头看我配置 Agent Team 的整个过程最大的感受是这个功能的价值不在多个代理同时干活这个表面现象而在于它逼迫你把项目边界和任务流程想清楚。把文件目录、职责范围、输出格式这些约束写进配置后代理的执行质量变得可预期这本身就是一种工程化收益。最后再分享一个小技巧配置文件的prompt不是写一次就完事的建议每次任务结束后根据主代理的汇报内容反向调整措辞。如果它经常漏掉某个约束就把那条约束写得再显眼一点如果某个输出格式总是不稳定就在后面补一句必须严格按此格式输出不得遗漏字段。模型对提示词的理解是动态的配置也需要跟着实际效果迭代。