1. 为什么单步聊天模式注定低效1.1 单步聊天的三大痛点先说结论如果你还在把 Claude Code 当成一个高级 ChatGPT 终端来用一次一个问题、一次改一个文件那你只用了它不到两成的能力。我自己在早期就是这么干的。让它写个函数我复制粘贴到项目里跑出报错再把报错丢回去让它改改了之后再跑又报错再丢回去……一个看似简单的功能往往要来回拉扯十几轮。这个过程我称之为单步聊天模式它的效率瓶颈是结构性的不是模型能力的问题。第一上下文窗口被无效信息撑爆。每次报错、每次修改都会把新的内容塞进对话历史。而 Agent 的注意力是有限的当上下文里堆满了第 3 次修改的补丁第 7 次报错内容它对项目整体结构的感知就会变弱甚至开始出现改了 A 文件忘了 B 文件还在引用旧函数这种低级失误。第二任务粒度太粗缺乏可执行的计划。单步聊天时你给的是帮我实现登录功能这种模糊指令。模型确实能生成代码但登录功能涉及前端表单、后端接口、会话管理、数据库表、异常处理……每一步之间没有明确的依赖关系也没有验证闭环。结果就是代码能跑但改起来像在拆炸弹。第三没有自动化的验证与恢复机制。人肉来回试探的最大问题是每次失败都要你亲自介入。白天还好晚上挂着跑批量任务时一次类型错误就能让整个流程停在那里白白浪费几个小时。这三个痛点叠加在一起就会形成一个非常熟悉的场景你觉得自己在用 AI 编程实际上你在给 AI 当 DevOps帮它传递报错、检查输出、重启进程。1.2 从对话到编排的范式转换要打破这个局面必须换个视角。Claude Code 的核心能力不应该是陪你聊天而应该是独立执行任务。它原生支持多 Agent 体系可以用一个主控 Agent 去调度多个子 Agent每个子 Agent 负责一个具体的子任务也可以借助脚本化 Routine 把重复性的工作固化下来每次跑相同的流程再配合执行—检查—修复—重跑的闭环自愈机制让 Agent 在无人值守的情况下自己把问题消化掉。把这个逻辑转换过来之后我的使用方式发生了质变。我给自己定了一个原则凡是能在命令行里描述清楚的任务就不该用聊天窗口逐步交互。描述清楚 交给编排系统 等待闭环结果这才是 Claude Code 的正确用法。这篇文章我就好好拆一下多 Agent 编排、闭环自愈和 Routine 脚本化这三个架构层。每种模式我都会给出可以落地参考的配置和操作路径也会把踩过的坑一并交代清楚。2. Claude Code 多 Agent 编排架构拆解2.1 子代理与主控代理的协作模型很多人一听到多 Agent就以为要写一堆复杂框架其实 Claude Code 的多 Agent 编排核心就两个角色主控 AgentPrimary/Orchestrator和子 AgentSubagents。主控 Agent 是入口。你给它一个总目标它负责拆解任务、规划执行顺序、调用子 Agent、汇总结果。子 Agent 是执行者。每个子 Agent 有自己独立的系统提示词、工具集和上下文范围只专注于自己那一亩三分地。这个结构有点像一家公司的运作方式。主控是项目经理子 Agent 是各个职能组的工程师。项目经理不会自己写全部代码他负责拆分需求、派活、验收工程师不需要关心整个项目的所有细节只需把手里的模块做好。这样的隔离可以避免 Agent 在做后端任务时被前端无关信息干扰判断。实际使用中Claude Code 已经内置了部分子代理比如用于代码审查的 reviewer、用于执行测试的 tester。但真正让我觉得好用的是自定义子代理。通过.claude/agents/目录你可以定义自己的专属 Agent每个 Agent 用 markdown 文件描述其职责、约束和工具范围。比如我经常给重构项目定义三个子代理architect负责分析现有代码结构输出重构方案不直接改代码。它必须严格只读。migrator负责执行具体的代码迁移按 architect 的方案做增量修改。verifier负责跑测试和静态检查输出验证报告。这三个子代理在主控的调度下形成流水线。architect 先出方案migrator 照着改verifier 最后验证。任何一个环节失败主控都能拿到结构化反馈决定是重试还是换个思路。2.2 任务拆解与结果汇聚编排的实操要点多 Agent 编排的效果很大程度上取决于你怎么拆任务。我总结了三层拆解原则第一层按生命周期拆。不要一个 Agent 干到死而是分成分析—设计—实现—验证—修复等阶段每个阶段由一个或一组 Agent 负责。阶段与阶段之间有明确的交付物分析阶段交付文档设计阶段交付方案实现阶段交付代码验证阶段交付报告。第二层按模块边界拆。如果项目有明确的功能模块如用户服务、支付服务、通知服务让不同子 Agent 各自负责一个模块可以大幅减少上下文冲突。第三层按风险等级拆。高风险操作如删除数据、修改核心依赖交给带强约束的子 Agent只读任务和写任务分离。我一般会把分析任务和写操作任务分开能读的别乱写能写的先确认再动。任务拆完之后结果汇聚同样重要。Claude Code 的子 Agent 执行完后会把结构化结果返回给主控主控再汇总判断。这里有一个关键细节子 Agent 返回的结果不一定是你想要的最终产品它可能是中间产物。我通常会要求子 Agent 在返回结果中带上完成状态、改动文件清单、遗留风险三个字段。这样主控就能快速判断是继续下一步还是先处理风险。2.3 一个可落地的多 Agent 编排示例理论讲完来一个我实际用过的示例。假设我要给一个旧项目新增批量导入用户功能涉及后端接口、前端页面、数据库脚本三个部分。我先把任务交给主控你的项目用户管理后台 任务实现批量导入用户功能支持 CSV 上传、后端校验、结果预览、确认入库。 请先调用 archive_analyze 子代理分析现有代码结构再调用 backend_dev 子代理实现接口 调用 frontend_dev 子代理实现页面最终调用 db_review 子代理检查数据库脚本安全性。 全部完成后统一汇总结果。主控会按照顺序调用子代理每个子代理只拿到与自己相关的上下文片段。整个过程中主控并不需要把所有代码都塞进自己的上下文它只需要跟踪各个子代理的状态。这个模式的优点非常明显就算某个子代理生成的代码有 bug也不会污染其他子代理的执行环境。修复时只需要让负责该模块的子代理重跑一次而不是整个流程推到重来。不过有一点要提醒子代理之间的依赖关系需要你显式声明。Claude Code 不会自动推断前端要等后端接口定义好才能开发所以我在任务描述里会明确加一句backend_dev 完成后请将 API 响应格式传给 frontend_dev前端的字段定义必须与后端返回结构保持一致。3. 闭环自愈让 Agent 自己发现并修复问题3.1 自愈机制的核心逻辑闭环自愈这个词听起来有点玄但核心思想其实就是四个字反馈循环。传统开发流程是写代码 → 人跑测试 → 看到报错 → 人改代码 → 再测试。闭环自愈把这个循环里的人替换成了 Agent。Agent 执行完任务后不是直接结束而是主动运行验证工具如pytest、tsc、eslint拿到失败结果后分析根因修改代码再重新运行验证直到通过或达到最大重试次数。Claude Code 天然适合做这件事因为它拥有 Shell 工具可以直接执行终端命令。很多人的误区是让 Claude Code 生成代码然后自己手动拿回终端里跑。其实它可以自己跑并且可以根据输出结果动态调整。实现闭环自愈最朴素的方式就是在对话里给它一个循环指令类似这样请完成以下任务 1. 修改 src/api/user.ts 中的导入接口 2. 执行 npm run test:unit 3. 如果测试失败分析原因并修复代码然后重新执行测试 4. 重复步骤3直到测试全部通过或最多执行 5 次 5. 测试全部通过后执行 npm run lint 做最终检查这就是一个最基本的闭环。Claude Code 会沿着这个循环自己跑不再需要你隔几分钟看一次屏幕。3.2 基于测试反馈的循环执行要让闭环自愈有效运转前提是项目里必须有可靠的自动化测试。如果没有测试Agent 的验证就只能停留在代码能编译这个层面很多逻辑错误根本发现不了。我自己在让 Claude Code 做自愈之前会先做一件额外的事让它为现有代码补齐基础测试。这看起来多了一步但事后收益极高。有了测试之后Agent 每次改动代码都可以在几十秒内得到反馈而不是等到最后人工验收时才发现问题。在闭环循环中体验最好的一种做法是把测试反馈直接结构化。Claude Code 执行pytest之后会拿到包含错误位置的跟踪栈。它有能力自己定位到对应的源码行并做针对性修改。这里有个小技巧要求它在修改后解释改动原因而不只是贴代码测试反馈显示UserImportService 在解析 CSV 时如果某一行的邮箱格式不合法 会直接抛出 ValueError导致整个文件导入中断。 请修改 CSV 解析部分将非法行记录到 error_log 中而不是中断整体流程。 修改后重新运行测试并把修改前后的核心代码差异列出来。这个技巧之所以好用是因为它强迫 Agent 从修一个报错上升到理解一个业务约束。很多自愈失败的情况都是因为 Agent 只机械地改到测试通过但引入了新的边界问题。3.3 自愈的边界与防抖闭环自愈也不是万能的。我踩过的最典型的一个坑Agent 在测试失败后自己修了三次每次都修错方向浪费了大量时间最严重的一次甚至把不相关的模块也改了。后来我总结出几个防呆措施重试次数必须显式限制。我会在任务里写清楚最多重试 N 次N 次后如果还失败停止并输出当前状态。没有这个限制Agent 可能会无限循环下去。它每次重试都在消耗上下文和 token而且越到后面修改越激进风险越大。失败条件要提前定义。什么是最终失败不仅是测试跑不通还包括两次修改尝试之间的改动方向完全不同这种情况。如果 Agent 第一次尝试改的是解析逻辑第二次尝试改的是数据库事务说明它没有找到真正根因这时候继续重试没有意义。使用预算控制来自动停。Claude Code 里可以设置 max_think_tokens 和 max_output_tokens也可以在循环之前手动检查上下文占用。如果 Agent 已经用了大半的上下文预算就不应该再让它无限探索而是让它压缩信息、输出阶段性结论由你决定下一步方向。这些边界不是限制 Agent 的能力而是保护它不被自己的错误路径带偏。一个聪明的开发者应该像管理人类员工一样管理 Agent给清晰的目标、给足够的工具、也要设定明确的止损线。4. Routine 脚本化架构把重复工作固化成流水线4.1 Routine 是什么为什么需要它如果你只用 Claude Code 做一次性任务那多 Agent 编排和自愈机制已经够用。但如果你像我一样每周都要做版本发布、代码审查、环境初始化、依赖升级那就会发现这些工作其实都是重复的模式只是每次的项目内容略有不同。Routine 就是为这种场景设计的。简单来说它是一个预定义的脚本化流程把一连串操作步骤固定下来Claude Code 可以一键执行整个流程而不用你每次重新描述需求和约束。在我眼里Routine 的价值不亚于多 Agent 编排。它相当于把你的操作经验沉淀成可复用的资产。这就像你写了一个 shell 脚本把一堆零散的 shell 命令串联起来下次直接运行而不是重新敲一遍。一个典型的 Routine 可能包含这些要素触发条件什么时候该跑这个 Routine比如发布前必须执行输入参数任务需要的外部输入比如本次发布的版本号执行步骤按顺序执行的操作调用测试、执行构建、生成变更日志验证标准判断 Routine 是否成功的条件失败处理某个步骤失败后该怎么降级或重试4.2 脚本化 Routine 的编写与调用Claude Code 的 Routine 机制本质上是通过在CLAUDE.md或项目记忆文件中写明流程规则来实现的。你可以在项目根目录放一个CLAUDE.md把项目的 Routine 约定写进去Claude Code 每次启动时都会加载这些约定。我自己常用的做法是把 Routine 分成两级第一级是项目级 Routine写在CLAUDE.md中包含如何运行测试如何检查代码风格如何构建项目这些通用流程。这些内容不需要每次对话都重新教它它自然会遵守。第二级是任务级 Routine通过命令行参数或启动指令传入。比如我跑一个发布流程会直接输入claude 按 Routine 执行发布流程版本号 v1.4.2需要先跑全量测试、更新 CHANGELOG、打 tag、推送远端因为CLAUDE.md里已经把发布流程的步骤写清楚了Claude Code 就能自动将其展开成具体操作序列。展开之后它会按序执行并在每一步之间做状态检查。写 Routine 的时候我有一条非常重要的经验步骤之间必须有显式的状态检查点。不要只写执行构建然后发布而应该写步骤1执行 npm run build 步骤2检查 dist/ 目录是否存在且产物时间戳为当前时间 步骤3若步骤2通过执行 npm run changelog -- --tag v1.4.2 步骤4检查 CHANGELOG.md 中已包含当前版本条目 步骤5使用 git tag -a v1.4.2 打标签 步骤6确认当前分支与远端同步后推送 tag只有每一步都有一个明确的做完没有的判断标准Routine 才是可靠的否则它只会变成看起来很流畅但经常漏步骤的花架子。4.3 版本管理与复用Routine 一旦多了就要做版本管理。我给每个项目维护了一份docs/routines/目录按名称分类存放 Routine 的描述文件。每份文件包含适用场景输入参数说明步骤清单最近修改记录当 Routine 需要调整时我不会直接在CLAUDE.md里改而是先改描述文件再让 Claude Code 把变更同步到它的记忆文件里。这样做的好处是Routine 的演进有迹可循不会出现上次还能用这次莫名其妙失效了的情况。复用方面如果你的多个项目有相似的流程比如都是 Node.js 项目都跑 lint、test、build可以把公共 Routine 抽到一个全局位置再在各自项目的CLAUDE.md中通过引用方式加载。我就常备一个通用 Node 项目检查的 Routine任何新项目都能直接套用省掉了大量重复配置的时间。4.4 Routine 与多 Agent 编排的组合Routine 和多 Agent 编排并不是互斥的它们的最佳实践恰恰是把两者组合起来。我目前比较稳定的用法是Routine 定义做什么多 Agent 编排定义谁来做。一个 Routine 的步骤里可以指定某些步骤交给特定子 Agent 执行。举个例子我的安全巡检 Routine包含三步使用dependency-checker子代理扫描依赖漏洞使用code-auditor子代理做敏感信息泄露检查汇总报告后由主控判断是否需要自动修复。这个 Routine 固定了流程但每一步的实际执行者是不同的子 Agent。这样一来我不但固化了自己的操作习惯还能利用子 Agent 的专注性提升每一步的质量。如果你只做 Routine 不做多 Agent那流程是固化了但每一步的智能程度不高如果只做多 Agent 不写 Routine那每次都要重新描述任务结构Agent 的发挥不稳定。只有组合起来才能达到流程可控 执行智能的效果。5. 配置与接入常见问题实录5.1 安装与编辑器接入聊了这么多架构层面的东西最后落回实操。毕竟编排和自愈的前提是先把 Claude Code 装好、配好让它能顺利访问你的项目。官方推荐的安装方式是通过 npm 全局安装国内开发者如果网络不稳定可以设置镜像源后再安装。安装完成后命令行输入claude就能进入交互模式。但如果你要在真实项目里用建议在项目根目录执行claude这样它才能读取项目的CLAUDE.md和.claude/配置目录。VS Code 接入是另一个高频需求。我习惯用 VS Code 的 Claude Code 扩展它会自动识别当前工作区并在侧边栏显示对话窗口。配好后你可以直接在编辑器里选中代码片段让 Agent 针对选中部分做改动免去手敲路径的麻烦。配置 VS Code 扩展时有几个细节值得注意确认扩展已经连接到与命令行相同的认证账号否则两边的会话状态不互通如果公司网络有代理需要在系统环境变量里配好HTTPS_PROXY否则扩展可能会卡在初始化阶段除了官方扩展也有第三方开发的 VS Code 扩展功能各有侧重我用下来官方扩展的稳定性和指令兼容性最好。5.2 第三方模型与 API 接入技巧Claude Code 默认使用官方 API但你完全可以通过环境变量切换到底层的大模型服务。社区里常见的做法是通过ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN指向兼容接口的网关再配合claude-code-router这类工具实现多模型路由。我用过的比较顺手的方案是把请求路由到不同的本地或第三方模型服务。比如本地用 Ollama 跑 Qwen、GLM 这类开源模型或者通过自定义网关接入 DeepSeek 等 API。这样做的最大好处是成本可控日常的小任务可以用便宜的模型复杂任务再切回模型能力更强的端点。实际配置时我一般会做这几件事在~/.claude/settings.json里设置环境变量而不是每次启动临时export用模型路由工具把不同模型的请求分发到不同 endpoint并配上超时与重试策略调低本地模型的 max_tokens 上限因为本地推理速度慢过长的输出容易卡住会话。这里必须提醒一点切换模型后Agent 的工具调用能力和指令遵循能力会有明显差异。我在本地小模型上跑多 Agent 编排时经常遇到子代理忘记返回结构化结果的情况。所以如果要用多 Agent 架构尽量让所有子 Agent 使用同一个能力较强的模型避免因为模型能力参差导致编排链路断裂。5.3 常见报错排查速查表我在使用中积累了不少报错排查经验列成一张表方便你直接对照。现象常见原因处理方式安装时提示版本不兼容Node.js 版本过旧或 npm 缓存异常升级 Node.js 到 LTS 版本清 npm 缓存后重装命令执行后无响应网络连接被阻断或代理未配置检查系统 HTTPS 代理配置确认能正常访问 API 端点提示认证失败/订阅不可用账号会话过期或权限组策略限制重新登录账号检查当前账号是否具备 CLI 工具访问权限VS Code 扩展连不上命令行两个环境的认证状态不同步退出 VS Code 重开或手动在扩展面板重新认证子代理没有返回结构化结果模型对工具调用格式遵循能力不足降低模型切换频率回到官方模型或重写子代理提示词上下文被撑爆后逻辑混乱单次任务步骤过多历史信息堆积把任务拆成多个 Routine/子代理缩短单 Agent 的上下文生命周期这张表只是我个人的经验集合不可能覆盖所有场景但大部分问题都逃不出网络、认证、模型能力、上下文管理这四个方向。遇到报错时先沿着这四个维度排查通常都能找到突破口。6. 从单步聊天到架构化任务执行我的实践体会最后聊一点我自己的感受也算给刚接触这些概念的朋友一些方向上的建议。我刚上手 Claude Code 的头两周产出效率其实很低。原因不是工具不行而是我的使用方式还停留在拿它当高级问答模型的惯性里。后来我强迫自己做了三件事第一任何任务先写CLAUDE.md把项目约束、命令、测试方式都告诉它第二把重复性工作逐步改写成 Routine第三在验证环节引入闭环自愈让 Agent 自己跑测试、自己修。完成这三个转变后最直观的变化是我不用再一直守着终端看日志了。任务丢出去它自己跑测试、自己改代码、自己出报告。我只需要在关键节点做一次性验收。这种放权一开始会有点不放心但只要把验证关卡和失败边界都写好Agent 的实际表现比很多人想象中可靠。再给你一个小技巧给子代理命名时不要用太抽象的名字。命名越具体它在执行时越容易进入角色。比如叫security-reviewer比叫agent3效果好得多提醒我不要用但我们可以用文字描述其角色。这个方向还有很多可以玩的地方。我就正在尝试把 Routine 与 CI 流程打通让 Claude Code 在代码提交后自动充当 Code Review 机器人。后续等这套流程跑得更稳了我会再写一篇专门讲 CI 集成的经验。