好些人用 Claude Code 还停留在单步聊天阶段让它改个文件、跑个测试、再改、再跑跟对着一个只会等你下指令的实习生说话似的。我自己刚上手那阵也这样一个简单的需求能来回拉扯十几个回合上下文越聊越乱最后它连自己改过什么都忘了。后来我把重心从单步调用挪到多 Agent 编排上情况才彻底改观——主任务拆给多个专职子任务并行推进把错误处理和自动修复也交给 Agent 自己去闭环再配合 Routine 脚本把反复要做的流程固化下来。这篇文章就把我实际跑通的这套架构拆开给你看包括为什么这么设计、每一步在解决什么问题、有哪些坑是我踩过之后才想明白的。适合已经装好 Claude Code 但觉得它也就那样的人也适合刚知道这个工具、想一步到位少走弯路的人。1. 单步聊天到底卡在哪从我问你答到多 Agent 协作的现实差距先别急着聊架构得把问题本身看清楚。单步聊天模式不是不能用小修小补完全够但一旦任务涉及多个文件、多个依赖环节它的短板就非常致命。1.1 单步 Chat 的三大死穴第一个死穴是上下文断链。单步聊天里每一次提问模型只能依赖你当前给的这句话加上窗口内的历史记录。你在第 3 步让它改了函数 A第 5 步让它调函数 B到第 8 步你问它A 和 B 的接口对得上吗它可能已经记不清 A 的具体签名了。模型不是状态机它不会帮你维护一张当前工程状态表。第二个死穴是职责混乱。一个 Agent 在同一轮会话里又要理解需求、又要改代码、又要跑测试、又要排查报错等于一个人同时干产品、开发、测试、运维四份活。它自己在不同角色间切换时非常容易把测试用的临时逻辑写进正式代码里。第三个死穴是反馈延迟。每一步都要你手动看结果、手动判断下一步macOS 上开十几个终端窗口来回切纯属自虐。1.2 多 Agent 不是噱头它解决的是上下文丢失和职责混乱Claude Code 的多 Agent 编排核心思路其实非常简单每个 Agent 只干一件事干完把结果写进文件或结构化输出下一个人读文件接着干。你不需要给每个 Agent 灌全部上下文只需要给它入口条件和出口标准。比如阅读src/parser.ts输出接口清单到docs/parser-api.md它不需要知道整个项目长什么样只需要把这一件事做好。这样上下文自然就隔离了职责也清了。我当时为了验证这个思路做了一个很小的实验同一个需求让单步模式和多 Agent 模式各跑一遍任务是把一个 Express 服务的路由拆成三个文件。单步模式花了 40 多分钟中间有两次上下文混乱把旧路由定义又重复写了一遍多 Agent 模式拆成分析路由 - 生成文件 - 更新入口 - 跑测试四步总共 20 分钟出头最后测试一次通过。差距不是模型能力而是工作方式的差距。2. Claude Code 多 Agent 编排的底层逻辑主从分工、任务队列与状态传递真正上手编排之前得先把它的身份体系搞清楚。Claude Code 的 Agent 分两种**主 Agent或叫 Orchestrator**负责接收你的自然语言指令、拆分任务、调度执行**子 AgentSubagent**负责执行被分配的具体任务。这个结构有点像一支施工队工头理解图纸、分派工人、检查质量工人只管自己那面墙。2.1 主 Agent 与子 Agent 的职责边界主 Agent 是你直接对话的对象它的智能程度决定了整个编排的上限。它要做三件事把模糊需求拆成明确的子任务、给每个子任务配一个合适的子 Agent、把子任务的产物汇总成最终结果。子 Agent 则更像专家系统你可以给它不同的 system prompt让它扮演不同的角色——比如TestAgent只写测试用例ReviewerAgent只做代码审查DocsAgent只维护文档。这里有个非常关键的点子 Agent 之间不直接通信。它们只能通过文件系统、标准输出、或者特定格式的状态文件来传递信息。这看起来像是限制其实是优点——你永远能追溯哪个 Agent 在哪个环节写了什么。2.2 任务编排中的上下文传递机制子 Agent 不共享上下文所以上下文是通过产物文件传递的。我在实践里总结了一套三文件传参规则task.md——主 Agent 给子 Agent 的输入描述任务目标、约束条件、验收标准result.md——子 Agent 写回的输出包含做了什么、结果在哪、有没有遗留风险state.json——可选记录任务执行过程中的关键状态比如改动了哪些文件、运行了哪些命令这三个文件的名字不固定但思路一定是输入文件 输出文件 状态文件。子 Agent 一启动的第一件事就是读task.md干完活第一件事就是写result.md。主 Agent 不需要盯着过程只需要在所有子任务结束后去读各自的result.md。2.3 编排策略组合串行、并行、并行竞标光有 Agent 体系还不够编排策略直接决定效率。我常用三种策略串行编排前一个任务产物是后一个任务的输入。比如先分析需求文档再写设计再写代码。适合依赖强的场景。并行编排任务之间没有依赖同时派多个子 Agent。比如给四个模块分别写测试。效率提升最明显。竞标式编排同一个问题让多个子 Agent 各自给出方案主 Agent 选优。适合技术选型、架构决策这类有分歧空间的场景。我自己的经验是串联适合精度并联适合速度竞标适合方向不明确的探索。实际项目里往往是三者混合。比如一次重构任务可以这么拆两个并行 Agent 分别分析前端和后端模块串行交给一个 Agent 出统一重构方案再竞标式让两个 Agent 提出不同的目录结构设计最后主 Agent 拍板。3. 闭环自愈让 Agent 从报错就停到识别-修复-验证-回归的自动循环这一节我想认真展开因为闭环自愈是我觉得 Claude Code 被低估最多的能力。很多人用它写代码写出来的代码有 bug跑测试失败了它就停下来等人处理。但你完全可以给它设计一个自愈循环让它在设定好的安全范围内自己发现问题、自己修、自己验证。3.1 闭环自愈的核心链路失败检测-归因-修复-验证闭环自愈的本质是一个控制回路四个环节缺一不可失败检测Agent 需要在任务定义阶段就明确什么算失败。是测试不过是编译报错是某个命令返回非 0 退出码不能是我感觉不太对这种模糊信号。归因拿到失败信号后要能定位到具体文件、具体函数、具体依赖关系。这一步失败后续全是瞎修。修复自动提出修复方案并执行这一步必须限制在白名单命令范围内比如修改代码、重装依赖、调整配置。验证修复后重新触发失败场景确认问题真的消失了同时做回归验证确认没有破坏其他功能。我把这套链路写成一个自愈指令段落放在每次派发子 Agent 的 task.md 尾部。效果立竿见影——但前提是每一步都有清晰的触发条件绝对不能让它自由发挥。3.2 自愈循环的显式指令设计让它自己修 bug这种事光说如果失败了就再试试等于没说。下面是几个我实际用过的指令片段它们的效果远好于模糊表达1. 修改完代码后执行 npm run test:unit。 2. 如果该命令返回非 0 退出码 a. 读取测试输出中的 FAIL 行定位失败用例和 stack trace。 b. 根据 stack trace 定位到对应源码文件只允许修改该文件及该文件直接 import 的文件。 c. 修改后重新执行 npm run test:unit。 3. 如果连续 3 次尝试仍失败停止修改将完整失败日志写入 artifacts/failed-test.log并在 result.md 中标记 status: need-human。这看起来像在写 for 循环控制语句实际上就是在给 Agent 定义循环边界。边界是自愈的灵魂——没有边界它可能因为一个无关紧要的测试断言把你的整个模块重写一遍。3.3 自愈的边界与代价什么时候该开、什么时候该关自愈不是越强越好。我踩过一个大坑让一个子 Agent 自愈一个正则表达式解析 bug它自动改了几次之后测试倒是过了但性能下降了一倍多——因为它把正则换成了循环匹配。后来我在自愈指令里加了一条硬约束任何修复不得改变输入输出的时间复杂度和空间复杂度这类问题才被堵住。还有一类风险是自愈循环的误改。比如测试本身写错了Agent 会为了通过测试去改源码而不是改测试。这时候你应该关闭自愈或者限制只允许修改 src/ 目录不允许修改 test/ 目录。我的通用规则是新写代码时开启自愈限制次数 2-3 次。重构时开启自愈但必须配有静态类型检查作为第一道关卡。改测试环境、CI 配置时关闭自愈任何失败都要上报。4. Routine 脚本化把会做的事变成能复用的事多 Agent 编排解决的是单次复杂任务的拆解但如果每个新项目都要重新设计一遍编排流程那就太蠢了。这时候就需要 Routine——把固定流程固化成脚本化流程。我更喜欢叫它流程模板或者套路本质上就是一套可复用的提示词工程模板加配套文件结构。4.1 什么是 Routine 脚本化从一次性任务到标准化流程简单说Routine 就是把分析依赖 - 设计接口 - 生成实现 - 编写测试 - 跑测试 - 修正这种通用流程写成一份固定的指令文档以后每次遇到同类任务直接把这份文档丢给 Agent它就会按流程走。你不用每次重新描述你先看看这个再改改那个。我的第一个 Routine 是新增一个 REST API 接口沉淀之后整个流程稳定在 5 分钟以内从路由到 controller 到 service 到 DTO 到测试一步到位。Routine 的价值不在于做得多聪明而在于每次执行的结果都稳定、可预期。4.2 一个实用的 Routine 骨架从输入到验收的全流程一个合格的 Routine 文档至少包含七个部分适用条件这个 Routine 什么时候能用、什么时候不该用。输入约定需要哪些信息比如需求描述、依赖约定、编码规范链接。执行步骤按顺序排列的操作步骤每一步都标注产出物。质量门禁什么条件下才算完成比如必须有测试用例且通过。失败处理哪些情况允许自愈哪些情况必须停下上报。输出产物最终会生成哪些文件、更新哪些文件。耗时预估自己心里有数Agent 也知道预期节奏。一个典型的写一个新 Go 服务 Routine 骨架长这样Routine: go-service-starter 适用: 需要在现有仓库中新增一个独立的 Go 微服务 输入: - 服务名 - 对外暴露的接口列表 - 依赖的上游服务 步骤: 1. 读取仓库根目录的 go.mod确认 Go 版本和已有依赖 2. 创建服务目录生成 main.go、config.go、handlers/ 结构 3. 为每个 handler 编写对应的 http.HandleFunc 注册代码 4. 编写 service 层逻辑禁止在 handler 里写业务逻辑 5. 为每个 handler 编写 table-driven 测试 6. 执行 go test ./... 如果失败定位到单个测试允许自愈 2 次 质量门禁: - go vet ./... 无输出 - 每个 handler 覆盖率不低于 80% - 接口文档写入 docs/api.md 失败处理: - 超过 2 次自愈失败停止并输出日志 输出: - 服务代码、测试代码、接口文档4.3 Routine 的版本管理与团队共享Routine 本质上是代码同样需要版本管理。我强烈建议把 Routine 文档放进 git 仓库和项目代码放一起。这样每次演进都有记录团队成员也能 review。团队协作时还有一个隐藏收益新人不需要手把手教了把 Routine 文档丢给他他自己跑一遍流程就上手了。我通常把 Routine 放在.claude/routines/目录下命名规则是动词-领域-工具比如generate-rest-api-go.md、refactor-legacy-module-python.md。文件名一眼能看出用途找起来也方便。团队共享的时候直接在项目 README 里写一行新增接口请调用 generate-rest-api-go Routine就能减少大量重复沟通。5. 从零跑通 Claude Code 环境安装、终端执行与 VSCode 集成说了这么多架构层面的东西如果环境没配好全是纸上谈兵。这一节把从安装到接入 IDE 的过程完整过一遍顺手把我踩过的坑标出来。5.1 安装与账号选择有哪些坑、怎么选安装本身很简单一条 npm 全局安装命令就能搞定。真正要动脑子的是账号。注册账号可以免费使用一定额度适合体验、学习、跑小任务。额度用完会提示等待或者升级。不注册账号处理一些简单任务也能跑但会话持久化、历史恢复、高级模型能力都会受限。订阅制高频开发者最省心的模式不用盯着额度过日子。我自己的使用体感是如果是拿它当主力工具、日常协作都在里面订阅比按量付费划算。如果只是偶尔试一下注册免费账号先跑明白再决定也不迟。注意如果在国内网络环境安装后运行提示所在地区不可用这个提示是针对服务可用区域的不要折腾所谓绕过的办法直接以官方当前支持范围为准。官方文档经常会更新支持地区列表以它为准。5.2 终端直接执行命令一次把权限边界摸清楚Claude Code 最强的地方之一是能在终端里直接跑命令。你不需要把命令复制到别的终端它会自己执行ls、cat、npm install、git status这些操作。但这一步权限很大必须有明确边界。我的建议是两步走第一步在第一次使用时仔细观察它请求执行命令的交互方式第二步在会话一开始就明确声明哪些命令不允许执行比如rm -rf、sudo、git push --force。你可以在 prompt 里直接写你可以执行任何与代码构建、测试、依赖安装相关的命令。禁止执行任何删除性、强制推送、涉及生产环境的命令。即便有这层声明我也建议你保持对执行日志的关注。自己写过的代码自己跑过的命令心里有底。5.3 VSCode 插件与第三方模型接入CC Switch 等工具的取舍长期重度使用的话纯终端体验还是有点累VSCode 插件是更好的选择。插件的好处在于可视化 diff、文件树、断点调试和无缝集成。安装插件后配置的关键是把默认的模型、API 地址、工作目录都写好。很多人在折腾换模型社区里有 CC Switch 这类工具可以把后端切到 DeepSeek、Qwen、GLM 等第三方模型。我的态度是能跑通但要想清楚为什么。如果你只是图便宜或者图某个模型的中文能力强没问题如果用第三方模型意味着你放弃了官方模型在 Agent 工具调用、指令遵循、格式输出上的诸多特性多 Agent 编排的稳定性可能明显下降。第三方 API 接入前先想清楚你是要一个便宜的聊天框还是要一个稳定的自动化开发流水线。6. 一个完整的实战编排示例从需求到验收前面讲的全是概念和组件下面拿一个完整例子串一遍。假设我要给一个 TypeScript 项目新增一个批量导出用户数据的接口用多 Agent 编排加自愈加 Routine 的方式跑完整流程。6.1 任务拆分与子 Agent 分配拿到需求后主 Agent 先拆分。我的拆分方式是三层架构层数据从哪来、导出格式是什么、任务是同步还是异步。这个子任务最难派给一个带架构背景提示词的 Agent。实现层写 controller、service、repository 三块代码。验证层写单元测试、集成测试跑起来验证。三个子任务按架构 - 实现 - 验证串行执行但实现层内部可以并行——controller、service、repository 三个文件分别给三个并行 Agent 写。它们不需要知道彼此的实现细节只要在开工前统一读同一个接口设计文档。6.2 自愈在实际任务中的完整介入过程整个流程里自愈介入最多的环节是验证层。写单元测试的 Agent 跑完测试后发现有三个测试失败了。依照自愈指令它做了这样的归因第一个失败是 DTO 字段命名不一致修复方法是统一为camelCase第二个失败是null值处理上 repository 层返回了undefined但 service 层断言的是null第三个失败是测试本身写错了——mock 数据的id重复了。前两个它直接修源码第三个它改了测试数据。这里你能看到自愈的正确用法区分产品代码的问题和测试代码的问题分别处理而不是一股脑去改源码。这个区分能力需要在自愈指令里写得很明确否则 Agent 会倾向于改源码让测试通过。6.3 执行结果与产物组织方式流程结束后工作目录里多出了这些文件src/controllers/user-export.tssrc/services/user-export-service.tssrc/repositories/user-export-repo.tstests/unit/user-export-controller.test.tstests/integration/user-export-flow.test.tsdocs/api/user-export.md我让主 Agent 在全部子任务完成后写了一份简短的execution-summary.md里面包含每个子任务的耗时、改动文件、未解决的风险点。这件事特别值得做——它让整个编排过程可审计出问题的时候你知道该找谁。7. 编排与自愈踩坑实录翻车之后才明白的道理架构设计得再漂亮实操里该翻的车一个都不会少。最后这一部分我把几个最有代表性的坑展开讲讲。7.1 并发写同一个文件并行编排的真正风险点并行编排最爽也最容易出事。我有一次同时派了三个 Agent 去改同一个配置文件结果三个 Agent 各自读取了旧版本的配置依次写入最后一个写入的覆盖了前两个的改动等于前两个 Agent 白干。从那以后我定了一条铁律多个 Agent 并行时绝对不允许修改同一个文件如有共同依赖先把共同依赖提取成稳定的独立文件。如果非要改同一个文件就改成先写独立片段再由一个汇总 Agent 合并。这是唯一的稳妥解法。7.2 自我修复的过度修复没有边界时它有多可怕自愈指令只写了定位问题并修复没有加边界约束的话Agent 的创造力会让你头疼。我经历过的真实案例一个简单的 CSS 布局错位Agent 为了修它把整个组件从 class 组件重写成了函数组件还顺手更新了三个无关文件。功能确实没问题了但 diff 大到没法 review。解决办法我上面提过——限制改动范围、限制重写阈值。更细一点可以在自愈指令里写明只允许改动与失败用例直接相关的函数如果修复需要改动超过 3 个文件必须停下征询确认。7.3 Routine 过度抽象把简单事做成重流程Routine 是把稳定的事固化流程但很多人跟我一样容易把 Routine 做得越来越庞大。当你的 Routine 从新增一个接口膨胀到处理鉴权、日志、限流、灰度、监控、文档、CI你就不是在写流程模板而是在写一个微框架加项目管理规范加发布制度。这种 Routine 跑起来非常慢而且任何一处环境变化都会导致整个流程卡住。我的建议是Routine 只做 3-5 步核心操作其余交给其他工具或后续步骤。生成代码和部署上线完全可以分成两个 Routine不要合体修 bug和做安全审计也不要放一起。单一职责这个原则对程序是真理对 Routine 同样是真理。7.4 Agent 之间的暗箱依赖它以为你知道了其实根本没有这是我认为最隐蔽的坑Agent A 在输出文件里写了一句已将依赖升级到 v2但没有写进result.md的显式字段里Agent B 后续运行时代码调用了旧版本 API直接运行失败。表面上看是通信问题本质上是没有明确状态传递协议。解决起来不难给所有子 Agent 统一要求result.md里必须有## 变更一节列出所有对外可见的变更包含但不限于依赖版本、环境变量、文件变动。任何变更不写进这个章节都算没发生。有了这个协议暗箱依赖基本就绝迹了。老实说把多 Agent 编排、闭环自愈、Routine 这三套东西组合起来初期是要付出学习成本的设计流程模板、调试自愈边界、排查编排并发冲突每一步都在挑战原有的工作习惯。我个人的建议是别追求一步到位先用最小闭环跑通一个高频任务比如新增接口或者修单个 bug把流程跑顺了再逐步扩展。等你真正适应了这种搭流水线而不是当搬运工的开发方式再回头看那些单步聊天熬出来的长夜大概也会跟我一样觉得回不去了。