1. 从单步对话到任务闭环多 Agent 编排到底解决了什么问题1.1 单步聊天的天花板在哪里用 Claude Code 写过稍大一点项目的人大概都经历过同一个尴尬时刻你让它改一个跨三个文件的接口它改完第一个文件就停下来等你确认你回一句继续它再改第二个然后又开始等。一个本来十分钟能收尾的活硬是被拆成了七八轮对话中间还得你反复把上下文喂回去。这不是模型不行而是单步交互范式本身的限制——每一次往返都只推进一小步状态维护、任务拆解、结果校验全靠人脑兜底。单步聊天真正的瓶颈有三个。第一是上下文漂移聊到第五轮的时候前面第三轮定下的约束条件早就被稀释了模型开始自由发挥。第二是缺乏并行一个任务里明明有互不依赖的子任务比如同时改前端类型定义和后端序列化逻辑却只能串行做。第三是没有自检环节模型写完代码就交差对不对它自己也不知道得你跑一遍测试才发现问题。多 Agent 编排要解决的正是把人盯着模型一步步走变成模型自己组队把活干完。核心思路是把一个大任务拆成若干角色明确的子任务每个子任务交给一个独立的 Agent 上下文去执行再由一个协调层负责调度、汇总和校验。这跟人类团队干活的逻辑是一样的——你不会让一个人既写需求又写代码又做测试而是分工协作。1.2 多 Agent 编排的三种典型形态实际落地时多 Agent 编排并不是只有一种样子。根据任务复杂度和耦合度我把它归成三类你可以对照自己的场景选。形态结构适用场景典型开销主从式一个主 Agent 派发多个子 Agent 执行任务可清晰拆分为独立子块中等主 Agent 上下文压力大流水线式Agent 按阶段串联前一个输出是后一个输入有严格先后依赖的流程低但无法并行对等式多个 Agent 互相评审、交叉验证需要高质量校验的场景高但结果最稳主从式最常见也最好上手。你定义一个协调者角色它负责读需求、拆任务、分派给执行者角色执行者干完把结果回传协调者再决定下一步。这里的关键是子 Agent 必须拿到干净的上下文——不要把主对话的全部历史塞给它只给它这个子任务需要的信息否则上下文污染会立刻出现。流水线式适合那种必须先设计再实现再测试的链路。每个阶段的 Agent 只关心自己那一段输出格式约定好下一个 Agent 直接消费。好处是每个环节的提示词可以打磨得很精坏处是一旦中间某步出错整条链都得回退。对等式是我个人最推荐用于关键代码的形态。让两个 Agent 分别独立实现同一个功能然后互相 review 对方的产出分歧点就是风险点。虽然 token 消耗翻倍但抓 bug 的能力确实强尤其是那种看起来对但边界条件错了的问题。1.3 为什么这套东西现在才火多 Agent 编排的概念其实不新早几年就有各种 Agent 框架在讲。真正让它变得实用的是两件事一是模型本身的指令遵循能力上来了能稳定地按角色设定输出结构化结果二是 Claude Code 这类工具把文件读写、终端执行、代码检索这些能力做成了 Agent 可以直接调用的工具Agent 不再只是聊天而是能真正动手改代码、跑命令、看结果。换句话说以前的多 Agent 是一群只会说话的嘴现在的多 Agent 是一群有手有脚还能互相传话的人。这个差别是质变。你让一个 Agent 去跑测试它真的能执行npm test然后读输出根据失败信息决定要不要改代码——这个闭环一旦成立自动化就有了根基。2. 闭环自愈让 Agent 自己发现并修复问题2.1 什么是闭环自愈为什么它比多轮对话高级闭环自愈这个词听起来玄拆开看很朴素Agent 执行动作 → 观察结果 → 判断是否符合预期 → 不符合就调整 → 再执行这个循环能自己转起来不需要人每次都推一把。它和多轮对话的本质区别在于多轮对话的判断是人做的闭环自愈的判断是 Agent 自己做的。举个具体例子。你让 Agent 实现一个函数并通过单元测试。单步模式下它写完函数就停了你得手动跑测试、把报错贴回去、它再改。闭环模式下Agent 的流程是写函数 → 调用终端跑测试 → 读测试输出 → 发现断言失败 → 分析失败原因 → 修改函数 → 再跑测试 → 通过 → 报告完成。整个过程你只说了一句实现这个函数并通过测试。这个能力的技术底座是工具调用 结果解析 循环控制三件套。工具调用让它能动手结果解析让它能看懂自己动手的结果循环控制让它知道什么时候该停成功或达到最大轮次。2.2 自愈循环的四个关键控制点自愈循环不是无限转就好转不好会烧钱还会跑偏。我总结了四个必须设死的控制点。第一最大迭代次数。一定要设上限比如 10 轮。没有上限的循环遇到一个永远修不好的 bug会一直烧 token 到天亮。达到上限就退出并报告未能自动修复以下是尝试记录把决策权交回给人。第二成功判据要明确。测试通过是明确判据代码看起来没问题不是。判据越机械越好最好是能用一个命令的退出码或者一段可解析的输出表示。我习惯让 Agent 把判据写成断言比如pytest退出码为 0 且无 FAILED 字样。第三失败信息的结构化。Agent 要能区分编译错误测试失败超时权限问题这几类因为处理策略完全不同。编译错误直接看报错行测试失败要看断言差异超时可能要改算法复杂度。如果所有失败都当成一类处理自愈质量会很差。第四状态回滚机制。自愈过程中如果越改越乱要能回到上一个已知good状态。最简单的做法是每轮开始前用 git 打一个临时 commit改砸了就 reset 回去。这个习惯能救命我踩过太多次改着改着把原本能跑的部分也改坏了的坑。2.3 一个可复现的自愈循环提示词骨架下面这个骨架我用了很久改改就能套到大部分场景。核心是把观察-判断-行动三段式写清楚并且强制 Agent 在每轮输出结构化的状态。你是一个具备自愈能力的执行 Agent。你的目标是{目标描述} 可用工具文件读写、终端执行、代码检索。 执行规则 1. 每轮开始时先输出当前状态{ round: N, last_action: ..., last_result: ... } 2. 执行一个动作改代码 / 跑命令 / 查文件 3. 观察结果判断是否满足成功判据{成功判据} 4. 若满足输出 { status: done, summary: ... } 并结束 5. 若不满足分析原因输出 { status: retry, reason: ..., next_action: ... } 并进入下一轮 6. 最多执行 {N} 轮超过则输出 { status: give_up, attempts: [...] } 禁止事项 - 禁止在未观察结果的情况下连续执行多个动作 - 禁止修改与当前失败无关的文件 - 禁止跳过成功判据的验证直接宣布完成这个骨架的关键在于强制结构化输出。Agent 每轮必须吐一个 JSON这样协调层可以程序化地解析状态、决定是否继续、记录日志。如果让它自由发挥写自然语言你就没法自动化控制循环了。2.4 自愈的边界哪些问题不该交给它自愈不是万能的有些问题交给它只会浪费时间。我的经验是能通过局部修改解决的问题适合自愈需要重新设计的问题不适合。比如拼写错误、类型不匹配、边界条件漏判、导入路径错误这些自愈效率很高。但如果是架构选错了、需求理解偏了、依赖版本冲突导致的大面积失败自愈循环往往会在错误的方向上越走越远。判断标准很简单如果失败信息指向的是某个具体位置的具体错误交给自愈如果失败信息是整体行为不符合预期且没有明确错误点先人工介入理清方向再交给自愈执行。3. Routine 脚本化架构把重复劳动固化成可复用流程3.1 Routine 的本质是流程即代码用 Claude Code 久了你会发现很多任务是重复的每次新建一个模块都要建目录、写样板文件、配路由、加测试每次发版前都要跑 lint、跑测试、更新 changelog。这些事每次让 Agent 现想一遍既慢又不稳定。Routine 脚本化架构要做的就是把这些重复流程固化成声明式的脚本Agent 执行时不再思考怎么做而是按脚本执行。这跟传统编程里把重复逻辑抽成函数是一个道理只不过这里的函数是给 Agent 看的流程描述。一个 Routine 通常包含三部分触发条件什么时候跑、步骤序列按顺序做什么、校验规则怎么算成功。触发条件可以是手动命令也可以是某个事件比如检测到新文件。步骤序列是核心每一步要写清楚用什么工具、做什么、期望什么结果。校验规则决定这个 Routine 是成功还是失败。3.2 Routine 的三种粒度设计Routine 不是越细越好也不是越粗越好粒度选错了维护成本会爆炸。我一般按三种粒度来组织。原子 Routine最小可复用单元比如创建一个符合项目规范的 React 组件文件。它只做一件事输入是组件名和路径输出是创建好的文件。这种 Routine 数量多但稳定是整个体系的地基。组合 Routine把多个原子 Routine 串起来比如新建一个完整的功能模块内部依次调用建目录建组件建测试注册路由四个原子 Routine。组合 Routine 负责编排不关心每个原子内部怎么实现。场景 Routine面向具体业务场景的端到端流程比如发布一个新版本包含跑测试、构建、打 tag、更新文档等。这种 Routine 通常包含人工确认节点不能全自动。粒度复用范围维护成本典型数量原子全项目低多组合单项目中中场景单团队高少3.3 用脚本文件承载 Routine 的具体做法Claude Code 支持通过项目内的配置文件或者自定义命令来承载 Routine。我的做法是在项目根目录建一个.claude/routines/目录每个 Routine 一个 markdown 文件文件名就是 Routine 名。文件内容分三段frontmatter 写元信息正文写步骤末尾写校验。--- name: new-component description: 创建一个符合项目规范的 React 组件 args: - name: componentName required: true - name: dir default: src/components --- ## 步骤 1. 在 {dir} 下创建 {componentName}.tsx 2. 使用函数式组件 TypeScriptprops 用 interface 定义 3. 在同目录创建 {componentName}.test.tsx包含一个渲染测试 4. 在同目录创建 index.ts导出该组件 ## 校验 - 三个文件都存在 - 运行 npx tsc --noEmit 无类型错误 - 运行 npx vitest run {componentName} 测试通过这样定义之后你只需要说跑 new-component组件名是 UserCardAgent 就会按脚本执行不再每次重新理解符合项目规范是什么意思。规范被固化进了脚本稳定性大幅提升。3.4 Routine 与多 Agent、自愈的协同关系这三者不是并列的而是分层协作的。Routine 是做什么的声明多 Agent 是谁来做的分工自愈是做砸了怎么办的兜底。一个完整的执行链路是这样的用户触发一个场景 Routine → Routine 把任务拆给多个 Agent → 每个 Agent 执行自己的子任务 → 子任务内部如果失败触发自愈循环 → 自愈成功则继续失败则上报 → 所有子任务完成后Routine 的校验规则统一验证 → 通过则结束不通过则报告。这个分层的好处是每一层职责单一。Routine 层不关心 Agent 怎么实现Agent 层不关心整体流程自愈层不关心任务语义。改任何一层都不会牵动其他层维护起来清爽。4. 从零搭一套可用的编排环境安装、配置与实操4.1 安装 Claude Code 与基础环境准备先把工具装起来。Claude Code 目前主要通过 npm 分发Node 版本建议 18 以上20 LTS 最稳。macOS 和 Ubuntu 的安装命令基本一致。# 确认 node 版本 node -v # 建议 v20.x # 全局安装 npm install -g anthropic-ai/claude-code # 验证 claude --versionWindows 用户要注意早期版本对 64 位 Windows 的兼容性有过一些问题如果遇到安装报错优先检查 Node 是不是 64 位版本以及是否用了 WSL。我个人在 Windows 上的经验是直接用 WSL2 Ubuntu 环境比原生 Windows 少踩很多坑。安装完之后第一次运行claude会引导你完成账号配置。这里有个常见困惑注册账号和不注册有什么区别。简单说注册账号能用到官方的模型服务和额度管理不注册的话功能会受限。如果你打算接入第三方模型或者本地模型配置方式会不一样后面单独讲。4.2 VS Code 集成配置要点Claude Code 的 VS Code 插件是日常使用频率最高的入口。装完之后需要在设置里配几个关键项否则体验会很割裂。{ claude-code.autoStart: true, claude-code.terminalIntegration: true, claude-code.contextFiles: [.claude/CLAUDE.md], claude-code.maxIterations: 10 }terminalIntegration这个一定要开开了之后 Agent 才能直接执行终端命令并把输出读回来这是闭环自愈的前提。contextFiles指向项目级的说明文件Agent 每次启动会读它相当于给 Agent 一份项目背景。maxIterations就是前面说的自愈上限别设太大。项目根目录的CLAUDE.md是重中之重它决定了 Agent 对你项目的理解程度。我一般会写清楚项目技术栈、目录结构约定、代码风格、常用命令、禁止事项。这份文件写得好Agent 的输出质量能上一个台阶。4.3 接入第三方与本地模型的思路官方模型之外很多人想接入第三方 API 或者本地跑的模型。Claude Code 本身对模型接入有一定的开放性通过配置 base URL 和 API key 可以指向兼容的端点。本地模型的话LM Studio 这类工具可以起一个兼容 OpenAI 协议的本地服务然后把 Claude Code 指向http://localhost:端口。这里要提醒几点。第一本地模型的能力和官方模型差距明显复杂编排任务上容易掉链子建议只用于简单任务或者隐私敏感场景。第二接入第三方模型时工具调用function calling的支持程度参差不齐如果模型不支持结构化工具调用闭环自愈基本跑不起来。第三切换模型后一定要重新验证一遍 Routine 脚本不同模型对同一段提示词的理解可能差很多。提示切换模型后先跑一个最简单的原子 Routine 验证工具调用链路是否通再上复杂任务。直接上复杂任务排查成本很高。4.4 一个完整的多 Agent 编排实操案例光说概念没意思走一个真实案例。需求是给一个已有的 Express 项目加一个用户注册接口包含路由、控制器、数据校验、单元测试。第一步定义 Routine。在.claude/routines/add-endpoint.md里写清楚步骤和校验。第二步拆 Agent 角色。我拆三个architect负责读现有代码结构、确定文件放哪、定义接口签名implementer负责按签名写实现tester负责写测试并跑通。第三步编排执行。主 Agent 先调 architect拿到文件清单和接口定义然后把定义分别传给 implementer 和 tester这两个可以并行最后汇总跑一次全量测试。第四步自愈兜底。tester 跑测试如果失败进入自愈循环最多改 5 轮。5 轮还不过就上报附上每轮的失败信息。这个案例里architect 的输出是结构化的文件路径 函数签名implementer 和 tester 都消费这个结构所以它们之间不需要共享上下文各自干净。这就是多 Agent 编排比单步对话强的地方——并行 隔离。5. 踩坑实录多 Agent 编排中最容易翻车的几个点5.1 上下文污染子 Agent 拿到太多不该拿的信息这是最高频的坑。主 Agent 把整个对话历史一股脑塞给子 Agent子 Agent 看到一堆无关的讨论开始过度联想输出偏离任务。解决办法是子 Agent 只接收任务相关的结构化输入历史对话一律不传。如果子 Agent 确实需要项目背景通过CLAUDE.md这种静态文件提供而不是动态对话历史。我踩过一次特别典型的主 Agent 在讨论阶段提到这个功能以后可能要支持多语言结果子 Agent 在实现时自作主张加了一堆 i18n 的样板代码把简单任务搞复杂了。从那以后我定了个规矩——子 Agent 的输入里不允许出现以后可能将来这类词。5.2 循环失控自愈变成无限烧钱前面强调过最大迭代次数这里再补一个细节迭代次数要按任务类型分别设。简单任务 3 轮够了复杂任务可以给到 10 轮但绝不能不给。另外如果连续两轮的失败原因完全一样说明 Agent 卡住了应该立即退出而不是继续转。这个重复失败检测我一般加在循环控制里。if last_two_failures_are_identical: abort with stuck detected5.3 校验形同虚设成功判据写得太松代码看起来没问题这种判据等于没有。校验必须是可执行的、机械的。我见过有人把判据写成Agent 自己认为完成了结果 Agent 每次都认为完成了自愈循环一次都没触发过。判据要落到具体命令和具体输出上比如npm run build退出码为 0。5.4 常见问题速查表现象可能原因排查方向Agent 不执行终端命令terminalIntegration 未开检查 VS Code 配置自愈循环不触发成功判据太松或未定义检查 Routine 校验段子 Agent 输出跑偏上下文污染精简子 Agent 输入循环停不下来未设最大迭代补 maxIterations切换模型后行为异常工具调用不兼容验证 function calling 支持安装报错Node 版本或位数不对检查 node -v 和系统位数5.5 几个我压箱底的小技巧第一个给每个 Agent 起个明确的名字。别叫 agent1、agent2叫 architect、implementer、reviewer。名字本身就是角色约束模型看到名字会更稳定地扮演角色。第二个Routine 脚本要进版本控制。它和代码一样是资产改了要 review坏了要回滚。我见过团队把 Routine 写在个人笔记里换个人就抓瞎。第三个自愈日志一定要留。每次自愈循环的每轮输入输出都存下来出问题的时候这是唯一的线索。日志按 Routine 名 时间戳归档别嫌占地方。第四个先用小任务验证编排链路再上大任务。编排这东西链路本身出问题的概率比任务本身还高。先用一个改个变量名这种小任务把整条链路跑通再上真实需求。第五个别迷信全自动。关键节点该人工确认就确认尤其是涉及删除文件、改数据库、发版这类不可逆操作。全自动的诱惑很大但翻车成本更高。我的做法是 Routine 里显式标注需要人工确认的步骤Agent 执行到那里会停下来等。6. 编排架构的扩展方向与个人实践体会6.1 从单项目到跨项目的 Routine 复用当你在一个项目里把 Routine 体系跑顺之后自然会想复用到其他项目。我的做法是把通用 Routine 抽到一个独立的 git 仓库通过 submodule 或者软链接引入各个项目。项目特有的 Routine 留在项目内通用的走共享仓库。这样改一处所有项目受益。共享 Routine 的维护要注意版本兼容。不同项目的技术栈可能不同Routine 里要避免硬编码具体框架尽量用参数化。比如创建组件这个 Routine把文件扩展名、模板内容都做成参数就能同时适配 React 和 Vue 项目。6.2 编排层与 CI 的结合多 Agent 编排跑在本地是第一步跑在 CI 里才是真正的自动化。思路是把 Routine 的执行封装成一个 CLI 命令CI 里调用这个命令。比如 PR 提交时自动跑代码审查 Routine让 reviewer Agent 检查改动输出审查意见作为 PR 评论。这里要注意 CI 环境的限制没有交互式终端Agent 不能等人确认。所以 CI 里跑的 Routine 必须是全自动的所有需要确认的步骤要么去掉要么改成默认通过并记录。另外 CI 的 token 消耗要监控别让一个失控的循环把额度烧光。6.3 我个人在实际操作中的体会折腾这套东西大半年最大的体会是编排的价值不在于让 Agent 更聪明而在于让流程更稳定。模型能力是波动的今天表现好明天可能就抽风但一套设计良好的 Routine 自愈 校验体系能把这种波动的影响压到最低。你不再依赖这次模型状态好不好而是依赖流程设计得对不对。另一个体会是别一开始就追求大而全。我最初想搭一个覆盖所有场景的编排系统结果设计了两周还没跑起来。后来改成先做一个最小的原子 Routine跑通再加第二个慢慢长出来反而顺利得多。编排系统是长出来的不是设计出来的。最后一个人的判断永远在环里。Agent 再能自愈它也不知道这个需求其实不该这么做。编排系统负责把执行做扎实方向性的决策还是得人来。把 Agent 当成一个执行力很强但需要明确指令的团队成员而不是一个能替你做主的合伙人这个定位想清楚了很多纠结就没了。后续这套架构还能往几个方向扩一是接入更多的校验工具静态分析、安全扫描让自愈循环的判据更丰富二是做 Routine 的可视化编排让不写代码的同事也能组合流程三是把自愈日志做成可分析的指标看看哪类问题最常触发自愈反过来优化提示词和 Routine 设计。这些我还在摸索有进展再单独写。