先说我个人的一个判断Claude Code 用得好不好分水岭往往不在“会不会发指令”而在“你让它一个人干活还是给它搭一套能分工、能验货、能自动返工的机制”。早期我把 Claude Code 当高级聊天框用一个问题一个上下文来回追问代码改一行就让它跑一遍效率确实比手写快但离“自动化”还差得远。后来逐步把单次对话拆成多 Agent 编排再把验证失败后的修复动作做成循环最后把高频任务沉淀成 Routine 脚本才真正感受到它作为工程工具的威力。这篇文章不讲安装配置也不聊 prompt 技巧直接拆三层核心架构多 Agent 编排怎么组织任务闭环自愈怎么让 Agent 自己发现错误并修正Routine 脚本化怎么把一次性的成功经验固化下来。适合已经会用 Claude Code 做辅助编程、但想让它在复杂项目里自主完成更大范围工作的开发者。文中的路径、脚本片段和参数都来自真实项目实践你可以直接照着搭。1. 单步聊天的瓶颈为什么“什么问题都能答”的模式其实走不远很多人对 Claude Code 的第一印象是“很聪明什么都能聊”。但等任务复杂度上来你会发现单步聊天模式的效率断崖式下跌。这不是模型变笨了而是这种交互结构本身有天花板。1.1 单会话上下文的“注意力稀释”大语言模型的能力和上下文长度强相关但更关键的是上下文里的“信噪比”。一个会话如果从需求讨论开始中间经历了方案确认、代码片段修改、报错分析到后期真正要动工的时候上下文里已经堆了几万甚至几十万 token 的历史信息。即便模型支持超长上下文它也不可能对每一条历史信息都保持同等注意力。我做过一个对比实验在同一个会话里让 Claude Code 连续处理三个互不相关的子任务再从第三个子任务里抽取关键文件路径进行修改。结果它三次里有两次引用了旧任务的变量名还有一次确实把不相干的逻辑改了。原因很简单——早期的对话占了注意力真正重要的操作细节被淹没了。单步聊天的另一个隐性问题是用户必须为模型的每一步操作做“人工确认”。它每改一个文件你都要肉眼 review每跑一次命令你都要盯着输出判断对不对。这个“人在回路中”的确认成本在代码量小的时候不明显到了多文件重构、跨模块迁移这种规模时会反过来成为整个流程的瓶颈。1.2 三种典型的低效场景单步聊天模式通常在以下场景里明显吃瘪批量操作类任务比如要把项目里所有fetch调用替换为新封装的request方法。人工一步步确认的话几十个文件就意味着几十轮交互每一轮的等待、阅读、判断都会累积大量时间。跨文件依赖类任务比如修改一个公共函数签名所有调用方都要跟着变。单会话模式改完定义后还要手动提醒“现在去改其他文件”而且很容易漏。稳定复现类任务比如“按公司规范对新代码做 lint、跑测试、整理 import 顺序”。这种任务流程固定但每次都要重新描述一遍需求既消耗时间又容易描述不一致。这三类场景的共同点是它们并不需要“高智商”需要的是“稳定的流程执行能力”。流程一旦稳定下来就应该脚本化执行一旦批量起来就应该并行化。而单步聊天恰恰在流程和批量上毫无优势。1.3 瓶颈的本质把 Agent 当成了聊天对象而不是执行单元一句话总结单步聊天模式把 Claude Code 当成“脑子里有完整上下文的私人助理”但工程实践告诉我们它更像一个“交给它的上下文质量决定产出质量的执行单元”。你给它全局上下文它就全局思考你给它子任务和限定工具它就更专注、更可控、更可并行。所以接下来要做的事情很清晰把大任务拆成多个子任务每个子任务交给独立的 Agent 上下文让它们并行或按依赖关系执行再汇总结果。这就是多 Agent 编排的起点。2. 多 Agent 编排的逻辑Claude Code 如何把一次大型任务变成一支任务团队多 Agent 编排不是让多个 Claude Code 实例同时跑同一个任务而是把一个大型任务拆解成若干有边界的子任务每个子任务由一个独立的 Agent 上下文承载通过主从关系、并行关系和依赖关系组织起来最终合并成一个结果。2.1 Subagent 机制主从协作的基本单元Claude Code 的 Subagent 机制可以理解为主 Agent 的“分身”。主 Agent 负责接收用户需求、拆分任务、协调进度子 Agent 负责执行某个具体的、边界清晰的子任务。每个子 Agent 有独立的上下文窗口、独立的工具权限甚至可以用不同的 prompt 角色定义来约束行为。实际操作中我会为重要任务定义专门的 Subagent 角色。比如下面这个{ name: refactor-executor, description: 负责执行指定范围内的代码重构不改变功能语义, system_prompt: 你是资深重构工程师。你的任务是按用户提供的重构方案修改代码严格遵守以下约束1. 只修改方案中明确列出的文件2. 不改变功能逻辑3. 修改完成后运行相关测试4. 如果发现方案有问题返回结构化错误报告。, tools: [read_file, edit_file, bash, grep] }关键在于tools的限定。子 Agent 不应该是“所有工具都能用的通用 Agent”而是“只拿到完成任务必要工具的执行单元”。如果重构子任务只需要读写文件和跑测试就不要给它执行任意命令的权限。权限边界就是风险边界Agent 不会主动自我约束你要在系统层面替它约束。2.2 三种编排拓扑并列、串行与主从分发我把实践中常用的编排方式归纳为三种拓扑按场景选型拓扑适用场景优点缺点并列编排多个互不依赖的文件或模块需要分别处理吞吐量大多个子 Agent 同时跑无法共享上下文结果合并成本高串行编排前一个任务的输出是后一个任务的输入逻辑清晰阶段划分明确总耗时线性累加主从分发主 Agent 拆任务子 Agent 执行并回报灵活、易扩展主 Agent 集中裁决主 Agent 可能成为瓶颈实战中最常用的是“主从分发 局部分组并行”。主 Agent 先读取项目结构、理解需求然后把一组相互独立的文件分配给多个子 Agent 并行处理等到所有子任务返回后统一 review。如果某个子任务失败主 Agent 再把失败信息打包给一个新的子 Agent 修复而不是自己接手。这里有一个容易犯的错把串行步骤错误地并行化。比如“底层模块升级—上层模块适配—整体测试”这个链路三步之间有严格依赖强行并行只会造成大量冲突和无效劳动。判断标准很简单两个子任务是否同时读写同一组文件是的话不能并行。2.3 编排时的上下文与 Token 分配策略多 Agent 编排最大的隐藏成本不是时间而是 Token。每个子 Agent 都有独立的上下文窗口如果每个子任务都把整个项目背景塞进去Token 消耗会成指数级上升。我的分配策略是“按需注入上下文层”全局层主 Agent 持有项目结构、需求文档、全局约束只注入一次。任务层子 Agent 持有子任务涉及的文件列表、依赖关系、判定标准。执行层命令输出和工具返回只保留与当前步骤相关的片段不保存完整输出。实际执行时我会用grep、read_file这类精准工具替代“让 Agent 自己逛目录”。有一次跑跨模块重构我把整棵目录树给子 Agent结果它花了很长时间浏览无关文件Token 消耗比预期多了 40%但产出质量并没有提升。之后我改成了显式文件清单效率立刻上来了。记住一个原则子 Agent 的上下文里一行的无用背景信息都是浪费。宁可让主 Agent 多花点时间做信息筛选也不要让每个子 Agent 重复读一遍全项目。3. 闭环自愈让 Agent 具备“做完一件事之后自己验货返工”的能力编排解决的是“任务怎么分”自愈解决的是“质量问题怎么办”。先说结论如果 Agent 做完任务后没有一个自动验证和反馈的闭环那它本质上是“单程执行”一次输出产生活一次结果的概率并不会因为你用多 Agent 而变高。真正把成功率拉上去的是这个闭环。3.1 自愈闭环的三个阶段执行、校验、反馈一个标准的闭环可以拆成三个环节执行Agent 按任务要求修改文件、运行命令、生成产物。校验用自动化手段确认执行结果是否符合预期。校验手段不是“让 Agent 自己看”而是跑实际命令比如npm test、go build、eslint、tsc --noEmit。反馈把校验失败的错误输出、失败路径、相关代码上下文重新注入给 Agent让它在下一轮修复中知道发生了什么而不是凭猜测重试。这三个环节形成一个循环。循环能自愈靠的是第三步反馈的质量。反馈越精准Agent 下一步修复命中率越高反馈越模糊它越可能做无用功。3.2 在 Claude Code 中搭建自愈循环的可行方案Claude Code 提供了 Hook 机制可以在特定事件后触发外部脚本。我用它搭建过两条自愈链路分别处理“命令执行失败”和“测试不通过”两种场景。链路一命令失败自愈在工具执行后拦截退出码如果非零把 stdout/stderr 截取后作为临时上下文文件让主 Agent 读取并修复#!/usr/bin/env bash # post_tool_use.sh # 配合 Claude Code 的 PostToolUse Hook 使用 EXIT_CODE$1 TOOL_NAME$2 OUTPUT_FILE$3 if [ $TOOL_NAME bash ] [ $EXIT_CODE -ne 0 ]; then # 截取最近 30 行错误输出写入诊断上下文 tail -30 $OUTPUT_FILE /tmp/cc_diagnostic.log echo 命令执行失败诊断信息已写入 /tmp/cc_diagnostic.log主 Agent 应读取并修复。 fi这套方案的精髓在于不让 Agent 自己决定“要不要看错误”而是强制把失败信息放到它眼前。很多人说“自愈不好用”多半是因为漏了这一步——Agent 在下一轮重试时根本不知道上一轮为什么失败而你又没有主动喂给它的机制。链路二测试驱动修复另一条链路更接近 TDD 的思路。Hook 在 Agent 完成一轮修改后自动执行测试命令如果失败将测试报告、失败用例、相关源码路径组合成一个结构化反馈块追加到对话上下文然后让 Agent 修复后重新触发测试。{ hooks: [ { matcher: stop, hooks: [ { type: command, command: ./scripts/auto_verify.sh, timeout: 120 } ] } ] }3.3 自愈的终止条件与防抖动设计自愈循环最大的风险是“永远修不好但永远在修”。要在工程上让循环可控必须设计终止条件和防抖动机制。我的经验是设置三个信号任何一个触发就跳出循环最大迭代次数一般设 3 或 5 轮。超过这个次数说明当前方案或者任务拆解本身有问题继续自动修复只会浪费 Token。失败模式重复如果连续两轮的失败原因属于同一个类别比如都是同一个文件的类型错误说明 Agent 陷入了局部循环应该回到主 Agent 层面重新规划而不是继续修。代价预算为一次循环设置 Token 上限达到后强制人工介入。这一步容易被忽略但很重要它保证了成本失控时有一个紧急刹车。防抖动方面我会在反馈信息里要求 Agent“不修改与本次失败无关的代码”。没有这个约束Agent 可能顺手优化了旁边一个函数结果引入新的问题你再修下去就飘了。实测下来有了这个闭环Claude Code 在多文件修改任务里的“一轮通过率”变化不明显但是“三轮内通过率”可以从不到一半提升到七成以上。这个提升的來源不是模型变强了而是失败的每一次都被有效利用没有浪费。4. Routine 脚本化架构把经过验证的工作步骤沉淀为可复用资产多 Agent 编排和自愈闭环解决了“一次复杂任务”的执行问题但它们还停留在“每做一次任务都要重新搭一套流程”的阶段。真正想提高长期效率需要把高频、稳定、可预期的操作流程固化下来。这就是 Routine 脚本化架构的定位。4.1 从 CLAUDE.md 到 Routine 的演进很多团队喜欢把规范写进 CLAUDE.md让 Agent 每次启动时自动读取。这是一个好的基础但 CLAUDE.md 本质是“静态知识”它说的是“你应该怎么做”。当这个“怎么做”涉及一连串工具调用、多轮验证、固定产出格式时光有知识是不够的还需要把它变成“可执行的动作序列”。我的做法是把流程中“变化的部分”和“不变的部分”分离。不变的部分——比如代码格式化规则、测试命令、提交信息模板——固化成 Routine变化的部分——比如本次改动的文件范围、要解决的问题——作为 Routine 的参数输入。一个典型 Routine 的输入输出结构是这样定义的name: athena_script_refactor_routine description: 执行一次范围受控的脚本重构包含测试验证与回滚保护 inputs: target_files: string[] refactor_plan: string test_command: string outputs: result_summary: string changed_files: string[] test_report: string stopping_conditions: max_iterations: 3 no_unrelated_changes: true4.2 用自定义斜杠命令把 Routine 固化Claude Code 支持用户自定义斜杠命令把一段精心设计的 prompt 和工具调用序列封装成一个命令。这是我认为最接近“Routine 脚本化”原生实现的方式。以一个“安全重构执行器”为例我会在项目.claude/commands/refactor.md里写这样一段--- description: 按指定方案执行安全重构自动验证回归 argument_hint: 目标文件或模块路径 allowed-tools: read_file, edit_file, bash, grep --- 你是一名重构执行引擎。本次任务的约束如下 1. 只允许修改用户指定的目标文件禁止修改其他文件。 2. 开始前先读取目标文件理解当前实现。 3. 按用户提供的重构方案修改保持功能语义不变。 4. 修改完成后运行用户指定的测试命令收集输出。 5. 如果测试失败读取错误信息只针对失败原因修复禁止顺带调整无关代码。 6. 最多修复 3 轮超过后停止并输出结构化报告。 7. 最终输出文件变更列表、测试结果摘要、剩余风险。 目标文件 {{目标文件}} 重构方案 {{用户输入}}这里有三个关键设计allowed-tools 显式限制工具范围防止 Routine 执行期间 Agent 调用与任务无关的工具。模板变量{{目标文件}}预留输入接口让不同任务复用同一套流程。第 5 条和第 6 条规定了自愈的边界和上一节的终止条件设计保持一致。这套方法最大的收益是“行为确定性”。同一个 Routine 在不同时刻调用执行路径是稳定的产出格式是统一的。我在项目里沉淀了四五个这样的 Routine 之后日常重复性开发任务的介入成本几乎只有“填参数 review 结果”。4.3 把 Routine 当成代码维护输入、输出、版本Routine 目前最被低估的价值在于“它是可以版本化的工程资产”。一个写好的 Routine 可以跟着项目代码走进入团队知识库经历 review、迭代、废弃和普通代码的生命周期完全一致。所以我建议从第一天就用代码规范管理 Routine写在仓库里.claude/commands/目录随项目版本库管理不放在个人笔记里。明确定义输入输出每个 Routine 必须有description、input、output和stopping_conditions否则它只是另一个 prompt。用真实用例测试 Routine每次修改 Routine拿一个已知的小任务跑一遍确认输出符合预期再放进正式流程。这套维护方式看起来很朴素但它决定了 Routine 能不能长期用下去。我见过太多团队写了 prompt 不验证、不迭代过几个月 prompt 失效了也浑然不知。对待 Routine要像对待自动化测试一样它需要维护也值得维护。5. 一个贯穿三者的实战案例自动化 Bug 修复闭环讲完三块架构用一个真实场景把它们串起来。这个案例是我在项目里做过的一次“自动化 Bug 修复 回归验证”流程所有关键环节都包含了编排、自愈和 Routine 三者的配合。5.1 任务背景和拆分项目背景是一个 JavaScript 服务端项目有大约 80 个文件。线上反馈一个 Bug某旧接口返回的数据结构中status字段从字符串改成了数字但前端和服务端内部多个调用方仍按字符串处理导致逻辑判断出错。我接到任务后没有直接丢给 Claude Code“请修复这个 Bug”而是先在主 Agent 上下文里做任务拆解定位涉及status字段的全部文件和代码位置。确认新旧数据结构的差异细节。修改服务端内部判断逻辑。修改调用方传参逻辑。更新相关单元测试。跑全量测试确认。其中第 3、4、5 项有先后依赖第 1、2 项是只读分析任务。我让主 Agent 先并行启动两个子 Agent 分别做定位和差异分析等结果返回后再由一个执行子 Agent 按分析结果统一修改最后走测试自愈循环。5.2 编排执行过程与中间产物执行过程大概是这样的子 Agent A定位任务返回了一份文件列表里面标注了每个文件里status的引用位置和使用场景。子 Agent B差异分析确认了新旧类型映射关系输出了一段类型映射说明。主 Agent 汇总 A 和 B 的结果加上我给定的约束只改status相关逻辑生成一份重构方案。执行子 Agent C 按照方案修改文件并且在修改完成后自动触发一次npm test。这一步里Hook 机制在测试失败后把错误日志传给主 Agent主 Agent 分析失败原因再回到子 Agent C 修复。整个过程中我只在开始时提供了任务描述中间没有任何人工干预。5.3 Token 成本与时间对比为了让你有个直观体感放一组数据对比基于我当时的真实项目方案总耗时总 Token 消耗人工介入次数结果单步聊天手动指导约 1.5 小时约 35 万 token8 次以上一次测试通过但遗漏了两处调用方多 Agent 编排约 20 分钟约 22 万 token1 次只做最终 review全部调用方覆盖测试通过Token 消耗反而比单步聊天低原因是子 Agent 上下文干净没有大量历史闲聊信息也没有因为上下文混乱导致的重复操作。人工介入次数从 8 次降到 1 次这个差距直接决定了整个流程是否真正“自动化”。6. 实践中的踩坑记录与我的补救方案路由、编排、自愈这套架构听上去设计很完整但实际跑起来还是踩过不少坑。下面几条是我的真实踩坑记录和对应的补救方案按频率和严重程度排序。6.1 并行子 Agent 之间的隐性耦合第一次跑并行子任务时两个子 Agent 被分到了同一目录下不同的文件。表面上它们互不相关但两个 Agent 同时修改了同一个模块的 import 语句合并时产生了冲突第二次只改了部分内容主 Agent 发现测试报错后又重新跑了一遍修复白白浪费了一轮循环。教训是判断子任务能否并行不能只看“文件是否不同”还要看“它们是否共享同一个依赖模块”。补救方案是在任务分配前加一道检查把共享同一组依赖文件的任务强制串行化。我把这个检查写进了 Routine 的输入要求里之后没有再遇到过同类问题。6.2 自愈循环失控的止损办法有一次自愈循环跑了两轮之后修复方案明显偏向“换一种写法碰运气”而不是基于错误日志做理性分析。问题出在反馈机制上当时的错误日志太长喂给 Agent 的信息超过了它能有效处理的量Agent 反而开始“自由发挥”。补救方案是强制做信息压缩。Hook 脚本里加入一段逻辑对测试错误只提取失败用例名、失败断言行、预期值和实际值把完整日志丢弃。压缩后 Agent 的下一轮修复命中率高了很多。这也印证了前面说的反馈信息要精不要多Agent 不是信息越多越聪明。6.3 Routine 过度抽象的教训我也走过另一个极端试图把一套非常通用的“任意任务执行器”Routine 做出来参数可以传任何目标文件、任何方案结果它的执行效果不稳定反而比直接用主 Agent 还难用。原因很简单Routine 越通用约束就越少约束越少Agent 的自由度就越大行为就越不可控。Routine 的价值在于“把高频、稳定的流程固化”它天然适合窄场景。如果你的场景需要大量自由判断和复杂决策那它更适合用多 Agent 编排来做动态规划而不是硬塞进一个 Routine 里。后期我把每个 Routine 收窄到“一个 Routine 只解决一种任务”例如“安全重构”“全量测试失败修复”“格式化与提交前检查”。窄之后每个 Routine 的 prompt 都可以把规矩写得很细稳定性立刻上来了。6.4 给模型版本和工具版本上保险最后一条经验比较隐蔽但非常重要多 Agent 编排和自愈循环的效果高度依赖模型版本的一致性。同一个 Routine在模型 A 上表现稳定在模型 B 上可能因为输出风格差异导致格式解析失败。如果你的流程里有用脚本解析 Agent 输出的环节比如解析结构化报告一定要固定模型版本并在升级时做一轮回归验证。工具版本也一样。Claude Code 自身的命令输出格式、Hook 事件名可能随版本调整升级后不要直接跑生产流程先跑一遍最小用例确认兼容。我在团队里定的规矩是Routine 文件的首部必须记录“最后验证日期”和“验证使用的模型版本”。半年下来这条规矩帮我们避免了好几次“自动化流程莫名其妙失效”的排查灾难。另一个值得提的小技巧把每个 Routine 的验证结果留档在 commit message 里。比如“refactor routine v3 verified on claude-sonnet-4-20250514”。这样将来任何时候翻 git 历史都能追溯到一套可用的组合。自动化编排和自愈闭环这套体系目前已经成了我在所有中等规模以上项目里的默认工作方式。它不会让每个任务都成功但它能让失败的代价变得可控让成功的经验可以沉淀和复用。对我个人而言这是 Claude Code 从“聊天工具”变身为“工程执行平台”的关键一步。如果你现在还在用单步聊天模式逐一交互我建议找一个中等规模的重构任务按文章里的思路先搭一个最小闭环一个主 Agent两个并行子 Agent一条 Hook 驱动的测试反馈链路。跑通一轮之后你会立刻感受到“批量、并行、自动验货”和“逐条聊天”在效率和体验上的差距。