1. 从单步对话到多 Agent 协作为什么单线程聊天模式正在被淘汰用 Claude Code 写代码的人大概都经历过这样一个阶段打开终端敲一句需求等它回一段代码复制粘贴发现不对再补一句这里报错了它改一版再跑再错。一轮一轮下来半小时过去了真正写出来的有效代码可能不到五十行。这不是模型能力的问题而是交互范式的问题——你把一个能并行处理任务的系统当成了一个只会一问一答的聊天框。单步聊天模式的根本瓶颈在于上下文窗口的线性消耗和任务状态的不可持久化。每多一轮对话历史消息就多占一份 token等到十几轮之后模型开始忘事前面定好的接口约定、目录结构、命名规范全被稀释掉了。更麻烦的是一旦你关掉终端整个任务的中间状态就没了下次得从头描述一遍背景。对于那种改一个功能要动五个文件的真实工程任务这种模式基本没法用。多 Agent 编排解决的正是这个问题。它的核心思路是把一个复杂任务拆成若干职责单一的子任务每个子任务交给一个独立的 Agent 实例去跑Agent 之间通过结构化的消息而不是自然语言闲聊传递结果。比如一个典型的前后端联调任务可以拆成接口定义 Agent、后端实现 Agent、前端调用 Agent、测试验证 Agent。四个 Agent 各自持有自己的上下文互不污染最后由编排层汇总。这里有个很多人忽略的点多 Agent 不等于多开几个终端。真正的编排需要解决三件事——任务分解策略、Agent 间的依赖调度、以及失败后的重试与回滚。如果只是手动开四个窗口各干各的那只是并行聊天不是编排。编排的本质是有一个**调度器Orchestrator**在中间做决策谁先跑、谁等谁、谁失败了要重来、结果怎么合并。闭环自愈则是这套体系里最值钱的部分。所谓闭环指的是 Agent 执行完一个动作后能自己拿到可验证的反馈编译是否通过、测试是否绿、lint 是否报错然后根据反馈决定下一步是继续、修正还是放弃。没有闭环的 Agent 就是个盲写代码的实习生写完就交差对不对不管。有了闭环它才像个会自己跑测试的工程师。Routine 脚本化架构是把上面这些能力固化下来的手段。你把常用的任务模式写成可复用的脚本——比如新建一个 CRUD 模块、给现有函数补单元测试、批量重命名并更新引用——每次触发时传入不同参数即可。这样做的价值在于把一次性的聪明变成可重复的流程降低对临场提示词质量的依赖。这套东西适合谁如果你只是偶尔让 AI 帮你写个正则、改个报错那单步聊天足够了。但如果你在维护一个有几十上百个文件的项目需要频繁做重构、补测试、迁移框架那多 Agent 编排带来的效率提升是数量级的。下面我会把这套架构拆开从任务分解讲到自愈机制再讲到 Routine 脚本怎么写尽量给到能直接抄的细节。2. 多 Agent 编排的骨架任务分解、角色划分与调度策略2.1 任务分解的粒度控制拆太细和拆太粗都是坑多 Agent 编排的第一步是任务分解而分解粒度直接决定了整套系统的成败。我踩过的坑是一开始拆得太细把一个实现用户登录拆成了写 User 模型写密码哈希函数写 JWT 生成写登录路由写参数校验五个 Agent结果五个 Agent 之间要传递大量中间产物光是协调开销就超过了任务本身的工作量。后来我总结出一个经验法则单个 Agent 的任务应该对应一个可独立验证的交付物。什么叫可独立验证就是这个 Agent 干完活之后你能用一个明确的命令判断它对不对。比如实现登录接口这个任务验证方式就是curl一下看返回是否符合预期。而写密码哈希函数这种虽然也能测但它太碎单独跑一个 Agent 不划算。合理的粒度大概是这样的任务类型推荐粒度验证方式新增功能模块一个完整接口/页面端到端测试或手动调用代码重构一个类/一组相关函数原有测试是否仍通过补测试一个文件的所有导出函数覆盖率报告依赖升级一个依赖及其所有调用点编译 全量测试文档生成一个模块人工抽查 链接检查拆得太粗的问题则是 Agent 上下文爆炸。一个 Agent 如果被要求重构整个项目它会在读取文件的过程中迅速耗尽上下文然后开始胡编。所以粒度控制的核心是让每个 Agent 的输入输出都能装进一个舒适的上下文窗口通常建议单个 Agent 处理的文件数不超过 10 个代码行数控制在 2000 行以内。2.2 角色划分不是每个 Agent 都要会写代码很多人做多 Agent 时习惯让所有 Agent 都是全能程序员这其实浪费了编排的价值。更有效的做法是按能力维度划分角色让每个 Agent 只擅长一件事。我常用的角色配置有这么几类Planner规划者只负责读需求、读现有代码结构输出一份任务清单和依赖关系。它不写代码所以上下文可以专注于理解而非生成。Coder实现者拿到 Planner 给的具体子任务专注写代码。它的输入被严格限定不需要知道全局。Reviewer审查者对 Coder 的产出做静态检查找逻辑漏洞、边界条件、命名问题。它和 Coder 用不同的提示词避免自己审自己的盲区。Tester验证者跑测试、跑编译、跑 lint把结果结构化返回。它是闭环的关键执行者。Fixer修复者专门处理 Tester 报回来的失败做最小化修改。这套角色划分的好处是每个 Agent 的提示词可以高度特化。Planner 的提示词里全是分析、拆解、排序Coder 的提示词里全是实现、遵循规范、不要引入新依赖Reviewer 的提示词里全是找问题、质疑、给反例。特化之后每个 Agent 的输出质量都比全能 Agent高一大截。2.3 调度策略串行、并行与条件分支怎么选调度层要回答的核心问题是这些 Agent 按什么顺序跑我实践下来有三种基本模式对应不同场景。串行链适合有强依赖的任务。比如先定义接口再实现后端再实现前端每一步都依赖前一步的产出只能排队。串行的缺点是慢但胜在状态清晰出问题容易定位。并行扇出适合无依赖的子任务。比如给这 8 个工具函数各补一组测试8 个任务互不干扰可以同时开 8 个 Agent。并行能大幅压缩总耗时但要注意资源竞争——如果多个 Agent 同时改同一个文件就会冲突。解决办法是让并行任务操作不同的文件或者用文件锁。条件分支适合需要根据中间结果决策的场景。比如 Tester 跑完测试后如果全绿就走合并分支如果有失败就走修复分支修复完再回到 Tester。这就是闭环自愈的调度基础。实际项目里这三种模式往往是嵌套的。一个典型的重构任务可能是Planner 串行产出计划 → 多个 Coder 并行实现 → Tester 串行验证 → 失败则 Fixer 条件触发 → 回到 Tester。调度器需要能表达这种嵌套结构通常用一个 DAG有向无环图来描述节点是 Agent 任务边是依赖关系。提示调度器一定要有超时和最大重试次数。我见过 Agent 陷入修复-失败-再修复的死循环一晚上烧掉大量额度。给每个任务设一个重试上限比如 3 次超过就标记为需人工介入别让它无限跑。3. 闭环自愈机制让 Agent 自己发现错误并修正3.1 闭环的三个必要条件可观测、可判定、可回滚闭环自愈听起来很玄但拆开看就是三个条件必须同时满足缺一个都闭不起来。可观测指的是 Agent 的每个动作都要产生可被程序读取的输出。写代码这个动作本身不产生反馈但写完代码后跑一次编译就产生了。所以闭环的第一步是给每个动作绑定一个验证命令。比如 Coder 写完一个 Python 文件紧接着跑python -m py_compile和pytest把 stdout/stderr 捕获下来。可判定指的是反馈结果要能被程序判断成败而不是靠人看。编译退出码是 0 还是非 0测试是 passed 还是 failedlint 是 clean 还是有 warning这些都是可判定的。最怕的是那种看起来好像对的模糊反馈比如让 Agent 自己说我觉得没问题这不算闭环。可回滚指的是失败后能回到一个已知良好的状态。如果 Agent 改坏了代码又没法撤销那闭环就变成了越修越坏。所以每次 Agent 动手前要么用 git 打一个临时 commit要么把原文件备份确保修复失败时能退回去。这三个条件里可判定是最容易被忽视的。很多团队的验证命令输出一大堆日志但没有明确的成功/失败标志Agent 拿到之后不知道该怎么办。解决办法是给验证命令包一层让它只输出结构化的结果比如{status: fail, errors: [...]}。3.2 失败分类哪些错误该自动修哪些该直接放弃不是所有错误都值得自动修复。我踩过的坑是让 Agent 无脑重试所有失败结果遇到依赖包版本冲突这种需要人决策的问题时它反复改代码越改越乱。后来我给失败做了分类错误类型典型表现处理策略语法/类型错误编译不过、类型不匹配自动修复重试上限 3 次测试断言失败逻辑不符合预期自动修复但需 Reviewer 复核依赖/环境问题包找不到、版本冲突直接放弃报告人工权限/网络问题无法写入、超时直接放弃报告人工需求理解偏差实现的功能和描述不符回到 Planner 重新规划这个分类的关键在于区分代码问题和环境问题。代码问题 Agent 有能力自己修环境问题它修不了硬修只会浪费时间。判断方法很简单看错误信息里有没有出现代码之外的关键词比如包名、路径、权限、网络。3.3 修复循环的收敛控制怎么避免无限重试即使只让 Agent 修代码问题也可能陷入死循环。比如一个测试断言失败Agent 改了实现结果另一个测试挂了它再改第一个又挂了。这种按下葫芦浮起瓢的情况靠单纯重试是解决不了的。我的做法是引入收敛判据每次修复后记录通过的测试数和失败的错误类型。如果连续两次修复后通过数没有增加或者错误类型在反复横跳就判定为未收敛停止自动修复转人工。这个判据用代码实现很简单def should_continue(history): if len(history) 2: return True last, prev history[-1], history[-2] # 通过数没增加且错误类型重复出现判定不收敛 if last.passed prev.passed and last.error_type in [h.error_type for h in history[-3:-1]]: return False return len(history) MAX_RETRY除了收敛判据还有一个技巧是限制单次修复的改动范围。让 Fixer 只改和错误直接相关的文件不要顺手重构别的代码。改动范围越小引入新问题的概率越低收敛越快。3.4 一个真实的闭环案例批量修复 lint 错误我拿一个真实场景走一遍闭环。需求是把项目里所有 ESLint 报错清掉。这个任务看起来简单但项目有 200 多个文件报错上千条手动改要命。第一步Planner 跑eslint . --format json把报错按文件分组输出一个任务清单。第二步调度器为每个文件开一个 Coder Agent并行处理。第三步每个 Coder 改完后Tester 单独对这个文件跑eslint file捕获结果。第四步如果还有报错Fixer 介入只改这个文件。第五步全部文件通过后跑一次全量eslint .做最终验证。这个案例里闭环体现在每个文件改完立即验证而不是全部改完再验证。前者能快速定位是哪个文件、哪条规则没处理好后者一旦失败就得大海捞针。实测下来200 个文件的任务用闭环方式跑成功率比一把梭高出很多而且失败的文件能精确定位。注意并行跑 lint 修复时要确保每个 Agent 只碰自己的文件。如果两个 Agent 同时改一个文件git 会冲突。调度器在分配任务时要做文件级去重。4. Routine 脚本化把一次性编排固化成可复用流程4.1 Routine 的本质参数化的任务模板Routine 这个词容易让人想到定时任务但在 Claude Code 的语境里它更像是参数化的任务模板。你把一套验证过的 Agent 编排流程写成一个脚本脚本里留出几个参数位每次调用时填入不同的值就能复用到相似的任务上。举个具体的例子。新增一个 REST 接口这个任务几乎每个后端项目都会反复做。它的流程是固定的定义路由 → 写 controller → 写 service → 写数据访问 → 写测试 → 跑验证。变的只是接口名、路径、字段。把这个流程写成 Routine参数就是{resource_name}、{path}、{fields}下次新增接口时一行命令就能触发整套编排。Routine 的价值在于把提示词工程的经验沉淀下来。你第一次做某类任务时可能调了半天提示词才让 Agent 输出满意结果。如果不固化下次还得重调。固化之后这套提示词就成了团队资产谁来跑都一样。4.2 Routine 脚本的结构声明、参数、步骤、断言一个可用的 Routine 脚本我通常写成四段结构。声明段描述这个 Routine 是干什么的、适用什么场景、有什么前置条件。这段是给人看的方便团队里其他人知道什么时候该用它。参数段定义输入。参数要尽量少而明确每个参数都要有类型和默认值。比如resource_name是字符串必填with_auth是布尔默认 true。参数太多说明这个 Routine 承担了太多职责该拆了。步骤段是核心描述 Agent 的编排。每一步要写清楚用哪个角色的 Agent、输入是什么、输出传给谁、验证命令是什么。步骤之间用依赖关系连接形成 DAG。断言段定义什么算成功。这是 Routine 和普通脚本最大的区别——它不只是执行还要自检。断言可以是所有测试通过、lint 无 error、生成的接口能被 curl 通。下面是一个简化版的 Routine 结构示意用 YAML 描述实际可以用任何你顺手的格式name: add-rest-endpoint description: 为现有项目新增一个 REST 接口 params: resource_name: { type: string, required: true } path: { type: string, required: true } fields: { type: list, required: true } with_auth: { type: bool, default: true } steps: - id: plan agent: planner input: 为 ${resource_name} 设计接口路径 ${path}字段 ${fields} - id: implement agent: coder depends_on: [plan] input: ${plan.output} - id: test agent: tester depends_on: [implement] command: pytest tests/test_${resource_name}.py assertions: - test.status passed - lint.errors 04.3 参数设计怎么让 Routine 既通用又不失控Routine 最容易犯的错是参数设计过度。我见过有人把 Routine 的参数做到二十几个结果每次调用都要查文档填半天还不如手动做。参数设计的核心原则是只暴露真正会变的东西其余全部写死。怎么判断什么是真正会变的看这个值在不同调用之间是否经常不同。比如接口路径经常变是参数代码风格用 4 空格缩进基本不变写死。如果一个参数 90% 的调用都用同一个值那它就不该是参数应该做成默认配置。另一个技巧是用枚举代替自由文本。比如认证方式这个参数与其让用户填字符串不如限定为none、jwt、session三个选项。枚举能防止用户填出 Agent 不认识的词减少出错。4.4 Routine 的版本管理与回归测试Routine 一旦被团队用起来就变成了基础设施改它要谨慎。我给 Routine 加了版本号每次修改都递增并且保留旧版本。这样即使新版本有问题也能快速回退。更重要的是给 Routine 写回归测试。做法是准备几个标准输入每次改完 Routine 后用这些输入跑一遍看输出是否符合预期。标准输入要覆盖典型场景和边界场景比如字段为空、路径带特殊字符、认证关闭。回归测试的断言不用太细抓住关键点就行生成的文件是否存在、测试是否通过、接口是否可调用。太细的断言会导致 Routine 稍微调整就测试失败维护成本反而高。提示Routine 的回归测试最好在隔离环境跑别在真实项目上跑。我吃过亏一次测试把生产配置给改了。用临时目录或容器隔离跑完就销毁。5. 落地这套架构时最容易翻车的几个地方5.1 上下文污染Agent 之间传递了什么多 Agent 系统里Agent 之间的消息传递是最容易出问题的地方。我见过最典型的翻车是Coder 把整个文件内容传给 ReviewerReviewer 又把整个文件加上自己的评论传回 Coder来回几次上下文里全是重复的代码真正有用的信息被淹没。正确的做法是传递结构化摘要而不是原始内容。Coder 传给 Reviewer 的应该是我改了哪几个文件、每个文件的 diff、我的实现思路而不是整个文件。Reviewer 传回的应该是发现的问题列表、每个问题的位置和建议而不是把代码再抄一遍。这个原则可以总结成一句话Agent 之间传的是结论和引用不是全文。文件内容放在磁盘上消息里只放路径和行号需要的时候各自去读。这样上下文占用小而且不会因为版本不一致产生混乱。5.2 状态管理任务进度存在哪单步聊天没有状态管理的问题因为状态就在对话历史里。多 Agent 一旦并行状态管理就成了必须解决的问题。我一开始用内存里的字典存任务状态结果进程一重启全丢了正在跑的任务全废。后来改成文件系统 简单数据库的方案。每个任务在磁盘上有一个目录目录里放任务元数据JSON、每个 Agent 的输入输出、验证结果。这样即使进程重启也能从磁盘恢复状态继续跑没完成的部分。状态管理还要考虑并发写入。多个 Agent 同时更新任务状态时要用文件锁或者数据库事务避免写冲突。我用的方案是每个 Agent 写自己的子目录汇总时由调度器统一读避免并发写同一个文件。5.3 成本控制别让 Agent 无限烧额度多 Agent 编排的 token 消耗是单步聊天的好几倍因为每个 Agent 都要读上下文、生成输出还有 Agent 之间的消息传递。如果不加控制一个复杂任务跑下来成本可能超出预期。控制成本的手段有几个。一是限制每个 Agent 的上下文大小超过就截断或摘要。二是设置任务总预算比如一个任务最多消耗多少 token超了就停。三是复用 Agent 实例相似的任务用同一个 Agent 跑避免重复初始化。四是缓存验证结果同一个文件的 lint 结果在没改动的情况下不用重跑。我实测下来加了预算控制之后成本能降下来不少而且因为避免了无意义的反复重试任务成功率反而提高了。5.4 人工介入的时机什么时候该叫停再好的闭环自愈也有搞不定的情况。关键是知道什么时候该叫停把控制权交回给人。我设了几个触发人工介入的条件重试超过上限、错误类型是环境问题、任务耗时超过预期、Agent 的输出和需求明显不符。人工介入不是失败而是这套系统的正常组成部分。把 Agent 能干的活交给它把需要判断的活留给人这才是合理的分工。我见过有人追求全自动结果 Agent 在错误的方向上狂奔最后返工的成本比一开始就人工介入还高。注意人工介入时要把 Agent 的完整执行历史呈现出来包括它做了什么、为什么这么做、卡在哪。这样人接手时不用从头查能快速定位问题。6. 我在这套架构上踩过的坑和总结出的几条经验先说一个最反直觉的体会多 Agent 编排的难点不在 Agent而在编排。很多人把精力花在调每个 Agent 的提示词上结果 Agent 单个表现都不错但组合起来就乱套。真正决定成败的是调度逻辑、状态管理、错误处理这些胶水部分。我后来把大部分时间花在写调度器和验证框架上Agent 的提示词反而改得少了。第二个体会是验证命令的质量决定闭环的上限。如果验证命令只能告诉你失败了Agent 就不知道往哪修。如果验证命令能精确到第 42 行第 3 列的类型不匹配Agent 修起来就有的放矢。所以我在项目里会专门花时间打磨验证命令让它输出尽可能精确的错误定位。这个投入的回报非常高。第三个是Routine 要从小处开始。别一上来就想做一个全自动开发的大 Routine先从一个具体的小任务做起比如给指定文件补测试跑通了再扩展。小 Routine 容易验证、容易调试积累几个之后再组合成大流程。第四个是给 Agent 的输出加约束。自由文本输出看起来灵活但下游解析起来痛苦。我后来要求所有 Agent 的关键输出都用结构化格式JSON 或 YAML这样调度器能可靠地解析不用做模糊匹配。结构化输出还能顺便做 schema 校验提前发现 Agent 输出格式错误。最后一个经验是关于日志。多 Agent 系统出问题时没有详细日志根本没法排查。我在每个 Agent 的每次调用前后都记日志包括输入、输出、耗时、token 消耗、验证结果。日志按任务 ID 组织出问题时能完整回放整个执行过程。这套日志后来还帮我做了成本分析发现哪些环节最烧钱针对性优化。这套架构不是银弹它适合的是重复性高、验证明确、单任务规模适中的场景。如果你的任务每次都不一样或者验证标准很模糊那多 Agent 编排带来的复杂度可能超过收益。判断标准很简单如果你发现自己在反复做同一类任务而且每次都能明确判断做没做对那就值得把它 Routine 化。
1. 从单步对话到多 Agent 协作为什么单线程聊天模式正在被淘汰用 Claude Code 写代码的人大概都经历过这样一个阶段打开终端敲一句需求等它回一段代码复制粘贴发现不对再补一句这里报错了它改一版再跑再错。一轮一轮下来半小时过去了真正写出来的有效代码可能不到五十行。这不是模型能力的问题而是交互范式的问题——你把一个能并行处理任务的系统当成了一个只会一问一答的聊天框。单步聊天模式的根本瓶颈在于上下文窗口的线性消耗和任务状态的不可持久化。每多一轮对话历史消息就多占一份 token等到十几轮之后模型开始忘事前面定好的接口约定、目录结构、命名规范全被稀释掉了。更麻烦的是一旦你关掉终端整个任务的中间状态就没了下次得从头描述一遍背景。对于那种改一个功能要动五个文件的真实工程任务这种模式基本没法用。多 Agent 编排解决的正是这个问题。它的核心思路是把一个复杂任务拆成若干职责单一的子任务每个子任务交给一个独立的 Agent 实例去跑Agent 之间通过结构化的消息而不是自然语言闲聊传递结果。比如一个典型的前后端联调任务可以拆成接口定义 Agent、后端实现 Agent、前端调用 Agent、测试验证 Agent。四个 Agent 各自持有自己的上下文互不污染最后由编排层汇总。这里有个很多人忽略的点多 Agent 不等于多开几个终端。真正的编排需要解决三件事——任务分解策略、Agent 间的依赖调度、以及失败后的重试与回滚。如果只是手动开四个窗口各干各的那只是并行聊天不是编排。编排的本质是有一个**调度器Orchestrator**在中间做决策谁先跑、谁等谁、谁失败了要重来、结果怎么合并。闭环自愈则是这套体系里最值钱的部分。所谓闭环指的是 Agent 执行完一个动作后能自己拿到可验证的反馈编译是否通过、测试是否绿、lint 是否报错然后根据反馈决定下一步是继续、修正还是放弃。没有闭环的 Agent 就是个盲写代码的实习生写完就交差对不对不管。有了闭环它才像个会自己跑测试的工程师。Routine 脚本化架构是把上面这些能力固化下来的手段。你把常用的任务模式写成可复用的脚本——比如新建一个 CRUD 模块、给现有函数补单元测试、批量重命名并更新引用——每次触发时传入不同参数即可。这样做的价值在于把一次性的聪明变成可重复的流程降低对临场提示词质量的依赖。这套东西适合谁如果你只是偶尔让 AI 帮你写个正则、改个报错那单步聊天足够了。但如果你在维护一个有几十上百个文件的项目需要频繁做重构、补测试、迁移框架那多 Agent 编排带来的效率提升是数量级的。下面我会把这套架构拆开从任务分解讲到自愈机制再讲到 Routine 脚本怎么写尽量给到能直接抄的细节。2. 多 Agent 编排的骨架任务分解、角色划分与调度策略2.1 任务分解的粒度控制拆太细和拆太粗都是坑多 Agent 编排的第一步是任务分解而分解粒度直接决定了整套系统的成败。我踩过的坑是一开始拆得太细把一个实现用户登录拆成了写 User 模型写密码哈希函数写 JWT 生成写登录路由写参数校验五个 Agent结果五个 Agent 之间要传递大量中间产物光是协调开销就超过了任务本身的工作量。后来我总结出一个经验法则单个 Agent 的任务应该对应一个可独立验证的交付物。什么叫可独立验证就是这个 Agent 干完活之后你能用一个明确的命令判断它对不对。比如实现登录接口这个任务验证方式就是curl一下看返回是否符合预期。而写密码哈希函数这种虽然也能测但它太碎单独跑一个 Agent 不划算。合理的粒度大概是这样的任务类型推荐粒度验证方式新增功能模块一个完整接口/页面端到端测试或手动调用代码重构一个类/一组相关函数原有测试是否仍通过补测试一个文件的所有导出函数覆盖率报告依赖升级一个依赖及其所有调用点编译 全量测试文档生成一个模块人工抽查 链接检查拆得太粗的问题则是 Agent 上下文爆炸。一个 Agent 如果被要求重构整个项目它会在读取文件的过程中迅速耗尽上下文然后开始胡编。所以粒度控制的核心是让每个 Agent 的输入输出都能装进一个舒适的上下文窗口通常建议单个 Agent 处理的文件数不超过 10 个代码行数控制在 2000 行以内。2.2 角色划分不是每个 Agent 都要会写代码很多人做多 Agent 时习惯让所有 Agent 都是全能程序员这其实浪费了编排的价值。更有效的做法是按能力维度划分角色让每个 Agent 只擅长一件事。我常用的角色配置有这么几类Planner规划者只负责读需求、读现有代码结构输出一份任务清单和依赖关系。它不写代码所以上下文可以专注于理解而非生成。Coder实现者拿到 Planner 给的具体子任务专注写代码。它的输入被严格限定不需要知道全局。Reviewer审查者对 Coder 的产出做静态检查找逻辑漏洞、边界条件、命名问题。它和 Coder 用不同的提示词避免自己审自己的盲区。Tester验证者跑测试、跑编译、跑 lint把结果结构化返回。它是闭环的关键执行者。Fixer修复者专门处理 Tester 报回来的失败做最小化修改。这套角色划分的好处是每个 Agent 的提示词可以高度特化。Planner 的提示词里全是分析、拆解、排序Coder 的提示词里全是实现、遵循规范、不要引入新依赖Reviewer 的提示词里全是找问题、质疑、给反例。特化之后每个 Agent 的输出质量都比全能 Agent高一大截。2.3 调度策略串行、并行与条件分支怎么选调度层要回答的核心问题是这些 Agent 按什么顺序跑我实践下来有三种基本模式对应不同场景。串行链适合有强依赖的任务。比如先定义接口再实现后端再实现前端每一步都依赖前一步的产出只能排队。串行的缺点是慢但胜在状态清晰出问题容易定位。并行扇出适合无依赖的子任务。比如给这 8 个工具函数各补一组测试8 个任务互不干扰可以同时开 8 个 Agent。并行能大幅压缩总耗时但要注意资源竞争——如果多个 Agent 同时改同一个文件就会冲突。解决办法是让并行任务操作不同的文件或者用文件锁。条件分支适合需要根据中间结果决策的场景。比如 Tester 跑完测试后如果全绿就走合并分支如果有失败就走修复分支修复完再回到 Tester。这就是闭环自愈的调度基础。实际项目里这三种模式往往是嵌套的。一个典型的重构任务可能是Planner 串行产出计划 → 多个 Coder 并行实现 → Tester 串行验证 → 失败则 Fixer 条件触发 → 回到 Tester。调度器需要能表达这种嵌套结构通常用一个 DAG有向无环图来描述节点是 Agent 任务边是依赖关系。提示调度器一定要有超时和最大重试次数。我见过 Agent 陷入修复-失败-再修复的死循环一晚上烧掉大量额度。给每个任务设一个重试上限比如 3 次超过就标记为需人工介入别让它无限跑。3. 闭环自愈机制让 Agent 自己发现错误并修正3.1 闭环的三个必要条件可观测、可判定、可回滚闭环自愈听起来很玄但拆开看就是三个条件必须同时满足缺一个都闭不起来。可观测指的是 Agent 的每个动作都要产生可被程序读取的输出。写代码这个动作本身不产生反馈但写完代码后跑一次编译就产生了。所以闭环的第一步是给每个动作绑定一个验证命令。比如 Coder 写完一个 Python 文件紧接着跑python -m py_compile和pytest把 stdout/stderr 捕获下来。可判定指的是反馈结果要能被程序判断成败而不是靠人看。编译退出码是 0 还是非 0测试是 passed 还是 failedlint 是 clean 还是有 warning这些都是可判定的。最怕的是那种看起来好像对的模糊反馈比如让 Agent 自己说我觉得没问题这不算闭环。可回滚指的是失败后能回到一个已知良好的状态。如果 Agent 改坏了代码又没法撤销那闭环就变成了越修越坏。所以每次 Agent 动手前要么用 git 打一个临时 commit要么把原文件备份确保修复失败时能退回去。这三个条件里可判定是最容易被忽视的。很多团队的验证命令输出一大堆日志但没有明确的成功/失败标志Agent 拿到之后不知道该怎么办。解决办法是给验证命令包一层让它只输出结构化的结果比如{status: fail, errors: [...]}。3.2 失败分类哪些错误该自动修哪些该直接放弃不是所有错误都值得自动修复。我踩过的坑是让 Agent 无脑重试所有失败结果遇到依赖包版本冲突这种需要人决策的问题时它反复改代码越改越乱。后来我给失败做了分类错误类型典型表现处理策略语法/类型错误编译不过、类型不匹配自动修复重试上限 3 次测试断言失败逻辑不符合预期自动修复但需 Reviewer 复核依赖/环境问题包找不到、版本冲突直接放弃报告人工权限/网络问题无法写入、超时直接放弃报告人工需求理解偏差实现的功能和描述不符回到 Planner 重新规划这个分类的关键在于区分代码问题和环境问题。代码问题 Agent 有能力自己修环境问题它修不了硬修只会浪费时间。判断方法很简单看错误信息里有没有出现代码之外的关键词比如包名、路径、权限、网络。3.3 修复循环的收敛控制怎么避免无限重试即使只让 Agent 修代码问题也可能陷入死循环。比如一个测试断言失败Agent 改了实现结果另一个测试挂了它再改第一个又挂了。这种按下葫芦浮起瓢的情况靠单纯重试是解决不了的。我的做法是引入收敛判据每次修复后记录通过的测试数和失败的错误类型。如果连续两次修复后通过数没有增加或者错误类型在反复横跳就判定为未收敛停止自动修复转人工。这个判据用代码实现很简单def should_continue(history): if len(history) 2: return True last, prev history[-1], history[-2] # 通过数没增加且错误类型重复出现判定不收敛 if last.passed prev.passed and last.error_type in [h.error_type for h in history[-3:-1]]: return False return len(history) MAX_RETRY除了收敛判据还有一个技巧是限制单次修复的改动范围。让 Fixer 只改和错误直接相关的文件不要顺手重构别的代码。改动范围越小引入新问题的概率越低收敛越快。3.4 一个真实的闭环案例批量修复 lint 错误我拿一个真实场景走一遍闭环。需求是把项目里所有 ESLint 报错清掉。这个任务看起来简单但项目有 200 多个文件报错上千条手动改要命。第一步Planner 跑eslint . --format json把报错按文件分组输出一个任务清单。第二步调度器为每个文件开一个 Coder Agent并行处理。第三步每个 Coder 改完后Tester 单独对这个文件跑eslint file捕获结果。第四步如果还有报错Fixer 介入只改这个文件。第五步全部文件通过后跑一次全量eslint .做最终验证。这个案例里闭环体现在每个文件改完立即验证而不是全部改完再验证。前者能快速定位是哪个文件、哪条规则没处理好后者一旦失败就得大海捞针。实测下来200 个文件的任务用闭环方式跑成功率比一把梭高出很多而且失败的文件能精确定位。注意并行跑 lint 修复时要确保每个 Agent 只碰自己的文件。如果两个 Agent 同时改一个文件git 会冲突。调度器在分配任务时要做文件级去重。4. Routine 脚本化把一次性编排固化成可复用流程4.1 Routine 的本质参数化的任务模板Routine 这个词容易让人想到定时任务但在 Claude Code 的语境里它更像是参数化的任务模板。你把一套验证过的 Agent 编排流程写成一个脚本脚本里留出几个参数位每次调用时填入不同的值就能复用到相似的任务上。举个具体的例子。新增一个 REST 接口这个任务几乎每个后端项目都会反复做。它的流程是固定的定义路由 → 写 controller → 写 service → 写数据访问 → 写测试 → 跑验证。变的只是接口名、路径、字段。把这个流程写成 Routine参数就是{resource_name}、{path}、{fields}下次新增接口时一行命令就能触发整套编排。Routine 的价值在于把提示词工程的经验沉淀下来。你第一次做某类任务时可能调了半天提示词才让 Agent 输出满意结果。如果不固化下次还得重调。固化之后这套提示词就成了团队资产谁来跑都一样。4.2 Routine 脚本的结构声明、参数、步骤、断言一个可用的 Routine 脚本我通常写成四段结构。声明段描述这个 Routine 是干什么的、适用什么场景、有什么前置条件。这段是给人看的方便团队里其他人知道什么时候该用它。参数段定义输入。参数要尽量少而明确每个参数都要有类型和默认值。比如resource_name是字符串必填with_auth是布尔默认 true。参数太多说明这个 Routine 承担了太多职责该拆了。步骤段是核心描述 Agent 的编排。每一步要写清楚用哪个角色的 Agent、输入是什么、输出传给谁、验证命令是什么。步骤之间用依赖关系连接形成 DAG。断言段定义什么算成功。这是 Routine 和普通脚本最大的区别——它不只是执行还要自检。断言可以是所有测试通过、lint 无 error、生成的接口能被 curl 通。下面是一个简化版的 Routine 结构示意用 YAML 描述实际可以用任何你顺手的格式name: add-rest-endpoint description: 为现有项目新增一个 REST 接口 params: resource_name: { type: string, required: true } path: { type: string, required: true } fields: { type: list, required: true } with_auth: { type: bool, default: true } steps: - id: plan agent: planner input: 为 ${resource_name} 设计接口路径 ${path}字段 ${fields} - id: implement agent: coder depends_on: [plan] input: ${plan.output} - id: test agent: tester depends_on: [implement] command: pytest tests/test_${resource_name}.py assertions: - test.status passed - lint.errors 04.3 参数设计怎么让 Routine 既通用又不失控Routine 最容易犯的错是参数设计过度。我见过有人把 Routine 的参数做到二十几个结果每次调用都要查文档填半天还不如手动做。参数设计的核心原则是只暴露真正会变的东西其余全部写死。怎么判断什么是真正会变的看这个值在不同调用之间是否经常不同。比如接口路径经常变是参数代码风格用 4 空格缩进基本不变写死。如果一个参数 90% 的调用都用同一个值那它就不该是参数应该做成默认配置。另一个技巧是用枚举代替自由文本。比如认证方式这个参数与其让用户填字符串不如限定为none、jwt、session三个选项。枚举能防止用户填出 Agent 不认识的词减少出错。4.4 Routine 的版本管理与回归测试Routine 一旦被团队用起来就变成了基础设施改它要谨慎。我给 Routine 加了版本号每次修改都递增并且保留旧版本。这样即使新版本有问题也能快速回退。更重要的是给 Routine 写回归测试。做法是准备几个标准输入每次改完 Routine 后用这些输入跑一遍看输出是否符合预期。标准输入要覆盖典型场景和边界场景比如字段为空、路径带特殊字符、认证关闭。回归测试的断言不用太细抓住关键点就行生成的文件是否存在、测试是否通过、接口是否可调用。太细的断言会导致 Routine 稍微调整就测试失败维护成本反而高。提示Routine 的回归测试最好在隔离环境跑别在真实项目上跑。我吃过亏一次测试把生产配置给改了。用临时目录或容器隔离跑完就销毁。5. 落地这套架构时最容易翻车的几个地方5.1 上下文污染Agent 之间传递了什么多 Agent 系统里Agent 之间的消息传递是最容易出问题的地方。我见过最典型的翻车是Coder 把整个文件内容传给 ReviewerReviewer 又把整个文件加上自己的评论传回 Coder来回几次上下文里全是重复的代码真正有用的信息被淹没。正确的做法是传递结构化摘要而不是原始内容。Coder 传给 Reviewer 的应该是我改了哪几个文件、每个文件的 diff、我的实现思路而不是整个文件。Reviewer 传回的应该是发现的问题列表、每个问题的位置和建议而不是把代码再抄一遍。这个原则可以总结成一句话Agent 之间传的是结论和引用不是全文。文件内容放在磁盘上消息里只放路径和行号需要的时候各自去读。这样上下文占用小而且不会因为版本不一致产生混乱。5.2 状态管理任务进度存在哪单步聊天没有状态管理的问题因为状态就在对话历史里。多 Agent 一旦并行状态管理就成了必须解决的问题。我一开始用内存里的字典存任务状态结果进程一重启全丢了正在跑的任务全废。后来改成文件系统 简单数据库的方案。每个任务在磁盘上有一个目录目录里放任务元数据JSON、每个 Agent 的输入输出、验证结果。这样即使进程重启也能从磁盘恢复状态继续跑没完成的部分。状态管理还要考虑并发写入。多个 Agent 同时更新任务状态时要用文件锁或者数据库事务避免写冲突。我用的方案是每个 Agent 写自己的子目录汇总时由调度器统一读避免并发写同一个文件。5.3 成本控制别让 Agent 无限烧额度多 Agent 编排的 token 消耗是单步聊天的好几倍因为每个 Agent 都要读上下文、生成输出还有 Agent 之间的消息传递。如果不加控制一个复杂任务跑下来成本可能超出预期。控制成本的手段有几个。一是限制每个 Agent 的上下文大小超过就截断或摘要。二是设置任务总预算比如一个任务最多消耗多少 token超了就停。三是复用 Agent 实例相似的任务用同一个 Agent 跑避免重复初始化。四是缓存验证结果同一个文件的 lint 结果在没改动的情况下不用重跑。我实测下来加了预算控制之后成本能降下来不少而且因为避免了无意义的反复重试任务成功率反而提高了。5.4 人工介入的时机什么时候该叫停再好的闭环自愈也有搞不定的情况。关键是知道什么时候该叫停把控制权交回给人。我设了几个触发人工介入的条件重试超过上限、错误类型是环境问题、任务耗时超过预期、Agent 的输出和需求明显不符。人工介入不是失败而是这套系统的正常组成部分。把 Agent 能干的活交给它把需要判断的活留给人这才是合理的分工。我见过有人追求全自动结果 Agent 在错误的方向上狂奔最后返工的成本比一开始就人工介入还高。注意人工介入时要把 Agent 的完整执行历史呈现出来包括它做了什么、为什么这么做、卡在哪。这样人接手时不用从头查能快速定位问题。6. 我在这套架构上踩过的坑和总结出的几条经验先说一个最反直觉的体会多 Agent 编排的难点不在 Agent而在编排。很多人把精力花在调每个 Agent 的提示词上结果 Agent 单个表现都不错但组合起来就乱套。真正决定成败的是调度逻辑、状态管理、错误处理这些胶水部分。我后来把大部分时间花在写调度器和验证框架上Agent 的提示词反而改得少了。第二个体会是验证命令的质量决定闭环的上限。如果验证命令只能告诉你失败了Agent 就不知道往哪修。如果验证命令能精确到第 42 行第 3 列的类型不匹配Agent 修起来就有的放矢。所以我在项目里会专门花时间打磨验证命令让它输出尽可能精确的错误定位。这个投入的回报非常高。第三个是Routine 要从小处开始。别一上来就想做一个全自动开发的大 Routine先从一个具体的小任务做起比如给指定文件补测试跑通了再扩展。小 Routine 容易验证、容易调试积累几个之后再组合成大流程。第四个是给 Agent 的输出加约束。自由文本输出看起来灵活但下游解析起来痛苦。我后来要求所有 Agent 的关键输出都用结构化格式JSON 或 YAML这样调度器能可靠地解析不用做模糊匹配。结构化输出还能顺便做 schema 校验提前发现 Agent 输出格式错误。最后一个经验是关于日志。多 Agent 系统出问题时没有详细日志根本没法排查。我在每个 Agent 的每次调用前后都记日志包括输入、输出、耗时、token 消耗、验证结果。日志按任务 ID 组织出问题时能完整回放整个执行过程。这套日志后来还帮我做了成本分析发现哪些环节最烧钱针对性优化。这套架构不是银弹它适合的是重复性高、验证明确、单任务规模适中的场景。如果你的任务每次都不一样或者验证标准很模糊那多 Agent 编排带来的复杂度可能超过收益。判断标准很简单如果你发现自己在反复做同一类任务而且每次都能明确判断做没做对那就值得把它 Routine 化。
