上周我让一个 Claude Code 实例去重构一个中等规模的 Python 服务它在没有任何人干预的情况下跑了四十分钟中途两次卡在工具调用循环里最后还把公共接口的签名改坏了。最初我把问题归咎于模型本身后来把同一个任务拆成多个 Agent 并行处理、加上自动回归校验和脚本化的 Routine 封装之后效果好了不止一个量级。这篇就把我在实战里摸索出的 Claude Code 多 Agent 编排、闭环自愈与 Routine 脚本化架构完整拆一遍适合已经在用 Claude Code、但觉得单个会话做不了复杂任务的开发者参考。说起 Claude Code很多人还停留在高级命令行助手的印象里给它一段自然语言它读代码、改代码、跑命令、给解释。但一旦任务规模变大——比如重构一个多模块服务、批量迁移几百个文件、搭一套带回归测试的功能——单会话模式很快就会暴露出各种问题。这篇文章不会停留在概念层面我会把编排的三种形态、自愈循环的具体脚本、Routine 的设计思路以及从安装到接第三方模型再到 VS Code 联调的完整落地链路全部讲清楚。1. 单 Agent 的瓶颈上下文漂移、卡死与局部最优陷阱1.1 上下文漂移越干越容易忘了自己说过什么单 Agent 最大的问题不是模型不够聪明而是会话上下文太长了。当一个会话里的文件改动、报错日志、用户指令累积到几万字之后模型对早期决策的注意力会明显衰减。你可以想象一个人同时抱着几十个记事本开会越往后越容易把最初的结论记串。在我那次重构里前五分钟定好的接口命名做到第三十分钟变成了另一个名字Agent 改了一个公共函数的签名却没有去更新所有调用方。它不是故意犯错的是早期信息被大量中间日志冲淡了。Claude Code 的上下文窗口虽然大但大不等于够用——注意力分布是非均匀的老信息永远比新信息更难被精确召回。这类问题的可怕之处在于错误不是突然出现的而是逐渐累积的。你在前面几轮审查里看不出问题等到攒了几处不一致之后整个模块的行为就开始变得不可预测。单 Agent 模式下你只能手动把关键约束一遍遍强调或者隔一段时间开一个新会话把上下文压缩一遍。这本质上是在用人工弥补架构缺陷。1.2 工具死循环没有外部信号帮忙跳出局部搜索Claude Code 的能力来自工具调用但工具调用一旦失控就会变成死循环。我见过最典型的表现是Agent 反复执行同一套测试失败后只做微小的表面修改然后又跑一遍一来一回十几分钟代码 diff 却几乎没有变化。这不是 bug而是模型在局部搜索里陷进去了。它每轮都能拿到测试失败这个负反馈但它没有能力判断这个失败可能不是当前文件引入的。于是它反复在自己的可见范围内打转。单 Agent 模式下这种死循环的终止条件只有两个token 耗尽或者你强行中断。我在实践中发现给单 Agent 加一句如果连续两次修改没有让测试结果发生变化就停下来分析根因能缓解一部分问题但依然不可靠。更根本的解法是让多个 Agent 以不同视角审视同一个失败一个负责修故障另一个负责审查 diff 是否合理第三个负责验证整体行为。这其实就是多 Agent 编排的起点。1.3 从单 Agent 到多 Agent编排、自愈与 Routine 的关系很多人分不清编排、自愈和 Routine 各自的职责我打个比方你就明白了一个团队开发功能项目经理负责把需求拆成任务并发给不同工程师编排工程师写完代码要跑测试测试挂了就自己看日志改代码再跑直到通过自愈有经验的工程师会把接手新需求时先做什么检查、代码规范怎么过、提交前跑哪些命令写成团队文档新人也照着做Routine。对应到 Claude Code 的世界里编排解决的是分工问题决定谁在什么时候做什么上下文如何隔离自愈解决的是失败恢复问题让系统在出现错误时自动进入修复回路Routine 解决的是经验固化问题把一组可复用的操作流程封装成命令避免每次从零开始摸索。三者不是平行的三个功能而是同一个系统的三个层调度层负责任务分发执行层按 Routine 干活异常处理层在出错时触发自愈。这也是我下面要展开的核心框架。2. 三种编排形态怎么选并行、主从与流水线的适用场景2.1 并行拆分把无依赖的模块交给不同 Agent如果你的仓库里有几个模块彼此依赖很少并行拆分是最直接的提速方式。比如一个服务包含 auth、payment、user 三个目录各自有独立的测试那就可以启动三个独立的 Claude Code 进程每个进程只负责一个子目录。用命令行方式做并行很简单。假设你有一个任务清单 tasks.txt每行一个子任务可以写一个 Python 脚本并发调用 Claude Code 的 headless 模式import subprocess from concurrent.futures import ThreadPoolExecutor tasks [ 重构 auth 目录保持公共接口不变补充单元测试, 重构 payment 目录保持公共接口不变补充单元测试, 重构 user 目录保持公共接口不变补充单元测试, ] def run(task): cmd [ claude, -p, task, --allowedTools, Read,Edit,Bash, --permission-mode, acceptEdits ] return subprocess.run(cmd, capture_outputTrue, textTrue) with ThreadPoolExecutor(max_workers3) as pool: results list(pool.map(run, tasks)) for i, r in enumerate(results): print(f任务 {i}: exit{r.returncode}, stdout length{len(r.stdout)})并行模式最大的收益是时间三个模块同时跑耗时约等于最慢的那个模块。但代价是你必须提前把边界切干净如果两个模块都依赖同一个公共文件它们同时改这个文件必然产生冲突。我自己的做法是公共文件单独抽出来或者指定一个 Agent 负责公共层其余 Agent 只改各自目录。另外并行模式不适合需要频繁交流的任务。Agent 之间不能直接对话只能通过文件交换信息。如果你发现两个任务之间隐性依赖很多优先考虑别的模式。2.2 主从模式一个调度者把关多个执行者干活主从模式是更可控的一种编排。一个 orchestrator Agent 只做分解和验收不直接改代码多个 worker Agent 分别执行具体子任务把结果汇报给调度层。这种模式最适合那种需求复杂但每个子任务边界清晰的场景。Orchestrator 把需求拆成若干条指令每条指令对应一个 worker 进程worker 完成后把输出写到指定目录orchestrator 再检查产物是否满足验收标准。我曾经用一个 Bash 脚本实现过轻量版的主从调度。核心逻辑很简单维护一个任务队列失败的任务重试或者分配给另一个 worker 处理#!/usr/bin/env bash set -euo pipefail WORK_DIR/tmp/agent_workspace mkdir -p $WORK_DIR/results declare -a tasks( 为 auth 模块新增登录失败锁定策略 为 payment 模块补充金额校验逻辑 为 user 模块补充资料更新接口 ) for i in ${!tasks[]}; do task_idtask_$i echo 分发 $task_id claude -p ${tasks[$i]}输出报告保存到 $WORK_DIR/results/$task_id.md \ --output-format text $WORK_DIR/results/$task_id.log 21 echo $task_id 完成exit$? done echo 调度完成所有结果在 $WORK_DIR/results 目录这个脚本没有做复杂的失败判断但它把最重要的东西固定下来了每个任务独立跑、结果独立落盘、调度器只负责顺序和记录。真实的 orchestrator 可以在这个基础上加更多逻辑比如任务依赖、结果校验、失败重分配。主从模式的优点是把决策和执行分开了。Orchestrator 的上下文不会被某个具体任务的细节污染它始终从整体视角判断结果是否合格。缺点是多了一层进程调度开销适合任务数量在几十个以内的场景。2.3 流水线模式一个 Agent 的输出是下一个 Agent 的输入流水线模式适合有明确顺序依赖的任务。最典型的例子是代码生成 - 静态检查 - 测试修复 - 文档补全。前一个 Agent 生成的代码文件后一个 Agent 基于它继续工作中间产物通过固定目录传递。我拿一个实际项目来说批量给某个服务加可观测性日志。流水线是这样跑的第一个 Agent 扫描代码里的对外接口生成一份哪些函数需要加日志、加什么级别的清单第二个 Agent 读取这份清单逐文件植入日志代码第三个 Agent 跑一遍静态检查找出日志格式不符合规范的地方第四个 Agent 根据静态检查结果做修复。流水线最关键的是定义好中间产物契约。每个阶段写在哪个目录、什么格式、验收标准是什么必须在启动前定清楚。否则 Agent 之间传递的信息就可能对不上。相比之下流水线模式比并行模式慢比主从模式简单但它最贴近真实开发流程也最容易做沉淀——因为每个阶段本身就可以封装成一个 Routine。2.4 三种模式对比什么时候选哪种模式适用场景优点风险与代价典型配置并行模块间无依赖、可同时推进吞吐最高耗时最短公共文件冲突无法传递即时反馈多进程同时跑每进程限定目录主从需求复杂、子任务边界清晰决策与执行分离整体可控多一层调度开销需要验收标准orchestrator worker 脚本流水线阶段之间有强顺序依赖产物可追踪阶段可复用整体耗时受最慢阶段限制每阶段写产物到固定目录我的建议是拿不准的时候先从流水线开始。流水线的每一步都可以单独验证出问题你很容易定位到底哪个阶段失败了。并行和主从更像是流水线跑顺之后的优化手段而不是起点。3. 闭环自愈不是魔法错误回调、回归重试与轮次上限的实现细节3.1 自愈的闭环逻辑执行、校验、反馈、重试自愈的完整回路只有四步执行任务校验结果反馈错误重试修复。听起来很简单但大多数失败的自愈系统其实只做了重试而没有做好校验反馈。这就像一个体感很差的程序员写代码写完自己编译一遍编译没过就根据报错去改然后继续跑。自愈的关键不在于重试多少次而在于校验信号是否准确。校验信号越精确重试越有效信号模糊重试就是在烧钱。校验手段的优先级我一般是这么排的编译/类型检查 静态检查lint 单元测试 端到端测试 Agent 自我检查。越靠前的越便宜、越快、越稳定。真实项目里很多错误根本不需要跑完整套测试才能发现一个 ESLint 或 mypy 就跑出来了。自愈循环里优先跑便宜的校验能大幅降低修复成本。3.2 一个可复用的自愈循环脚本下面是实际可用的 Bash 脚本结构不复杂但把自愈的关键点都覆盖了轮次上限、测试驱动修复、失败退出码。你可以直接保存为 selfheal.sh 使用#!/usr/bin/env bash set -euo pipefail MAX_RETRIES${MAX_RETRIES:-3} TARGET_DIR$1 TEST_CMD${2:-python -m pytest} for i in $(seq 1 $MAX_RETRIES); do echo 第 $i 轮运行校验命令 if eval $TEST_CMD; then echo 校验通过任务完成 exit 0 fi echo 校验失败调用修复 Agent claude -p 修复 $TARGET_DIR 下导致校验失败的问题。修复前先阅读相关代码和错误输出定位根因修改后先自我检查再交付不要提交只改表面症状的代码。 \ --allowedTools Read,Edit,Bash \ --permission-mode acceptEdits done echo 重试 $MAX_RETRIES 轮仍未通过需要人工介入 2 exit 1脚本里藏了几个细节。第一MAX_RETRIES默认 3这是成本和安全之间的平衡点。第二修复 prompt 里明确要求先阅读相关代码和错误输出定位根因这一句话能显著减少只改表面症状的行为。第三每次修复后重新跑的是同一个校验命令保证闭环的验证标准稳定。实际使用的时候TEST_CMD可以不是测试而是任何布尔判断命令。比如python -m compileall src做语法检查npx eslint src做代码规范检查甚至可以是grep -q TODO src/main.py exit 1; exit 0这种自定义规则。你还可以把校验命令从测试扩展成测试 diff 检查。我经常加一条修复完成后检查 git diff 行数如果单轮改动超过某个阈值就判定这次修复可能跑偏了。例如MAX_DIFF_LINES200 if [ $(git diff --numstat | awk {s$1$2} END {print s0}) -gt $MAX_DIFF_LINES ]; then echo 修改量过大停止自动修复需要人工确认 exit 1 fi有些 Agent 在修复失败时会选择绕过问题而不是解决问题比如把测试用例删掉。所以自愈脚本里还应该加一个保护完成任务前检查测试文件是否被修改或删除。如果不检查Agent 很容易通过阉割测试让校验通过这比不修复更糟。3.3 自愈的边界与人工介入时机自愈不是无限重试。token 成本、时间成本、上下文污染都是现实约束。我个人的习惯是把单任务的修复轮次限制在 3 轮以内。如果 3 轮都没有命中说明问题可能不是局部代码问题而是需求理解、架构设计、或跨模块冲突层面的问题。再继续烧 token 只会让 Agent 在同一个局部里打转。哪些情况适合自愈编译错误、lint 不通过、单元测试失败、配置文件格式错误、生成的文档缺失关键章节。这些问题的特征是有明确客观标准Agent 可以通过反馈快速逼近正确答案。哪些情况不适合自愈需求歧义、架构决策、跨模块接口设计、测试用例本身的正确性。这些问题没有唯一正确答案Agent 每轮做出的修复可能只是随机选择一个方向。遇到这类问题自愈循环越快熔断越好。我判断是否人工介入有三个信号你们也可以参考连续两轮修复都在修改同一个文件且校验依旧失败Agent 修改了测试文件或跳过了部分校验报告说修复完成但 git diff 内容明显偏离任务目标。出现任何一个信号就停掉循环自己去看一遍。4. Routine 脚本化把团队里最值钱的操作流程固化成命令4.1 Routine 是什么从每次重新打字到一键执行Routine 就是把一段经常重复、有固定步骤的 Agent 任务固化成脚本或命令。如果说编排是调度层、自愈是异常处理层Routine 就是标准作业层。我见过很多人用 Claude Code 的方式是每次想让它干个活就在命令行里临时打一段长长的话。这就像每次做饭前都重新去菜市场现买食材、现想菜谱。而 Routine 是把你已经验证过有效的那套流程沉淀下来下次直接调用。一个菜谱是 Routine厨师是 Agent尝菜是校验叫另一个厨师帮忙备菜是编排。菜谱要清晰到换个厨师也能做出一致的菜Routine 也要清晰到换个新会话、换一批文件也能执行出可靠的结果。什么样的操作值得沉淀成 Routine我的标准有三条高频每周至少用一次、步骤稳定每次执行的流程大同小异、可校验有明确成功标准。比如代码审查、环境诊断、批量迁移、依赖升级、文档生成这些都是 Routine 的好素材。4.2 一个 Routine 的完整设计参数化、幂等、结构化输出Routine 设计有三大原则参数化、幂等、结构化输出。参数化指的是脚本能接收不同的输入而不是把路径写死幂等指的是同样一个 Routine 重复执行不会产生叠加副作用结构化输出指的是每次执行都有清晰的退出码和日志方便上层编排判断结果。下面是一个代码审查 Routine 的示例。它做的事情是取最近一次提交的 diff让 Agent 审查把报告写到固定文件。这个 Routine 可以被任何项目复用只要传一个参数指定 diff 范围#!/usr/bin/env bash set -euo pipefail DIFF_RANGE${1:-HEAD~1..HEAD} OUTPUT_FILE${2:-/tmp/review_report.md} git diff $DIFF_RANGE /tmp/latest_diff.txt if [ ! -s /tmp/latest_diff.txt ]; then echo diff 为空没有需要审查的变更 exit 0 fi claude -p 你是代码审查员。请阅读 /tmp/latest_diff.txt 里的代码变更按严重程度列出问题包括潜在 bug、安全问题、性能隐患、可维护性问题。每个问题给出文件路径、行号级定位和具体修改建议。输出为 Markdown 格式。 \ --output-format text $OUTPUT_FILE echo 审查完成报告输出到 $OUTPUT_FILE这个 Routine 体现了参数化diff 范围可传、输出路径可传、幂等不管跑多少次只是重新生成一份报告、结构化输出退出码代表成功失败报告文件是固定格式。把你的项目里最常见的 Agent 任务都写成这种形态你会发现团队协作时能省掉大量沟通成本。4.3 实际 Routine 示例环境诊断、批量迁移、依赖升级环境诊断 Routine 是我用得最多的。它的职责是检查当前仓库的依赖版本、Python/Node 版本、配置文件是否完整输出一份诊断报告如果发现问题直接询问是否交给 Agent 修复。批量迁移 Routine 要复杂一些通常和自愈循环配合。它的流程是扫描目标文件列表逐个交给修复 Agent迁移失败的文件记录到单独列表最后生成迁移报告。每个文件用独立会话处理避免上下文互相污染。依赖升级 Routine 我强烈建议做。它要做的事情包括读取当前依赖列表、检查最新可用版本、列出升级影响分析、按模块分组升级、跑一遍全量测试。全部用脚本固化了之后升级依赖从一个下午的忐忑变成一条命令加一杯咖啡。4.4 与多 Agent、自愈机制的组合方式Routine 不是孤立存在的。在实际架构里Routine 是 worker 的标准执行方式自愈是 Routine 的异常处理层编排是 Routine 的调度层。一个任务进来编排调度器先判断应该用哪个 Routine然后起 worker 执行执行过程中如果校验失败触发自愈回路轮次用尽后上报给编排层编排层决定是重试、换方案还是通知人工。这种三层结构的价值在于每层都可以独立替换。你觉得某个 Agent 能力不够换一个入口你觉得某个 Routine 的提示词写得不好只改 Routine 本身你觉得自愈太烧钱只调轮次上限。系统各部分的耦合度低维护起来舒服得多。5. 环境落地Claude Code 安装、第三方模型接入与 VS Code 联调5.1 安装与初始化从 npm 到终端可用的完整路径Claude Code 的安装其实很快麻烦的是环境不一致带来的各种小问题。最标准的安装方式是 npm 全局安装npm install -g anthropic-ai/claude-code装完之后执行claude --version确认版本。如果提示找不到命令十有八九是 npm 全局 bin 目录没加进 PATH。执行npm config get prefix拿到 npm 全局目录再把对应的 bin 目录加入 PATH 就行。安装完成后第一次运行claude会引导你完成初始化。注册账号与不注册账号的主要差异在于会话管理、用量统计这些功能范围具体以官方当前说明为准。我的建议是正式项目开发用一个稳定的账号登录会话恢复和用量统计会让你心里有数临时体验或者测试脚本不受限的轻量模式也可以先用着。在 Ubuntu 上额外要注意 Node 版本。Claude Code 对 Node 版本有最低要求如果你系统自带的 Node 太老建议先用 nvm 装一个当前 LTS 版本再安装。macOS 上主要是权限问题如果全局安装失败检查目录写权限必要时用sudo但优先考虑修复 npm 目录权限而不是用 sudo 强行装。5.2 第三方模型接入与多模型切换合规配置与团队协作很多团队不想只用固定模型会考虑接入 DeepSeek、Qwen、GLM 等第三方模型服务。这一步在 Claude Code 里做起来并不复杂核心是修改它连接的后端配置。社区里常见的做法是使用 cc-switch 这类开源配置切换工具它可以把多套模型服务的配置保存下来一键切换。切换的本质是环境变量或配置文件里的接口地址和密钥。下面是一个环境变量层面的接法示意export ANTHROPIC_BASE_URLhttps://your-service-provider.example.com export ANTHROPIC_AUTH_TOKENyour_api_key_here claude接入第三方模型时有两点必须提醒第一不同服务商支持的模型能力、上下文长度和工具调用格式不同接入前先阅读对应服务商的技术文档确认它提供的 Anthropic 兼容接口支持 Claude Code 需要的全部特性。第二任何模型接入都必须遵守服务商的服务条款和使用规范不要做超出授权范围的事情。这既是对平台规则的尊重也避免你的项目埋下合规隐患。多模型切换在团队协作里特别有用。一个模型擅长代码生成另一个模型擅长审查第三个模型可能成本低适合批量任务。通过 cc-switch 这类配置管理工具你能在一条命令内完成切换再配合前面的编排框架不同的 worker 用不同的模型服务很多工作流就有意思了。5.3 VS Code 集成把 Agent 放进编辑器VS Code 里可以直接安装 Claude Code 扩展。装完后侧边栏会出现一个面板可以创建会话、查看 Agent 的工具调用记录、管理权限。和命令行模式相比VS Code 面板的优势是可视化程度高你能看到 Agent 正在读哪些文件、执行了哪些命令便于观察和干预。扩展的配置项里我最常用的是权限控制。默认情况下Agent 执行工具需要逐次确认这在交互式会话里是安全的但放到自愈脚本或批量任务里就太拖沓了。你可以把某些工具设为自动允许比如 Read、Edit、Bash但要小心放开之后 Agent 的自主性会提高建议先在小范围试用。VS Code 里的会话和 CLI 是可以共存的。我通常的习惯是探索性调试、理解代码结构用 VS Code 面板批量任务、自动化流程用 CLI headless 模式两者通过同一套配置文件管理权限和接口地址切换没有摩擦。5.4 常见安装与联调问题速查症状可能原因处理方式claude: command not foundnpm 全局 bin 未加入 PATH执行npm config get prefix把 bin 目录加入 PATH安装时提示 Node 版本过低系统 Node 版本不满足要求用 nvm 安装 LTS 版本重新安装 Claude Code登录状态失效Token 过期或本地配置损坏重新执行claude完成初始化登录Agent 无法执行 Bash 工具权限配置限制检查权限模式按需打开 Bash 工具白名单第三方模型接入后响应异常接口地址或模型名称配置错误核对服务商文档确认兼容接口和模型名VS Code 面板找不到扩展扩展未安装或版本不匹配在扩展市场搜官方扩展检查是否被禁用如果你在初始化阶段看到环境可用性相关提示请以官方的支持范围说明为准先确认当前环境是否在支持列表内再继续后续配置。6. 我在真实项目里踩过的编排坑与调优心得6.1 坑 1并行 Agent 互相覆盖公共文件第一次跑并行编排我自信满满地起了四个 worker分别处理四个目录。结果十分钟后 git 状态乱成一团两个 Agent 同时改了一个公共工具函数文件互相覆盖最后半个模块处于不可编译状态。根因在于我只按目录切分了任务没有按文件所有权切分。公共文件是隐性依赖表面上看目录独立实际上共享了我没意识到的代码。后来的解法很简单任务拆分时先跑一遍依赖分析把所有公共文件单独标记公共文件要么由调度器统一改要么任何一个 Agent 都不允许碰全部通过任务描述传给专人来改。6.2 坑 2自愈循环把 token 烧掉几千块自愈机制刚上线时我犯过一个冒进错误把最大重试轮数设成 10并且校验命令用的是全量端到端测试。结果一个很小的问题触发 Agent 反复修了十轮每轮都跑全量测试token 消耗直接爆了。这次教训让我把自愈循环的成本控制拆成了三层校验命令优先用静态检查和单元测试只有这些全绿才跑端到端单任务重试上限默认 3 轮绝不轻易放开每轮修复前先记录当前 git 状态如果 Agent 连续两轮产出几乎同样的 diff就判定为停滞直接熔断。参数我的默认值说明MAX_RETRIES3单任务最大自愈轮次FIRST_CHECKlint / 类型检查第一轮校验用最便宜的信号SECOND_CHECK单元测试第一轮通过后再跑FINAL_CHECK端到端测试交付前最后的门禁DIFF_LIMIT200 行/轮单轮修改量超过则人工介入6.3 坑 3Routine 参数泛滥最后没人愿意用我一开始设计的代码审查 Routine 有七个参数从 diff 范围、输出路径到审查关注点、语言偏好应有尽有。结果团队里除了我没人愿意用它——参数太多了背不住。后来我把 Routine 按场景重新设计而不是按功能设计。不再有一个通用的审查 Routine而是拆成了常规 PR 审查安全专项审查性能专项审查三个。每个的默认参数都设置好用户只需要在最简单的场景里改一两个值。参数越少采用率越高。6.4 几条沉淀下来的调优心得如果让我给刚起步的团队一个建议我会说先跑通一条最小的流水线再加自愈最后加编排。很多人一开始就想搭一个全自动多 Agent 平台结果调试编排本身花的时间比真正干活的时间还多。我踩过这个坑所以我强烈推荐从最小的闭环开始比如就写一个脚本一个 Agent 生成代码一个脚本跑测试失败就再调用一次修复 Agent。这条链路稳定了再慢慢把并行、主从这些模式加进来。另外架构里一定要给 Agent 明确的不做清单。比如不要修改测试文件不要改动公共接口签名不要删除 TODO 注释。Agent 是不会主动遵守的但这些约束写在 prompt 和 Routine 的固定片段里之后能明显降低走偏概率。最后别把所有环节都自动化。merge 到主干、部署上线、删除旧 API 这类动作我都会保留人工确认节点。自愈和编排解决的是重复劳动和低级错误真正关键的判断还是留给人来做比较稳妥。