Claude Code多Agent编排与闭环自愈架构实战

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-code

Ubuntu 上我用的是 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 秒再重试。这样做的原因是，有些失败是暂时性的（比如网络抖动），等一等再试可能就成功了。

整个闭环的流程是这样的：

1. 执行 Agent 执行任务
2. 验证器运行验收标准
3. 如果通过，流程结束
4. 如果不通过，反馈器整理错误信息
5. 重试控制器判断是否还有重试次数
6. 如果有，把错误信息传给执行 Agent，回到步骤 1
7. 如果没有，停止并通知人工介入

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 Routine，componentName 为 UserCard，props 为 name、avatar、onClick”，它就会自动按脚本执行。

Routine 脚本化的关键在于模板的维护。模板不是写一次就完了，随着项目规范的变化，模板也要更新。我一般会在每次代码审查之后，把新发现的规范补充到模板里，这样模板就越来越完善。

4. 完整实操流程：从零搭建一套多 Agent 编排系统

4.1 第一步：明确任务边界和验收标准

在动手配置之前，先要把任务想清楚。我一般会问自己三个问题：

• 这个任务涉及哪些模块？前端、后端、数据库、还是都有？
• 每个模块的验收标准是什么？是测试通过、还是接口返回正确、还是页面渲染正常？
• 哪些步骤是重复性的？能不能固化成 Routine？

把这三个问题回答清楚，后面的配置就有方向了。

4.2 第二步：设计 Agent 拆分方案

根据任务边界，设计 Agent 的拆分方案。我一般会画一个简单的表格来梳理：

这个表格看起来简单，但它能帮你把整个编排逻辑理清楚。我见过很多人一上来就写配置文件，写到一半发现 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 常见问题速查表

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 拆分和闭环自愈，感受一下效果，再逐步扩展到更复杂的场景。