最近我在做某跨平台系统的重构把 Claude Code 从“命令行补全工具”一路用到了“多智能体协作平台”这个程度。说实话一开始我对它没什么期待以为只是能在终端里多聊几句代码的 AI 助手。真正让我改观的是它开始具备完整的子代理机制和多智能体调度能力之后。这篇文章不是官方文档翻译是我在真实项目里反复调教、踩坑之后对这套系统架构的理解它怎么设计、怎么配置、怎么用以及最常见的翻车现场都在哪里。先说一个总体感受Claude Code 的多智能体架构本质上是把“一个人憋大招”变成了“一支团队分工干活”。主代理负责拆解目标、调度资源、汇总结果子代理负责具体领域的脏活累活。这个架构解决的痛点是真实存在的——单 Agent 干一个中型项目的重构上下文窗口很快就撑爆了任务链路一长就顾此失彼。现在这套体系至少在“怎么组织协作”这个层面确实让我觉得 AI 编程协作的方式被重新定义了。1. 多智能体到底是什么先看单 Agent 模式卡在哪1.1 单 Agent 的瓶颈上下文就是那堵墙用过命令行 AI 助手的人应该都有同感早期的编码 Agent 本质上是一个“记忆力有限的全能选手”。你把需求丢给它它读代码、改代码、跑命令全程只有一份上下文窗口。这个窗口往小了说是几千个 token往大了说也就是几十万 token听着挺大但塞进一个中型项目的源码、报错日志、测试输出很快就会见底。我自己遇到的典型场景是这样的让 Claude Code 去重构某模块任务包括“先理解现有逻辑再迁移到新架构最后补齐单元测试”。单 Agent 模式下它前半段读了一堆文件上下文里塞满了各种类型定义和函数签名等真正要动手写新代码的时候前面读过的内容已经被压缩得不成样子了。于是你就会看到它反复问同一个问题、反复读同一个文件甚至把以前看过的内容忘得一干二净。更难受的是任务间的相互干扰。让同一个 Agent 先写后端接口再写前端页面它很容易把前后端的代码风格搞串。因为所有知识都堆在同一份上下文里缺乏隔离决策时就会互相污染。这就好比让一个全栈工程师同时开三个项目记忆全叠在一起不出错才怪。单 Agent 还有一个隐患工具调用链太长。一次重构可能要调用几十次文件读写和命令执行每一步都可能出错。只要中间有一次 Bash 命令抛了个诡异异常Agent 就可能陷入死循环一遍遍尝试同样的修复浪费大量时间。1.2 从“一个人干活”到“一支团队协作”Claude Code 的多智能体架构核心思路就是不再让一个 Agent 包揽所有事而是引入“编排者 执行者”的角色分层。主 Agent 是编排者负责理解你的目标、制定计划、决定哪些任务自己做、哪些任务拆给子代理最后把子代理的结果汇总回来形成完整交付。子代理是真正专职干活的角色。比如专门的文档子代理、代码搜索子代理、代码审查子代理、浏览器操作子代理。每个子代理有自己独立的上下文空间只接收主代理派发过来的精简指令干完活之后把“结果摘要”返回给主代理。这就像你是一个项目经理手里有几名各司其职的工程师你不需要记住每个人手里的全部细节只需要知道他们最后提交了什么成果。这个架构最聪明的设计在于上下文隔离。子代理自己的思考过程、读过的文件、跑过的命令不会全量塞回主上下文。主代理拿到的是一个结构化处理过的小结所以它的“工作记忆”始终处于一个相对干净的状态。这从根本上缓解了单 Agent 模式那种“什么都知道一点但什么都记不全”的尴尬。用一句大白话总结单 Agent 是“全栈超人”多智能体是“一支可以随时扩编的项目组”。后者的优势不是单点能力更强而是组织方式更合理容错率更高。2. 系统架构核心模块拆解2.1 编排层主代理怎么当“包工头”Claude Code 的编排层是整个多智能体系统的中枢。它负责接收用户指令把模糊的自然语言需求转化成一系列可执行的任务项。如果任务复杂度不高主代理直接就自己做了一旦任务涉及多个领域它就会考虑拆分子任务并派给对应的子代理。我观察到的调度逻辑是“先尝试后拆分”。主代理不会一上来就疯狂建子代理而是先自己跑一遍发现阻力或者工作量过大时再主动委派。这个行为很像一个资深工程师的习惯能自己顺手做的就不开会避免过度协作遇到明确的分工边界比如要并行审查多个文件、要跑浏览器验证页面效果那就让子代理上。编排层还有一个容易被忽略的职责结果回收与冲突处理。当多个子代理并行返回结果时主代理需要把这些结果合并进整体方案。比如重构某个模块时文档子代理给出了接口变更说明代码审查子代理提出了三个隐患主代理就要把这些信息整合起来决定哪些采纳、哪些忽略、哪些需要二次验证。在实操中编排层的效率高低主要看主代理的指令拆解质量。你给的需求越清晰、边界越明确它拆出来的任务链就越合理。如果你上来就丢一句“帮我把这个项目优化一下”那它也只能拆出一些泛泛而谈的优化点整体效果自然差很多。2.2 工具层读写、执行、检索的底层底座无论是主代理还是子代理最终都要落到工具上。Claude Code 的工具层大致可以分为三类文件读写类、命令执行类、代码检索类。文件读写是最常用的一组。主代理可以直接编辑文件子代理如果配置了相应权限也可以编辑。但这里有个关键设计写操作的权限往往被严格控制。在很多团队实践中子代理默认只读只能看代码、搜代码、跑测试真正的修改动作由主代理统一执行。这样能避免多个子代理同时改一个文件造成互相覆盖。命令执行类工具就是 Bash。它可以跑构建、跑测试、装依赖、查日志。多智能体场景下Bash 工具的权限管理会变成安全重点。比如某个子代理只有执行npm test的权限没有全局 shell 权限这样即使它被诱导输出了一堆危险命令也无法真正执行。代码检索类工具包括按文件名搜索的 Glob、按内容搜索的 Grep以及直接读取特定文件内容的 Read。这些检索操作是子代理的“眼睛”没有它们子代理就只能在黑暗中摸索。实际使用中我通常会给审查类子代理配上完整的检索工具集而给一些执行型子代理只保留运行命令的 Bash。工具层是整个架构的底盘主代理和子代理都是在这些工具之上工作。工具配置得越合理多智能体协作就越顺畅。反过来工具权限放得太宽出事故的概率也会直线上升。2.3 记忆层CLAUDE.md 与会话压缩机制多智能体系统能不能长期稳定用记忆层是关键。Claude Code 的记忆体系里CLAUDE.md 是最重要的文件。它有点像团队的“作战手册”全局级别的 CLAUDE.md 写通用规范项目级别的 CLAUDE.md 写这个项目的技术栈、目录结构、命名约定、常见命令。有了 CLAUDE.md每次启动会话时主代理都会先读一遍这本“手册”从根本上减少反复解释背景的麻烦。比如我那个跨平台系统CLAUDE.md 里明确写了“业务逻辑放 services 层UI 组件放 views 层状态管理统一用某一套方案”这样无论派哪个子代理去干活它都能迅速对齐代码习惯而不是凭通用知识瞎猜。会话压缩则解决的是“越聊越长”的问题。Claude Code 会在上下文接近上限时自动压缩历史保留核心决策和结论丢弃冗余细节。你也可以手动用/compact命令强制执行压缩或者在觉得对话已经乱成一锅粥时直接用/clear开个新会话。从多智能体的角度看记忆层的最大价值是“传承”。子代理不需要记住整个项目的历史CLAUDE.md 已经替它们记好了。这就好比新员工入职不用重新发明一遍公司流程看一遍入职手册就能上手干活。2.4 权限层与事件层安全与自动化的双保险多智能体系统跑起来之后控制力就变得格外重要。权限层解决的是“谁能干什么”的问题。Claude Code 的权限模型是经典的 ask / allow / deny 三态。默认情况下写入文件和执行命令会询问你你可以在配置文件里按命令和工具类别设置自动允许对于高风险操作还可以直接加入拒绝列表。事件层是另一个隐藏利器也就是 Hooks。它允许你在 Claude Code 的各个生命周期阶段触发自定义脚本。比如在工具执行前拦截命令、在子代理完成工作时触发通知、在对话结束时自动跑一遍测试。这有点像是给多智能体系统加了一套“自动化流水线”让整个编程协作过程不再只是人机聊天而是能接入现有工程体系。我自己体会最深的是 PreToolUse 这个钩子。我给它挂了一个脚本凡是检测到git push或rm -rf这类命令就自动拦截并弹出确认提示。这相当于给子代理的越权行为上了一道紧箍咒即便某次调度逻辑出问题了也不至于直接造成破坏。3. 实操从零配置一套多智能体协作流程3.1 初始化项目环境先写好你的“作战手册”实操的第一步不是急着写代码而是把记忆层搭好。进入项目目录运行claude启动会话然后执行/init。这个命令会扫描当前项目的结构和技术栈生成一份初始的 CLAUDE.md。不过我个人建议自动生成之后一定要手动补一段“项目纪律”。比如我的某跨平台系统 CLAUDE.md 里会写# 项目说明 本项目是一个跨平台应用系统技术栈包括…… ## 目录结构 - src/services业务逻辑 - src/views界面组件 ## 代码约定 - 所有 API 调用统一走服务层不允许在页面里直接 fetch。 - 新增功能必须补充单元测试。 ## 常用命令 - npm run dev启动开发环境 - npm run test跑全部单测 - npm run lint代码风格检查这些内容看似简单实际价值极高。子代理被派发任务时会先读这份手册行为偏差会明显减少。你不想反复叮嘱的规则写进 CLAUDE.md 就相当于写进了每个子代理的初始化记忆。3.2 自定义子代理创建一个“代码审查专家”Claude Code 允许自己定义子代理存放位置是项目内的.claude/agents/目录或用户级的~/.claude/agents/目录。每个子代理就是一个 Markdown 文件通过 frontmatter 配置基本属性正文写角色指令。以代码审查子代理为例我写的内容大概是这样的--- name: code-reviewer description: 负责审查代码质量、安全性和边界条件输出问题清单 tools: Read, Grep, Glob --- 你是一名资深代码审查专家。收到任务后请先使用 Grep 和 Glob 定位相关文件 用 Read 阅读完整实现然后检查以下重点 1. 是否存在安全漏洞如注入、越权、硬编码密钥。 2. 边界条件是否处理如空值、超时、并发冲突。 3. 是否遵循项目 CLAUDE.md 中约定的目录和命名规范。 4. 是否存在明显性能问题如不必要的重复计算和请求。 输出格式按严重程度排序的问题清单每条包含文件路径、行号、问题描述和修改建议。 不要直接修改代码只负责审查和报告。这里有个关键点我刻意在 tools 里只给了 Read、Grep、Glob没给 Write 和 Bash。因为审查者只需要看代码不需要改代码。没有写权限它就无法越权动代码没有执行权限它也无法跑危险命令。这就是权限隔离的实际应用。配置好后运行/agents命令检查加载状态然后在对话里让它干活时主代理会自动根据任务性质决定要不要调用这个子代理。3.3 实战场景让主代理调班子代理完成模块重构为了说清楚整个协作流程我拿一个真实发生过的场景举例重构某跨平台系统的登录模块。旧模块耦合严重登录逻辑和 UI 混在一起还要同时支持账号密码、第三方登录、多端会话改起来很费劲。我向 Claude Code 发出的指令是claude 重构登录模块 src/auth要求逻辑与 UI 分离保留全部现有接口迁移到新目录结构。先分析现状再给方案然后实施最后自查。主代理的调度大概是这样的先自己用 Glob 和 Grep 找出所有登录相关文件读一遍核心逻辑确认模块边界。这个阶段我发现它会自主决定不调用子代理因为“分析现状”属于主代理的分内工作。分析完成进入方案设计后主代理会输出一份重构计划。这时我开始介入对方案做了些调整让它优先抽出会话管理逻辑。改完方案后主代理开始动手写代码。文件编辑这种操作发生在主代理的上下文里每个改动点都很清晰。重构完成后我在对话里追加了一句“让 code-reviewer 审查一下改动”。主代理就派出了一个子代理实例子代理用自己独立的上下文读了一遍所有改过的文件回来输出了一份审查报告。报告里找到一个我没注意的问题某个会话续期接口在 token 过期时没有返回统一的错误码。主代理拿到这个结果后直接修掉了这个问题再让子代理复查确认。整个过程就像一个小团队项目经理负责拆活和干核心逻辑资深工程师负责挑毛病最后项目经理把问题修完收工。这就是多智能体协作的标准工作流。3.4 利用 Hooks 把流程自动化多智能体系统跑通之后还有一个提效神器就是 Hooks。它可以让整个协作流程融入到你的工程链路里。我现在的项目配置里挂了这样几个钩子{ hooks: { PostToolUse: [ { matcher: Bash(npm test*), hook: python3 ~/scripts/notify.py 测试完成 } ], PreToolUse: [ { matcher: Bash(git push*), hook: python3 ~/scripts/guard.py git push } ], Stop: [ { hook: python3 ~/scripts/log_session.py } ] } }PostToolUse钩子匹配到npm test命令结束时触发一个通知脚本。这样子代理或主代理跑完测试我立刻能知道结果不用一直盯着终端。PreToolUse钩子对git push做拦截检查。脚本里可以加上“当前分支是否干净”“测试是否已跑过”一类的前置条件不满足就中断操作。这一招在子代理执行命令时尤其有用等于在自动化流程里加了一道人工护栏。Stop钩子在每次对话结束时触发把会话摘要记到日志里。通过日志文件我能复盘主代理和子代理的协作路径看看哪类任务调用了哪个子代理、在哪个环节浪费了最多时间。这些数据比感觉靠谱得多。4. 权限配置与模型选型的心得4.1 权限策略怎么设最顺手权限配置的核心原则是“默认收紧按需放开”。很多新手一开始图省事把所有操作都设置成 allow结果就是 Agent 满世界乱改改错了还得花更长时间修复。另一个极端是全部 ask弹窗不断效率低到没法用。我的做法是分阶段调整。项目刚开始时权限保持相对严格命令执行全部询问文件写入也先问。跑几轮对话之后观察 Agent 的行为是否靠谱再逐步把高频且低风险的操作加入 allow 列表。比如npm run dev、npm test这类命令风险极低直接放行。git push、rm -rf、提交到生产环境这类高风险命令要么 ask 要么 deny。配置文件一般在~/.claude/settings.json用户级或项目.claude/settings.json项目级。我通常会写类似这样的内容{ permissions: { allow: [ Read, Glob, Grep, Bash(npm run dev), Bash(npm test) ], ask: [ Edit, Write, Bash(git push*), Bash(npm install*) ], deny: [ Bash(rm -rf *), Bash(rm *) ] } }注意一点权限配置对子代理同样生效。如果某个子代理没有 Write 权限它就算想改文件也改不了。这比我手动告诉它“你不要改文件”要可靠得多。4.2 不同任务该给子代理配什么模型Claude Code 里主代理和子代理都可以指定模型。不同模型档位的能力和成本差异挺大的我的选择逻辑很简单任务越复杂、越需要全局理解用越强的模型简单机械的任务用轻量档位就够了。深度重构、架构设计、多文件联动修改这种任务我会让主代理用最强档位因为它的上下文管理能力和代码生成质量直接决定整体效果。代码审查、文档撰写、接口梳理这类子代理可以用能力稍弱的档位因为这些任务相对聚焦输出格式也相对固定对模型的上限要求没那么高。还有一个技巧是给不同子代理在定义文件里直接写死模型--- name: docs-writer model: sonnet ---这样派发任务时就不会默认继承主代理的高成本模型长期跑下来能省不少开销。4.3 上下文预算管理别一次塞太多活即使有了多智能体架构上下文管理仍然是决定成败的细节。子代理的上下文虽然被隔离了但主代理的上下文仍然是有限的。如果主代理身上挂了太多子代理的返回结果同样会膨胀。我的经验是“一次只推进一件事”。需要并行处理的任务可以先列出来让主代理逐个派发而不是一口气全丢进去。一个子代理返回结果后先审查摘要确认没有需要追加追问的地方再派下一个任务。这样做的好处是主上下文始终保持精简每个子代理的任务指令也更清晰。另一个小技巧是用符号精准引用文件而不是让 Agent 自己满项目搜索。比如claude 修改 src/views/login.tsx 的样式问题它就不用先花一堆 token 去找文件了。需要看目录结构时用/status查看当前上下文的占用情况快满的时候果断/compact或/clear。5. 踩坑记录与排查速查表5.1 子代理返回结果太短主代理拿不到足够信息这个坑在审查类任务里特别常见。子代理可能只返回一句“没有发现问题”但主代理不知道它到底有没有全面读代码。我第一次遇到这种情况时还以为是代码真的没毛病后来才发现是子代理的指令里没写清楚输出标准。解决办法是细化子代理定义中的输出要求。刚才我在 code-reviewer 的定义里就写明“按严重程度排序的问题清单包含文件路径、行号和修改建议”。有了这些强制约束子代理就没法偷懒只回一句话。任何自定义子代理我都建议在指令里把“输出格式”写死越具体越好。5.2 子代理越权改了不该改的文件这个问题的根源基本是权限配置没跟上。某个子代理需要执行 Bash 跑测试我就给了它 Bash 权限结果它在别的任务里直接用 Bash 调用了编辑命令。权限没有细分到命令级别等于放开了口子。现在我的配置原则是子代理默认零写权限除非明确需要否则不给 Edit 和 Write。需要跑测试就只给Bash(npm test*)这一条命令的权限。这样即使子代理产生错误意图它能执行的破坏性操作也非常有限。5.3 上下文还是爆了主代理开始胡言乱语即使有子代理隔离主代理上下文在超长会话里还是会慢慢涨上去。表现就是它开始重复早期讨论过的问题或者干脆忘了项目背景。这时候最有效的操作不是让它继续而是用/compact压缩或者/clear开新会话后引用之前的总结。养成一个习惯每个大节点完成任务后让主代理输出一段“本次改动总结”然后/clear。下次再开会话时把这段总结丢给它它就能快速接力而不是靠那点压缩残留硬撑。5.4 Hooks 脚本报了错但没看到失败Hooks 脚本失败往往是静默的你只会觉得“怎么该出现的通知没出现”而不会看到明确错误。排查方式是自己手动执行一遍脚本命令确认脚本本身没有 bug再检查 hooks 配置的路径是不是绝对路径。相对路径在子代理的环境里经常解析到错误位置。另外Hooks 的 matcher 匹配规则也容易踩坑。Bash(npm test*)只能匹配以npm test开头的命令如果子代理执行的是npm run test就匹配不上了。这类细节不实际跑一遍很难发现建议在前期调试时故意触发一次验证拦截是否生效。5.5 常见问题速查表症状可能原因对策子代理只回一句话没干活指令里没定义输出格式在子代理 Markdown 中写死输出要求主代理反复读同一个文件上下文被压缩记忆丢失用 精准引用任务拆小及时 /clear子代理乱改文件权限给太宽子代理默认只读按需放开单条命令命令弹窗频率太高ask 列表过宽把低风险命令加入 allow 列表危险命令没拦住matcher 规则没覆盖实际命令完善匹配规则配合 PreToolUse 钩子拦截自动回复越来越短、质量下降上下文接近上限/compact或/clear后传递总结接力最后分享一个小技巧让子代理在做任何事之前先输出一段“执行计划”。这个动作成本极低但价值极高。你可以在它真正动手之前就判断方向对不对避免它闷头跑偏十几分钟。多智能体系统最怕的不是能力不足而是方向失控。如果每个子代理都能先列计划、再动手、最后汇报整个协作流程的可控性会提升一个量级。这也是我在实际项目里收获最大的一条经验。
