1. 从单步对话到多 Agent 协作这套架构到底在解决什么问题如果你用过一段时间的 Claude Code大概率经历过这样的场景让它改一个 bug它改完你发现引入了新问题让它写个脚本它写完你手动跑一遍发现参数错了让它重构一个模块它改到一半上下文爆了前面的工作全白费。整个过程就像你带了一个实习生但这个实习生每次只干一件事干完就失忆你得反复把背景重新讲一遍。Claude Code 多 Agent 编排、闭环自愈与 Routine 脚本化架构本质上就是在解决这个“单步失忆”的问题。它的核心思路不复杂把一个大任务拆成多个有明确职责的 Agent让它们各自负责一块通过一个编排层来协调调度每个 Agent 执行完自己的步骤后系统自动验证结果如果不符合预期就触发修复流程形成闭环而那些重复性高、流程固定的操作则通过 Routine 脚本固化下来不用每次重新描述。这套东西适合谁如果你已经在用 Claude Code 做日常开发辅助但总觉得效率卡在“反复沟通”和“手动验证”这两个环节上那这套架构就是为你准备的。如果你还没开始用 Claude Code也没关系我会在讲架构的同时把安装配置、基础使用这些前置知识一并带过保证你能跟上。我自己的体验是单 Agent 模式下一个中等复杂度的重构任务我大概要来回对话 15 到 20 轮中间还得手动跑测试、手动检查 diff。切换到多 Agent 编排加闭环自愈之后同样的任务我只需要在开头把需求和验收标准描述清楚后面的执行、验证、修复基本自动完成我只需要在关键节点做一次确认。时间从原来的四十多分钟压缩到十分钟左右而且出错率明显下降。下面我会从架构设计思路开始拆然后讲核心细节和实操要点接着给出一套完整的落地流程最后把我踩过的坑和常见问题的排查方法整理出来。整个过程我会尽量用“我实际怎么做的”来展开而不是给你一堆理论。2. 架构设计思路为什么是“多 Agent 闭环 脚本化”这个组合2.1 单 Agent 模式的三个硬伤在讲多 Agent 编排之前得先搞清楚单 Agent 到底哪里不够用。我总结下来主要是三个问题。第一个是上下文窗口的硬限制。Claude Code 再强它的上下文也是有上限的。当你让它处理一个涉及十几个文件的重构任务时它读到后面就忘了前面改完 A 文件之后再去改 B 文件可能已经把 A 文件的改动逻辑忘掉了。这不是它笨是物理限制。第二个是缺乏验证环节。单 Agent 模式下Claude Code 执行完一个操作它默认这个操作是对的。但实际开发中改完代码要跑测试、要检查语法、要确认没有破坏其他模块。这些验证步骤在单 Agent 模式下全靠人来做而人一旦偷懒或者疏忽问题就留到了后面。第三个是重复劳动无法沉淀。每次让 Claude Code 做类似的事情比如“帮我写一个符合项目规范的 React 组件”你都得把项目规范、目录结构、命名约定重新讲一遍。这些信息本可以固化下来但单 Agent 模式下没有这个机制。2.2 多 Agent 编排的核心逻辑分而治之多 Agent 编排的思路其实很朴素既然一个 Agent 记不住那么多东西那就拆成多个 Agent每个 Agent 只负责一小块上下文压力自然就小了。具体怎么拆我常用的拆分维度有三种。按职责拆一个 Agent 负责写代码一个 Agent 负责审查代码一个 Agent 负责跑测试。写代码的 Agent 不需要知道测试怎么跑审查的 Agent 不需要知道代码怎么写的各司其职。按模块拆如果任务涉及多个独立模块比如前端和后端那就前端一个 Agent后端一个 Agent各自处理自己那一块最后通过接口约定来对接。按阶段拆一个任务分规划、执行、验证三个阶段每个阶段一个 Agent。规划 Agent 负责拆解任务、制定步骤执行 Agent 负责按步骤操作验证 Agent 负责检查结果是否符合预期。这三种拆分方式可以组合使用。比如我最近做的一个项目就是按“规划 Agent 前端执行 Agent 后端执行 Agent 验证 Agent”来编排的效果很好。2.3 闭环自愈让系统自己发现问题并修复闭环自愈这个词听起来有点玄其实逻辑很简单执行 → 验证 → 不通过则修复 → 再验证直到通过或者达到重试上限。关键在于“验证”这一步怎么做。我的做法是给每个 Agent 配一个明确的验收标准。比如写代码的 Agent验收标准是“代码能通过 ESLint 检查且单元测试全部通过”写脚本的 Agent验收标准是“脚本能正常运行且输出符合预期格式”。验证不通过的时候系统不是简单报错就完了而是把错误信息反馈给执行 Agent让它根据错误信息重新执行。这个过程可以循环多次直到通过为止。我一般设置最大重试次数为 3 次超过 3 次就停下来人工介入避免无限循环浪费资源。2.4 Routine 脚本化把重复操作变成可复用的“套路”Routine 脚本化的本质是把那些你反复让 Claude Code 做的事情写成固定的脚本或者配置文件。下次遇到同样的场景直接调用脚本不用重新描述。举个例子我团队里有一个规范所有新的 React 组件必须包含 PropTypes 定义、必须有对应的单元测试文件、必须导出为默认导出。以前每次让 Claude Code 写组件我都要把这三点重复一遍。后来我把它写成了一个 Routine 脚本脚本里定义了组件的模板、测试文件的模板、以及文件命名规则。现在只需要说“用组件 Routine 创建一个 UserCard 组件”Claude Code 就会自动按规范生成所有文件。Routine 脚本化的好处不只是省时间更重要的是保证一致性。人可能会忘但脚本不会。3. 核心细节解析与实操要点3.1 环境准备Claude Code 的安装与基础配置在讲多 Agent 编排之前得先把 Claude Code 跑起来。如果你已经装好了可以跳过这一节。Claude Code 目前支持 macOS、Linux 和 Windows通过 WSL。我主要用 macOS 和 Ubuntu所以以这两个为例。macOS 上的安装很简单官方提供了 Homebrew 安装方式brew install anthropic/tap/claude-codeUbuntu 上我用的是 npm 全局安装npm install -g anthropic-ai/claude-code安装完之后第一次运行claude命令会引导你完成登录和初始化配置。这里有一个点需要注意Claude Code 需要访问 Anthropic 的 API所以网络环境要能正常连通。如果你在公司内网或者网络受限的环境下使用可能需要配置代理具体方式参考官方文档的网络配置章节。VS Code 用户可以直接安装 Claude Code 的 VS Code 插件安装完之后在 VS Code 的设置里配置好 API Key 就能用。插件版的优势是能直接在编辑器里看到 Claude Code 的操作diff 对比也更直观。注意Claude Code 的订阅和 API 访问有地区限制如果你在安装或登录过程中遇到“not available in your country”之类的提示说明当前地区不支持需要确认你所在地区的支持情况。3.2 多 Agent 编排的配置文件怎么写Claude Code 的多 Agent 编排主要通过配置文件来定义。我一般会在项目根目录下创建一个.claude/agents/目录里面放各个 Agent 的定义文件。每个 Agent 的定义文件是一个 YAML 或者 JSON 文件包含以下几个关键字段name: frontend-executor description: 负责前端代码的编写和修改 model: claude-sonnet-4-20250514 system_prompt: | 你是一个前端开发专家负责根据任务描述编写 React 组件。 你必须遵循以下规范 1. 所有组件使用函数式组件 Hooks 2. 必须包含 PropTypes 定义 3. 必须导出为默认导出 4. 文件命名使用 PascalCase tools: - read_file - write_file - run_command acceptance_criteria: - eslint 检查通过 - 单元测试通过 max_retries: 3这里有几个关键点值得展开说。model 字段不同 Agent 可以用不同的模型。比如规划 Agent 可以用更强的模型如 Claude Sonnet执行 Agent 可以用更快的模型如 Claude Haiku这样在保证质量的同时控制成本。我实测下来规划用 Sonnet、执行用 Haiku 的组合成本能降低大概 40%效果差异不明显。system_prompt这是 Agent 的“人设”和“行为准则”。写得好不好直接决定 Agent 的输出质量。我的经验是system_prompt 里要包含三样东西角色定义、行为规范、输出格式要求。角色定义让 Agent 知道自己是谁行为规范告诉它什么能做、什么不能做输出格式要求保证它的输出能被后续环节解析。acceptance_criteria验收标准。这是闭环自愈的核心。验收标准要具体、可执行不能是“代码质量好”这种模糊描述而应该是“ESLint 无 error 级别问题”“单元测试覆盖率不低于 80%”这种可以自动检查的条件。max_retries最大重试次数。我一般设 3 次超过就停下来人工介入。设太多会浪费 token设太少可能错过一些本来能修好的问题。3.3 闭环自愈的实现机制闭环自愈的实现依赖于三个组件验证器、反馈器和重试控制器。验证器负责执行验收标准。比如验收标准是“单元测试通过”验证器就会运行npm test命令然后解析输出结果判断是否通过。反馈器负责把验证失败的信息整理成 Agent 能理解的格式。比如测试失败时反馈器会提取失败的测试用例名称、错误信息、堆栈跟踪然后把这些信息作为上下文传给执行 Agent。重试控制器负责管理重试次数和重试策略。我一般用的是“指数退避”策略第一次失败后立即重试第二次失败后等 5 秒再重试第三次失败后等 15 秒再重试。这样做的原因是有些失败是暂时性的比如网络抖动等一等再试可能就成功了。整个闭环的流程是这样的执行 Agent 执行任务验证器运行验收标准如果通过流程结束如果不通过反馈器整理错误信息重试控制器判断是否还有重试次数如果有把错误信息传给执行 Agent回到步骤 1如果没有停止并通知人工介入3.4 Routine 脚本化的具体写法Routine 脚本我一般放在.claude/routines/目录下每个脚本是一个 Markdown 文件里面包含脚本名称、适用场景、执行步骤和模板内容。举个例子一个创建 React 组件的 Routine 脚本长这样# Routine: create-react-component ## 适用场景 需要创建一个新的 React 函数式组件时使用。 ## 参数 - componentName: 组件名称PascalCase - props: 组件接收的 props 列表 ## 执行步骤 1. 在 src/components/ 目录下创建 {componentName}.jsx 文件 2. 在 src/components/__tests__/ 目录下创建 {componentName}.test.jsx 文件 3. 在 src/components/index.js 中添加导出语句 ## 组件模板 此处省略具体模板内容 ## 测试模板 此处省略具体模板内容使用的时候只需要在 Claude Code 里说“执行 create-react-component RoutinecomponentName 为 UserCardprops 为 name、avatar、onClick”它就会自动按脚本执行。Routine 脚本化的关键在于模板的维护。模板不是写一次就完了随着项目规范的变化模板也要更新。我一般会在每次代码审查之后把新发现的规范补充到模板里这样模板就越来越完善。4. 完整实操流程从零搭建一套多 Agent 编排系统4.1 第一步明确任务边界和验收标准在动手配置之前先要把任务想清楚。我一般会问自己三个问题这个任务涉及哪些模块前端、后端、数据库、还是都有每个模块的验收标准是什么是测试通过、还是接口返回正确、还是页面渲染正常哪些步骤是重复性的能不能固化成 Routine把这三个问题回答清楚后面的配置就有方向了。4.2 第二步设计 Agent 拆分方案根据任务边界设计 Agent 的拆分方案。我一般会画一个简单的表格来梳理Agent 名称职责输入输出验收标准planner任务拆解用户需求任务列表任务列表覆盖所有需求点frontend-executor前端代码编写任务列表中的前端任务前端代码文件ESLint 通过、单元测试通过backend-executor后端代码编写任务列表中的后端任务后端代码文件接口测试通过verifier整体验证所有代码文件验证报告端到端测试通过这个表格看起来简单但它能帮你把整个编排逻辑理清楚。我见过很多人一上来就写配置文件写到一半发现 Agent 之间的职责有重叠又得回头改浪费时间。4.3 第三步编写 Agent 配置文件按照前面说的格式为每个 Agent 编写配置文件。这里有一个技巧先写 system_prompt再写其他字段。因为 system_prompt 是 Agent 的核心其他字段都是围绕它来配置的。写 system_prompt 的时候我一般遵循“三段式”结构第一段定义角色“你是一个资深前端开发工程师擅长 React 和 TypeScript。”第二段定义行为规范“你必须遵循项目的代码规范包括但不限于使用函数式组件、使用 Hooks 管理状态、所有组件必须有 PropTypes 定义。”第三段定义输出格式“你的输出必须包含完整的文件内容不要省略任何部分。如果需要创建多个文件按文件路径分节输出。”4.4 第四步配置闭环自愈的验证器验证器的配置取决于你的项目技术栈。如果是 JavaScript 项目验证器一般是运行npm test和npm run lint如果是 Python 项目验证器一般是运行pytest和flake8。我一般会把验证命令写在一个 shell 脚本里然后在 Agent 配置文件中引用这个脚本#!/bin/bash # verify.sh set -e echo Running lint... npm run lint echo Running tests... npm test echo All checks passed!然后在 Agent 配置中acceptance_criteria: - command: ./verify.sh success_exit_code: 0这样做的好处是验证逻辑和 Agent 配置解耦修改验证逻辑不需要改 Agent 配置。4.5 第五步编写 Routine 脚本把重复性的操作整理成 Routine 脚本。我一般会从最常用的操作开始比如创建组件、创建 API 接口、创建数据库迁移文件等。写 Routine 脚本的时候有一个原则脚本要足够具体但不要过于具体。太具体了适用范围窄太宽泛了又起不到规范作用。我的经验是一个 Routine 脚本覆盖一类操作比如“创建 React 组件”是一个 Routine“创建带表单的 React 组件”是另一个 Routine。4.6 第六步联调测试和迭代优化配置写完之后不要直接上生产任务先用一个小任务来测试整个流程。我一般会用一个“创建一个简单的 Hello World 组件”这样的任务来测试。测试的时候重点关注三个地方Agent 之间的衔接是否顺畅规划 Agent 的输出能不能被执行 Agent 正确理解闭环自愈是否生效故意制造一个错误看系统能不能自动修复Routine 脚本是否按预期执行生成的代码是否符合规范发现问题就调整配置调整完再测直到整个流程跑通为止。5. 常见问题与排查技巧实录5.1 Agent 之间“沟通不畅”怎么办这是最常见的问题。表现是规划 Agent 输出的任务列表执行 Agent 理解不了或者理解偏了。根本原因通常是输出格式没有约定好。规划 Agent 输出的是一段自然语言描述执行 Agent 期望的是结构化的任务列表两者对不上。解决方法是在规划 Agent 的 system_prompt 里明确输出格式比如要求它输出 JSON 格式的任务列表{ tasks: [ { id: 1, type: frontend, description: 创建 UserCard 组件, files: [src/components/UserCard.jsx], acceptance: ESLint 通过单元测试通过 } ] }然后在执行 Agent 的 system_prompt 里说明它会接收这种格式的输入。这样两边就对齐了。5.2 闭环自愈陷入无限循环怎么破理论上设置了 max_retries 就不会无限循环但实际中我遇到过一种情况Agent 每次重试都犯同样的错误导致重试次数用完了问题还在。这种时候需要分析根因。我遇到过的原因主要有两个一是验收标准太模糊Agent 不知道具体要改成什么样二是错误信息没有正确传递给 Agent它不知道上次为什么失败。解决方法是第一把验收标准写得更具体比如把“测试通过”改成“UserCard.test.jsx 中的所有测试用例通过”第二检查反馈器的输出确保错误信息完整传递给了 Agent。5.3 Routine 脚本执行结果不符合预期Routine 脚本执行出问题通常是模板本身有问题或者参数传递有问题。我的排查步骤是这样的先手动执行一次 Routine 脚本对应的操作确认模板本身是对的然后检查参数传递看参数名和模板中的占位符是否匹配最后检查 Agent 的 system_prompt看它是否正确理解了 Routine 的执行逻辑。5.4 常见问题速查表问题现象可能原因排查方法解决方案Agent 输出格式不对system_prompt 缺少格式约束检查 system_prompt 是否有输出格式说明补充输出格式要求闭环自愈不触发验收标准配置错误手动运行验证命令看是否正常修正验收标准配置重试次数用完了问题还在验收标准太模糊或错误信息未传递检查验收标准具体性和反馈器输出细化验收标准完善反馈信息Routine 脚本执行失败模板错误或参数不匹配手动执行对应操作检查参数修正模板或参数Agent 之间职责重叠拆分方案设计不合理检查各 Agent 的职责描述重新设计拆分方案整体流程跑不通配置文件之间有冲突逐个检查配置文件修正冲突配置5.5 我踩过的三个坑第一个坑Agent 拆得太细。一开始我觉得拆得越细越好结果拆了十几个 Agent每个 Agent 只负责很小一块导致 Agent 之间的协调成本比任务本身还高。后来我调整了策略一般控制在 4 到 6 个 Agent 之间每个 Agent 的职责有足够的覆盖面。第二个坑验收标准写得太理想化。我一开始把验收标准写成“代码质量优秀”结果 Agent 根本不知道什么叫“优秀”。后来改成具体的、可量化的标准比如“ESLint 无 error”“测试覆盖率不低于 80%”效果就好多了。第三个坑Routine 脚本写得太死。我一开始把 Routine 脚本写得很死参数很少结果适用范围很窄。后来我增加了参数化程度比如组件模板里把组件名、props、样式方案都做成参数适用范围就广多了。6. 进阶技巧让这套架构跑得更顺6.1 Agent 之间的上下文传递优化多 Agent 编排中Agent 之间的上下文传递是一个容易被忽视但很关键的环节。如果传递的信息太多会浪费 token传递的信息太少接收方又理解不了。我的做法是只传递必要信息。具体来说规划 Agent 传递给执行 Agent 的信息包括任务描述、相关文件路径、验收标准。不传递的信息包括规划过程中的思考过程、被否决的方案、历史对话记录。这样做的好处是执行 Agent 的上下文窗口不会被无关信息占满能更专注于当前任务。6.2 用条件分支处理不同场景有些任务不是线性的需要根据情况走不同的分支。比如“如果前端测试通过就继续后端否则先修复前端”。Claude Code 的编排配置支持条件分支我一般用 YAML 的when字段来实现steps: - name: frontend agent: frontend-executor next: check-frontend - name: check-frontend type: condition condition: {{ frontend.status }} success true_next: backend false_next: fix-frontend - name: fix-frontend agent: frontend-executor next: check-frontend这样就能实现“前端通过才继续不通过就修复”的逻辑。6.3 监控和日志知道系统在干什么多 Agent 编排系统跑起来之后你需要知道它每一步在干什么。我一般会开启 Claude Code 的详细日志模式把每个 Agent 的输入、输出、执行时间都记录下来。日志的用途有两个一是排查问题出问题的时候能快速定位是哪个 Agent 哪一步出了错二是优化性能通过分析日志能发现哪些步骤耗时最长然后针对性优化。我一般会把日志输出到一个文件里然后用简单的脚本做分析。比如统计每个 Agent 的平均执行时间、成功率、重试次数等。6.4 成本控制别让 token 烧得太快多 Agent 编排的一个副作用是 token 消耗会增加因为多个 Agent 各自有上下文而且闭环自愈会触发重试。控制成本的方法有几个一是用不同级别的模型规划用强模型执行用快模型二是优化 system_prompt去掉不必要的描述三是设置合理的 max_retries避免无效重试四是定期清理不再使用的 Agent 配置和 Routine 脚本。我实测下来优化之后成本能控制在单 Agent 模式的 1.5 倍左右但效率提升是 3 到 4 倍整体性价比还是很高的。6.5 团队协作让 Routine 脚本成为团队资产Routine 脚本最大的价值在于团队共享。一个人写好的 Routine全团队都能用而且能保证所有人产出的代码风格一致。我一般会把 Routine 脚本放在项目的.claude/routines/目录下和代码一起做版本管理。每次代码审查发现新的规范就更新对应的 Routine 脚本。这样 Routine 脚本就成了团队规范的“活文档”比写在 Wiki 里的规范更有效因为它能被自动执行。新成员加入的时候只需要让他熟悉 Routine 脚本就能快速上手项目的开发规范省去了大量的口头传授时间。这套架构我用了大概三个月从最初的单 Agent 手动操作到现在多 Agent 自动编排中间经历了不少调整。最大的感受是工具的价值不在于它有多强而在于你怎么用它。Claude Code 本身的能力已经很强了但只有把它组织成一个有结构、有反馈、有沉淀的系统才能真正把效率提上来。如果你也在用 Claude Code建议从一个小任务开始先试试多 Agent 拆分和闭环自愈感受一下效果再逐步扩展到更复杂的场景。