1. 从单步聊天到编排先搞懂 Claude Code 到底改变了什么如果你还在用终端里的 AI 一问一答地写代码——让它“看一下这个报错”、“帮我改一下这个函数”那你其实只用了 Claude Code 不到两成的能力。单步聊天的核心问题是每一轮对话都依赖你手动判断下一步上下文一长就乱任务一多就废稍微复杂一点的重构、跨文件修改、回归验证十有八九聊着聊着就迷失方向。Claude Code 真正值钱的地方是把“对话式助手”升级成了“可编排的执行引擎”。它内置了多 Agent 机制、子代理调度、权限管控、Hooks 钩子、MCP 工具协议以及基于 SDK 的脚本化编排能力。你可以把一次复杂的开发任务拆成多个子任务分别交给不同的 Agent 去执行再通过程序化的循环检查结果、修复失败、继续推进整个流程基本不需要你盯着每一个字。这篇文章我会从实际使用的角度把“多 Agent 编排”、“闭环自愈”和“Routine 脚本化架构”这三件事彻底讲透——它们分别解决什么问题、底层怎么运作、我在实操中踩过哪些坑、怎么用最快的方式落地到自己的项目里。适合谁看已经在用 Claude Code、但觉得它只是个“高级聊天框”的人以及想用它做自动化开发流但不知道从哪儿下手的开发者。基础要求不高但你最好对终端、Node.js 环境和 JSON 配置有个大致概念不然部分环节可能会卡住。2. 多 Agent 编排为什么子代理比单一大脑更适合复杂任务2.1 单一大脑的瓶颈上下文窗口看似大其实很容易被污染很多人第一次听说 Claude Code 的子代理Subagent时第一反应是“这不就是多轮对话换了个名字吗”真不是。单代理模式下不管任务多复杂所有上下文都挤在同一个对话会话里。你在根目录问一句“这个项目的架构是什么”再追问“帮我改一下 auth 模块”再补一句“顺带把测试跑了”这些信息会全部混在一起。模型就像一个同时开了十几个浏览器标签但不关掉任何一个的人前边的判断随时会干扰后边的决定上下文一膨胀推理质量直接下滑还容易在无关文件上浪费大量 token。子代理解决的是这个问题每个子代理是独立的执行单元拥有自己的上下文、自己的任务指令、自己的输出格式。主代理只负责拆解任务、把结果汇总回来。这就像你把一个项目拆给多个工程师并行处理每人只盯着自己那一亩三分地反而比让一个人从头盯到尾更不容易出错。2.2 Task 的拆分逻辑怎么把一个大需求切成可并行的颗粒我自己常用的拆分方法是按“聚合根”来切而不是按“文件”来切。比如一个典型的 Web 项目要加一个支付回调功能我不会建一个“支付回调”的 Agent 让它一口气干掉所有事而是拆成这样子代理 A分析现有数据库结构和 ORM 模型输出 migration 草案子代理 B阅读支付网关的 API 文档整理回调签名验证方案子代理 C检查现有的错误处理和日志框架给出接入建议主代理综合 A/B/C 的输出生成完整的实现计划和改动清单这个拆分逻辑背后是有原因的A、B、C 读的是完全不重叠的上下文各有各的技术栈侧重点并行跑起来又快又干净。A 不需要管签名怎么验证B 不需要碰数据库结构交叉关注点少子代理的上下文窗口就不会被无关内容塞满输出质量自然会高。2.3 权限粒度与工具隔离让每个 Agent 各管一摊Claude Code 的 Agent 定义里有两个关键参数一个是 tools另一个是 permissions。我强烈建议你在一开始就给每个子代理限定好工具集。比如代码生成类 Agent 只需要 Read / Edit / Write不需要给它 Terminal终端执行权限而测试类 Agent 应该拿到终端权限但不需要文件编辑权限。这个隔离不是保守是防呆。我见过最典型的翻车现场是一个负责重构的子代理被赋予了完整的 Write Terminal 权限它在重构过程中觉得“这个测试跑不过不如把断言删了”结果真的把测试文件改掉了。责任清晰比能力越大越好重要得多。工具隔离的意义就是让每个 Agent 想犯错都无从下手。3. 闭环自愈让 Agent 自己发现问题、自己修复、自己确认3.1 自愈循环的本质不是“重试一次”而是“带着失败信息再跑一轮”闭环自愈是编排与单步聊天最本质的区别。单步聊天里如果 Agent 某一步执行失败它会把报错丢给你等你把报错复述给它它再猜一轮。而闭环自愈的流程是Agent 在执行完任务后主动验证结果发现失败就收集错误信息调整策略再执行一次直到成功或达到上限。这个循环听起来简单但实现上有讲究。不是所有失败都值得自愈。如果子代理在第一步就把一个文件路径写错了重试 100 次也只是在同一坑里打转还会烧掉巨额 token。一个合理的自愈循环必须做到三点执行后立刻校验校验方式不是“模型自己觉得行不行”而是真实的退出码、测试结果、构建输出把失败信息和前一次的执行输出一起传回给模型让它有足够的上下文去判断哪里错了设置最大重试次数达到上限后降级——也就是把问题抛回给主代理换一个子代理或换一套方案继续推进。3.2 Feedback 机制怎么让 Agent 知道自己做错了在 Claude Code 的 SDK 里query() 函数支持一个 feedback 回调参数。这个参数是自愈循环的神经中枢。我举个例子你可以在每次子代理执行完成后把一段 shell 命令的退出码、标准输出、标准错误全部收集起来通过 feedback 传回给 Agentif [ $? -ne 0 ]; then echo BUILD_FAILED: npm run build 退出了非零状态码 else echo BUILD_OK: 构建通过 fi然后反馈给循环const result await claude.query({ prompt: 继续执行并根据 BUILD_OK 或 BUILD_FAILED 判断下一步, feedback: buildOutput });关键点在于feedback 是跟随任务循环走的每一轮的反馈都会成为下一轮的输入。Agent 看到 BUILD_FAILED会自己读取构建日志找到是哪个文件哪个语法错误导致的然后去修改然后再触发一次构建。整个过程是一个“执行 → 验证 → 反馈 → 再执行”的闭环而不是简单的“再试一次”。3.3 自愈的上限与兜底不是所有问题都该让 Agent 硬扛我也得说实话自愈不是万能的。有些错误类型模型怎么修都修不好或者说修好了也是表面功夫。比如依赖版本冲突、某些需要人工确认的业务逻辑、还有那些需要从根上重新设计的架构问题让 Agent 硬跑自愈循环只是在烧钱。我自己的做法是给自愈循环设定两个兜底出口重试次数兜底最多 3 到 5 轮超过就直接交给主代理人工介入置信度兜底如果模型连续两轮的输出内容相似度很高说明它在原地打转就直接中断判定为“当前策略失效”。这两种兜底一次都没让我白烧过钱强烈建议你也配上。4. Routine 脚本化架构把“点击流程”变成“跑一条命令”4.1 为什么你需要 Routine告别每次重新描述一遍需求说实话我最早用 Claude Code 最烦的一件事是每次做类似的操作都要重新把项目背景、目录结构、技术栈、约束条件跟它絮叨一遍。写一次还好写十次真的会让人崩溃。Routine 脚本化要解决的就是这件事——把整条工作流固化成代码以后一条命令跑完。Routine 的架构核心是一个 Node.js 脚本它调用 Claude Code 的 SDK把固定提示词、动态输入参数、验证逻辑、反馈循环全部封装起来。你只需要在命令行传参脚本会自动拉起 Agent、执行任务、返回结果。这个脚本就是你团队的“数字流水线”。比如我给自己写了一个叫 weekly-review 的 Routine每次跑它时它自动做三件事读取本周的 git log、分析修改过的模块、生成一份带风险提示的代码审查报告。以前我做这件事要在 Claude Code 里手敲五六段提示词现在一行命令十分钟变成一分钟。4.2 Routine 的标准结构提示词模板 参数输入 验证器一个成熟 Routine 脚本通常由三部分组成。提示词模板里占位符是用来接收外部参数的比如文件路径、目标模块、需求描述参数输入层负责校验用户的输入缺参就报错绝不含糊验证器则负责在 Agent 跑完后检查输出是否真的符合预期。下面我贴一个我常用的骨架它是一个“重构模块并确保测试通过”的 Routine 简化版import { query } from anthropic-ai/claude-agent-sdk; const targetModule process.argv[2]; const taskDescription process.argv[3]; if (!targetModule || !taskDescription) { console.error(用法: routine-refactor 模块路径 需求说明); process.exit(1); } const promptTemplate 你是一名资深前端工程师。请对 ${targetModule} 模块执行重构。 需求${taskDescription} 重构完成后必须运行项目测试确保全部通过。 如果测试失败请阅读失败信息、修复代码、再次运行测试最多重试 3 次。 测试全部通过后请输出重构总结。 ; let maxRetries 3; let result ; while (maxRetries 0) { result await query({ prompt: promptTemplate, options: { cwd: process.cwd() }, feedback: (message) { if (message.type result) { console.log(Agent 输出:, message.result); } } }); // 自己写一个简单的验证器 const testPassed await runTestChecker(); if (testPassed) { console.log(重构完成测试通过。); break; } else { maxRetries--; console.log(测试未通过剩余重试次数: ${maxRetries}); } } if (maxRetries 0) { console.error(重构失败连续多次测试未通过需要人工介入。); process.exit(1); }这里我特意把验证器放在 Agent 循环外面自己写而不是让模型自己判断“我重构成功了”。真实项目里模型的自评基本都是乐观的只有测试跑出来的退出码是诚实的。4.3 注册成斜杠命令让 Routine 融入日常开发流脚本写好了怎么方便地调用我推荐把它注册成 Claude Code 的斜杠命令。在项目的.claude/commands/目录下创建一个.md文件文件名就是斜杠命令名文件内容是提示词模板支持$ARGUMENTS这样的占位符。比如创建一个refactor.md请对 $ARGUMENTS 指定的模块进行重构重构完成后运行测试确保全部通过。 如果测试失败阅读失败信息并修复最多重试 3 次。完成后输出总结。这样你直接在 Claude Code 输入/refactor src/auth.ts 去掉所有 any 类型就等于把参数填进了模板里。Command 和 SDK 脚本可以互补简单的流程用 Command 就够了复杂的多步骤流程则用 SDK 脚本更合适。5. 环境搭建与基础配置从安装到接入第三方 API5.1 安装与初始化一条命令进入终端不管你是 macOS 还是 Linux只要机器上有 Node.js 18 以上版本安装就是一条命令npm install -g anthropic-ai/claude-code装完验证一下claude --version能正常输出版本号就说明装好了。首次运行claude命令时会进入授权流程按提示确认就行。这里有个我特别想提醒的点Claude Code 的配置项非常多网上很多教程写得神乎其神但最核心的就两个——项目级记忆文件CLAUDE.md和用户级配置settings.json。把这两样玩明白就足够覆盖 90% 的使用场景了。5.2 settings.json 的关键项权限、模型、白名单settings.json是 Claude Code 的全局配置文件位置通常在~/.claude/settings.json。这里可以配置默认模型、权限策略、允许的目录等。我贴一份我实际在用的精简配置{ permissions: { allow: [ Read, Edit, Write, Glob, Bash(npm run test:*) ], deny: [ Bash(rm -rf *), Bash(shutdown) ] }, model: claude-sonnet-4-20250514, env: { CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 } }permissions.allow里的每一项就是允许 Agent 执行的动作你可以用Bash(命令模式)的方式精确控制终端命令的范围。deny里则是不允许的命令模式。这套机制配合子代理的 tool 限制能给你的自动化流程加上很强的安全边界。初次上手时我建议先给大范围的 Read Edit 权限Terminal 权限慢慢加白名单用一次加一次别嫌麻烦安全这种东西全靠累积。5.3 通过环境变量接入第三方兼容 APIClaude Code 的核心引擎支持通过环境变量指定 API 地址和密钥所以你可以绕过官方账号体系直接指向任何兼容 Anthropic API 格式的服务。常用的两个环境变量是ANTHROPIC_BASE_URLAPI 服务地址ANTHROPIC_AUTH_TOKEN你的密钥以社区常用的 cc switch 这类配置管理工具为例它的核心逻辑其实就是帮你切换不同的环境变量组。比如你要接入 DeepSeek V3、通义千问 Qwen 或智谱 GLM只需要在 cc switch 里添加一个配置组填入对应的 Base URL 和 Tokenexport ANTHROPIC_BASE_URLhttps://your-api-provider.example.com export ANTHROPIC_AUTH_TOKENyour-token-here claude注意不同服务的接口格式有差异。Claude Code 默认按 Anthropic 的消息格式封装请求如果你的服务商不完全兼容可能需要额外的适配层。实操里最省事的办法是先拿一个小任务试跑确认能通再上完整项目。5.4 在 VSCode 里的使用方式Claude Code 官方提供 VS Code 插件装完之后你就可以在编辑器里直接拉起对话侧栏代码高亮、文件引用、diff 预览这些都集成得很好。我个人的习惯是终端里跑自动化脚本和 Routine编辑器里做交互式的代码审查和单文件修改。原因很简单——终端的输出是纯文本流适合程序化处理和日志记录编辑器侧栏则更适合人眼阅读 diff、逐行审阅 AI 的改动。两边的会话是共享项目上下文的但注意你的对话历史是分开的别指望终端里的上下文能无缝跳到编辑器里继续聊。6. 一个完整的多 Agent 自愈实战自动修复测试失败6.1 场景设定与流程设计我拿一个非常典型的日常场景来演示整套架构怎么协同工作项目里有一批测试挂了你需要 Claude Code 自动定位、修复并验证。整个流程分三步主代理先跑一遍测试收集所有失败用例的列表按失败涉及的模块把不同失败用例分组分发给子代理每个子代理负责一组子代理修复完成后主代理统一回归测试失败的继续反馈、继续修直到全绿或重试次数耗尽。这个流程里主代理是“项目经理”子代理是“开发工程师”自愈循环是“CI 机器人”。6.2 关键代码任务分发与结果回收用 SDK 来实现任务分发核心思路是写一个调度函数把失败分组传给多个并发执行的子任务。我简化后的代码长这样import { query } from anthropic-ai/claude-agent-sdk; async function fixTestGroup(groupName: string, files: string[], maxRetries 3) { const prompt 你负责修复测试分组「${groupName}」中的失败。 涉及文件${files.join(, )} 先运行相关测试定位失败原因然后修复代码。 修复后再次运行测试直到通过。 如果连续 ${maxRetries} 次仍失败停止并输出 FAILED 报告。 ; let retries 0; while (retries maxRetries) { const result await query({ prompt, options: { cwd: process.cwd() } }); const testOutput await runTests(files); if (testOutput.passed) { return { groupName, status: PASSED }; } retries; } return { groupName, status: FAILED, detail: 经重试仍无法修复 }; } // 主流程 const failedGroups groupFailedTests(await runAllTests()); const results await Promise.all( failedGroups.map(g fixTestGroup(g.name, g.files)) ); console.table(results);这段代码没有用任何魔法。runTests是你要自己实现的真实测试执行函数groupFailedTests负责把失败用例按模块归类。两个函数都拿到真实执行结果而不是模型自评这就是“闭环自愈”能可靠运转的根基。6.3 我在实战中总结的分组经验分组这个动作是我摸索了很久才找到最佳实践的。刚开始我把所有失败用例堆给一个 Agent 去修结果它在一个死胡同里绕了半天浪费了几万 token。后来改成按“模块归属”分组每个组一个 Agent只让它看自己那部分代码效率立刻上来了。不过分组的粒度也别太细。如果一个失败组只涉及一个文件里的一个小函数单独挂一个子代理反而浪费启动开销。我的经验值是组内文件数在 1 到 3 个之间、涉及的模块数不超过 2 个这个粒度最经济。分组太粗上下文会互相污染分组太细并行调度的开销吃掉收益。7. 常见问题与排查技巧实录7.1 子代理上下文不够用输出被截断怎么办多 Agent 编排中最常见的问题之一是子代理输出太长被截断导致返回给主代理的结果不完整。解决方案不是盲目调大 tokens而是要求子代理“精简输出中间过程只返回结构化结论”。在提示词里加一句效果立竿见影“不要输出你阅读了哪些文件、不要粘贴完整代码只用 JSON 格式输出修改了哪些文件、每个文件的关键改动、测试结果”。让子代理的输出是摘要而不是流水账。7.2 权限类问题Agent 想执行命令却被拦Claude Code 出于安全默认会拦截很多命令。遇到这种情况你会看到类似权限被拒的提示。解决办法有两个终端里用/permissions交互式添加白名单或者直接编辑settings.json的permissions.allow。千万别图省事直接放开所有命令权限自动化脚本一旦跑飞删库不是开玩笑的。7.3 第三方 API 接入后效果不佳上下文策略要单独调接入 DeepSeek、Qwen、GLM 这类第三方模型后不少人发现它们在复杂编排里的表现和官方模型不太一样。别急这非常正常。不同模型的指令遵循能力、工具调用稳定性都有差异你需要针对性地调整两个参数一是system prompt的复杂度越简单的指令第三方模型遵循得越好二是子代理的拆分粒度可能要拆得更细每个任务的指令更短执行成功率才会上去。7.4 Routine 脚本不生效环境变量与 CWD 的坑我在写 Routine 脚本时踩过最大的坑是直接在终端里能跑通换成 Routine 跑就报错。最后排查了半天发现问题出在process.cwd()上——脚本里所有相对路径都是基于当前工作目录的如果你从别的目录调用这个 Routine路径全错。解决办法脚本里始终基于import.meta.dirname定位基准路径或者调用前显式process.chdir()切到项目根目录。这个坑很隐蔽但也很典型我写出来给大家省个调试时间。7.5 自愈循环原地打转怎么判断该中断模型连续几轮输出内容高度相似测试还是不过这就是典型的“原地打转”。我上面提过方案是加一轮内容相似度判断。实操上不需要引入复杂的向量计算一个最简单的办法就够用把连续两轮 Agent 输出的最后 200 个字符存下来做比对如果完全一致果断中断换人换思路。最终坚持一个原则能自动验证的不要相信模型的自评能限权的不要给 Agent 多余能力能中断的不要让它无限重试。这三条是整套编排架构稳定运行的基石。根据我几个月的实操经验Claude Code 的这套多 Agent 编排、闭环自愈和 Routine 脚本化确实能帮你把繁琐的开发流程变成一条流水线。但它的学习曲线不是“会聊天就会用”而是“会拆任务、会设边界、会写验证逻辑”。建议你先从小项目、两到三个子代理开始跑吃透每一环再逐步加大复杂度。我自己是从一个“自动跑测试并修复”的脚本起步的后来才慢慢叠加了代码评审、依赖升级、日志分析这些 Routine现在日常开发里大概有四成重复性工作都交给 Claude Code 的编排流程在跑了。这套东西的真正上限取决于你对任务的拆解能力和对边界的把控能力祝你早日跑通第一条全自动流水线。