我最初用 Claude Code其实只是把它当终端里的“升级版聊天框”。问一句答一句代码只出建议执行全靠我复制粘贴一个中大型重构经常被我拆成几十轮对话上下文越聊越碎改完 A 模块又弄坏 B 模块。直到我把思维从“单步聊天”切换到“多 Agent 编排、闭环自愈、Routine 脚本化架构”之后才意识到之前浪费了多少时间。这篇文章把我实际摸索出来的工作方式完整写出来包含安装配置、直接执行终端命令的权限边界、多 Agent 任务拆解、自动修复循环的落地条件以及用 cc-switch 接入 DeepSeek、Qwen、GLM 这类第三方模型的具体做法适合正在用或准备用 Claude Code 做自动化开发、批量重构的工程师。1. 单步聊天的天花板为什么我被迫研究多 Agent 编排1.1 “一问一答”模式在真实工程里的三宗罪我印象最深的一次踩坑是给一个旧支付模块做重构。起初对话很正常Claude Code 给了我一段修改建议我复制进项目编译通过接着问“下一步”它又给了一段建议。但到了第六七轮它已经记不清前面改过哪些文件了反复重复同一个路径甚至建议我再改一遍已经改好的函数。最后我只能新建会话把十几个文件的内容重新贴进去再要求它从头分析。这种工作方式的问题非常典型上下文不断被截断。单次会话窗口有限聊得越多最早的约束、变量名、业务规则就被挤得越远。一旦上下文不完整大模型就成了一个“记忆只有十分钟”的临时工。没有全局任务视角。你问它“下一步做什么”它只能根据现有会话推断下一步无法像项目负责人一样维护一张任务总表更谈不上主动推动多个子任务并行。执行和验证严重脱节。代码改完没有立即跑测试测试失败又得重新粘贴报错再让它分析整个循环低效到让人不想用第二次。这不是模型能力不够而是使用方式本身就有问题。我们需要的不是让 Claude Code 一次性回答更大的问题而是把一个大型任务拆成可验证的小块让它自己调度、自己执行、自己看结果、自己修正。这就是后面要展开的三件事多 Agent 编排、闭环自愈、Routine 脚本化。1.2 编排、自愈、脚本化其实是一个整体很多教程喜欢把这三个概念分开讲但我用下来发现它们必须组合起来才有真正的工程价值。多 Agent 编排解决的是“任务怎么拆、怎么派、结果怎么汇总”的问题。类似大项目里的模块负责人把需求拆成可并行的子任务。闭环自愈解决的是“拆出去的子任务失败了怎么办”的问题。每个子 Agent 执行完命令后要能读取报错、修复代码、重新运行测试形成一个持续反馈的循环。Routine 脚本化解决的是“同样的流程下次还要重复跑一遍怎么办”的问题。把经验固化成一套可复用的脚本和步骤以后直接触发而不是每次重新教一遍。我用一个厨房的例子来说明你一个人又要洗菜又要切菜又要炒菜还要刷锅这是“单步聊天”一个后厨团队里配菜组只负责备料热菜组只负责炒洗碗工只负责收盘主厨统筹整条出餐线这是“多 Agent 编排”炒糊了立刻倒掉重新做而不是等客人投诉这是“闭环自愈”把整套后厨流程写成标准作业手册新人照着做就能出餐这是“Routine 脚本化”。Claude Code 真正值钱的地方就是这三种能力可以叠加在同一个工作流里。2. 环境地基Claude Code 在 VS Code、Ubuntu、macOS 上的安装与配置2.1 三种安装形式到底怎么选很多人在安装阶段就会被各种渠道搞混因为 Claude Code 并不是只有一种打开方式。目前主流的三种形态是形态安装方式适用场景更新方式适合人群命令行终端npm 全局包自动化脚本、CI、SSH 远程开发claude update或 npm 更新喜欢终端工作流、要跑自动化任务的开发者VS Code 插件插件市场安装IDE 内开发、边看代码边对话插件市场更新习惯可视化界面的前端、后端工程师桌面版官方安装包不想折腾终端、窗口化使用官方更新非深度开发者、产品经理、运营人员我最推荐的是“命令行终端 VS Code 插件”组合。因为 Claude Code 真正强大的地方是直接执行终端命令纯聊天界面根本发挥不出它的价值。终端形态也方便写脚本、接入自定义 workflow甚至直接在服务器上跑。安装前先确认 Node.js 环境没问题建议 LTS 版本而不是最新开发版不然 npm 装包的时候容易出现兼容警告。node -v npm -v然后全局安装npm install -g anthropic-ai/claude-code装完验证一下claude --version如果以后要升到最新版本我一般直接用claude update2.2 VS Code 插件配置里容易被忽略的字段VS Code 插件接入 Claude Code 之后很多配置不是写在插件界面里的而是落到 Claude Code 的配置文件里。常见的路径是用户目录下的.claude文件夹里面会有settings.json这类配置文件。我建议重点关注几个字段权限模式决定是否允许 Claude Code 自动执行命令、是否每次都要弹窗询问。允许命令列表只放日常开发中用到的安全命令比如测试、构建、lint。工作目录打开某个项目时默认的启动目录必须明确避免它跑到无关目录里去执行命令。模型选项指定默认模型也可以留空让 CLI / 插件自动判断。我踩过的坑是改了插件配置之后没有重启 VS Code导致配置一直不生效。这类配置文件的变更很多时候不像普通设置那样热更新重启窗口是最快的验证方式。2.3 Ubuntu 和 macOS 安装时的常见环境问题Ubuntu 上最常见的报错是安装成功之后找不到claude命令。这通常是因为 npm 的全局 bin 目录不在 PATH 里。解决办法不是去chmod某个奇怪路径而是把 npm 全局 bin 加进 PATHexport PATH$(npm prefix -g)/bin:$PATH source ~/.bashrcmacOS 上更多是系统权限拦路。第一次运行 Claude Code 时如果它要写文件、执行终端命令系统会弹安全确认。这一步别直接点“始终允许”后不管要看清它到底要访问哪个目录。我习惯在独立项目目录里测试而不是让它访问整个用户目录。另外要提醒一句如果你在公司电脑上安装最好先确认安全策略是否允许不要为了绕过限制去改系统级配置这既不稳定也不安全。3. 直接执行终端命令的能力边界从“问答工具”到“行动者”3.1 执行命令才是自动化工作流的起点很多人的误区是把 Claude Code 当成一个“代码解释器”只输出建议人工再去执行。但 Claude Code 的核心能力之一是直接调用终端命令跑测试、看输出、读错误、改文件、再跑测试。这一条链路打通之后它才真正从一个问答工具变成一个自动化执行者。我举个例子。以前我遇到测试失败要手动把终端的报错复制给 Claude Code让它分析它给出修复建议我再改代码再跑测试循环往复。现在流程变成Claude Code 自己跑测试自己读输出自己改代码自己重新跑测试。我要做的只是设定边界和验收条件。3.2 权限设计不是所有命令都应该无脑放行Claude Code 默认执行危险操作前会请求确认但从工程效率角度我更倾向于把安全的命令加入白名单把高风险命令加入黑名单而不是让它在每个git status上都停下来问我。我个人常用的配置思路如下{ permissions: { allow: [ npm test, npm run build, pytest, git status, git diff, git log --oneline ], deny: [ rm -rf *, sudo *, git push --force, DROP TABLE ] } }这里面的逻辑是我只放行那些“可观察、可回滚、低风险”的命令。可观察命令执行完有明确输出Agent 能读取输出判断成功与否。可回滚改了代码可以git checkout退回不会造成不可逆影响。低风险不会删除生产数据、不会覆盖远端分支、不会以管理员权限执行未知操作。如果你一上来就允许“自动接受所有命令”Claude Code 就可能在你不知情的情况下执行rm -rf或者把本地分支强推到远端。这个风险不是它不够聪明而是你没有给它设置足够清晰的边界。3.3 从“执行命令”到“闭环自愈”的跳跃执行命令本身并不能带来多少收益真正的收益来自“执行后观察结果、根据结果调整行为”的循环。当 Claude Code 跑完测试发现失败它能自动从错误栈里提取线索找到对应代码文件修改逻辑再跑测试验证这时候就形成了一个闭环。我把这个闭环称为“自愈”的最小单元触发 → 执行 → 检测 → 修复 → 回归。后面专门用一整章来讲但它的地基一定是第 3 章的直接执行能力。没有命令执行权限自愈循环就是空谈。4. 多 Agent 编排的工作机制任务拆分、上下文隔离与结果合并4.1 为什么要用多个 Agent 而不是一个大对话单次对话最大的瓶颈是上下文窗口和注意力聚焦。你把“重构整个订单服务”这种需求丢给一个大 Agent它在处理订单数据库模型的时候很容易被前端展示逻辑干扰。多 Agent 编排的核心思路是把一个大型任务拆成多个相对独立的子任务每个子任务由单独的 Agent 负责外面再有一个主控 Agent 做分配和汇总。这个方法之所以有效不只是因为并行快更重要的是上下文隔离。每个子 Agent 只需要关注自己的任务描述和对应文件不必把整个项目都塞进上下文。这就像让后端工程师只看后端代码、前端工程师只看前端代码一样注意力集中了准确率自然上升。4.2 我在一次旧项目重构里使用的编排思路我有一次要把一个老项目从自定义文件上传逻辑迁移到对象存储任务涉及前端上传组件、后端接口、数据库字段、异步任务队列四个部分。如果单线程一个个改很容易改完前端忘了后端。我当时的执行框架是这样的主控 Agent先分析项目结构输出任务清单并把四个模块分别定义为四个子任务。前端 Agent负责替换上传组件修改上传成功回调不碰后端代码。后端 Agent负责修改接口签名和存储逻辑不碰数据库结构。数据层 Agent负责新增字段迁移脚本并检查旧数据兼容。任务队列 Agent负责异步处理的改造和前端/后端通过约定好的接口文档对接。最后验证 Agent统一跑测试、检查接口联调、生成变更报告。每个子 Agent 拿到的是一个明确边界的小任务而不是“帮我全部搞定”这种模糊指令。最终结果由主控 Agent 合并如果有冲突它再协调相关 Agent 重新处理。这种编排特别适合这些场景适合多 Agent 编排不适合多 Agent 编排跨多个模块的大重构简单回答一个技术问题依赖链复杂、需要并行验证项目只有两三个文件需要重复执行的工程流程需求本身还没明确一次改动影响多个服务只改一个文案、调一个参数4.3 子任务结果合并时的冲突处理多 Agent 并行之后最大的坑不是并行本身而是合并结果时的冲突。两个 Agent 同时改了同一个文件或者一个 Agent 改了接口名另一个 Agent 还在用旧接口名调用。我的处理经验是每个子 Agent 输出时不只是返回文字总结还要产出明确的变更文件列表和 diff。主控 Agent 必须做一次“交叉检查”对一起改动的文件逐一确认解决顺序后再合并。如果项目里没有严格的模块边界就不要强行并行串行反而更安全。另外上下文隔离也不是完全不共享信息。子 Agent 之间需要一份“统一契约”比如接口定义、数据结构、变更规范。这份契约最好单独写到一个文件里让所有子 Agent 都能读取而不是靠对话传递。5. 闭环自愈从报错到修复再到验证的三个阶段实践5.1 闭环自愈的本质是“三阶段循环”闭环自愈听起来很玄其实拆开就是三个阶段的循环执行验证 → 失败诊断 → 修复回归。执行验证运行测试、构建、lint得到明确成功或失败信号。失败诊断读取错误日志、堆栈信息定位到文件和原因。修复回归修改代码重新执行验证直到通过或者达到迭代上限后停止。这个循环看起来简单但落地时的细节决定成败。5.2 我在 CI 循环里用的简版自愈框架下面这段不是某个 CLI 工具的直接语法而是我在自动化脚本里模拟“Claude Code 自愈循环”的思路。重点看结构不要把它当成万能命令行直接粘贴因为不同版本的 CLI 参数可能有差异。for attempt in {1..5}; do pytest result.log 21 if grep -q FAILED result.log; then claude -p 请读取 result.log定位失败用例修复代码中导致失败的问题不要修改测试文件修复后重新运行 pytest 验证。 else echo success break fi done这个循环里有几个被很多人忽略的约束第一限制了最大尝试次数。没有上限的话Agent 可能会在一个简单的逻辑错误上反复打转白白消耗大量 token。第二要求不要修改测试文件。这是自愈里最容易出问题的地方Agent 发现单测失败后可能会“机智”地把单测断言给改软让测试暴力通过。这种假修复会直接毁掉测试的价值。所以我在自愈指令里明确禁止改测试代码。第三把结果输出到日志文件再读取。相比直接在终端里抓取输出日志文件更适合多轮分析Agent 可以反复读取不会因为终端滚动丢失信息。5.3 自愈不是万能的什么情况会越修越糟我踩过的几个坑值得单独列出来只修表面症状。错误信息指向某个空指针Agent 加了一个 if 判断绕过但实际上数据流向本来就错了根因在后面一层。反复修同一个问题。测试用例并没有覆盖真正出错的分支Agent 改完代码跑了同一批用例全部通过就认为修好了其实问题还在。改动扩散到无关代码。自愈循环里没有加“最小改动”约束Agent 为了通过测试顺手重构了旁边的模块。所以我在自愈场景里一定会加三条规则改动限定在错误日志关联的文件范围内超出范围必须先汇报。修复之后必须跑完整测试集而不是只跑单个失败用例。连续两次修复后仍然失败立即暂停把现场情况交给人工判断。哪怕 Claude Code 能力再强自动修复也只是用来处理那些“有明确失败信号、有确定修法”的问题。像需求理解错误、产品逻辑不清晰这类问题放进自愈循环只会越修越乱。6. Routine 脚本化架构把高频重复任务变成可复用剧本6.1 Routine 和普通 Prompt 的区别在哪普通的 Prompt 是你临时提的需求比如“帮我看看这个模块怎么优化”。Routine 则是一套结构化的可复用流程它包含任务目标、工作目录、执行步骤、验收标准、失败处理方式。说白了Prompt 是一次性的对话Routine 是沉淀下来的操作手册。我最先开始做 Routine是因为每次新项目初始化都要重复一套动作创建目录结构、初始化 git、安装依赖、配置 lint、生成 README。这些事情每次让 Claude Code 临时想一遍既浪费时间结果还不稳定。后来我把它写成一个 Routine 文件每次只需要触发它就会严格按步骤执行。6.2 我的 Routine 目录长什么样我在.claude目录下维护了一套私有 Routine 库按场景分目录~/.claude/routines/ ├── release/ │ ├── 00_check_env.sh │ ├── 01_bump_version.sh │ ├── 02_run_tests.sh │ ├── 03_update_changelog.sh │ ├── 04_build.sh │ └── 05_publish.sh ├── new_project/ │ ├── init_git.sh │ ├── setup_config.sh │ ├── install_deps.sh │ └── create_readme.sh └── daily/ ├── update_deps.sh ├── run_lint.sh └── generate_report.sh每一个脚本对应一个明确的步骤。这样设计的好处是当某个步骤失败时Claude Code 可以只处理那一个脚本而不是把整个 Routine 从头跑一遍。失败处理也可以直接复用第 5 章的闭环自愈逻辑。6.3 Routine 与多 Agent 编排的经典组合Routine 不是只能串行跑它也可以作为编排中的一个节点。拿我最常用的“依赖升级日”来说编排 Agent 先检查项目依赖列表生成一份需要升级的清单。分析 Agent 评估每个依赖的 breaking change 风险把高风险项标记出来。升级 Agent 按风险从低到高逐个升级每升级一个就跑一遍测试。测试 Agent 负责全量回归发现失败就调用自愈循环修复。最后报告 Agent 把升级结果、失败项、修复情况汇总成一份文档。这套流程单靠任何一个 Agent 都做不完但组合起来之后我只需要在工作日早上触发一次所有升级和回归都是自动完成的。这就是我理解的“Routine 脚本化架构”它不只是保存几个脚本而是把一套工程方法论固化成了能自动执行的流程。如果团队使用我还会把 Routine 目录放进 Git 仓库这样不同成员可以 review、讨论、迭代这套流程。Routine 本身也应该像代码一样经过 review因为它直接影响自动化执行的行为。7. 兼容性实战cc-switch 接入 DeepSeek、Qwen、GLM 以及第三方 API 的正确姿势7.1 为什么要在 Claude Code 里接其他模型官方模型质量固然好但实际工程里会有几个现实问题成本预算、不同任务对模型能力的不同要求、以及团队内部已经部署了其他模型网关。我自己的习惯是简单任务走轻量模型复杂重构和代码审计才用更高质量的模型。这种诉求下就需要一个能切换模型的方案。cc-switch 是我在社区里看到的方案它可以管理多个模型供应商配置在 Claude Code 的调用层做切换接入 OpenAI 兼容接口的模型。用之前必须明确一点它不是官方工具使用时要自己评估风险。尤其是 API Key 的安全永远不要传给不明来源的第三方面板。7.2 cc-switch 接入 DeepSeek / Qwen / GLM 的核心步骤下面是我的配置流程但要注意一点各家 API 的 Base URL 和模型名称会不定期调整所以不要把我写的地址当成永久格式接入前务必以各家官方文档的最新信息为准。安装并配置 cc-switch。在 cc-switch 里添加供应商配置填写名称、Base URL、API Key、模型名称。让 Claude Code 的数据接入层使用这套配置。跑一个最简单的测试任务看看是否正常返回再逐步上复杂任务。配置结构大致像下面这样具体字段名按工具版本调整{ providers: [ { name: deepseek, base_url: https://api.deepseek.com/v1, model: deepseek-chat }, { name: qwen, base_url: https://dashscope.aliyuncs.com/compatible-mode/v1, model: qwen-max }, { name: glm, base_url: https://open.bigmodel.cn/api/paas/v4, model: glm-4 } ] }这类兼容方案容易踩的坑是不同模型的参数名、上下文长度限制、工具调用格式都有细微差别。有些模型在一个供应商接口下表现正常换到另一个供应商就频繁报格式错误。这时候不要急着怪模型先看是不是配置里的参数没有对齐。模型常见兼容点常见冲突点建议DeepSeekOpenAI 兼容风格明显切换成本低部分工具调用格式和官方略有差异先跑一个带工具调用的测试用例QwenDashScope 兼容模式比较成熟最大上下文和模型版本命名变化频繁关注官方模型列表页GLMAPI 风格接近部分历史版本参数不一致用最新稳定版本7.3 注册账号和不注册账号到底差在哪一个经常被问到的问题是“harness 不登录可以用其他模型吗”我的回答是可以但要想清楚代价。不登录使用第三方模型整个 CLI 外壳仍然能跑只要它被配置为通过某个 OpenAI 兼容端点来调用模型。你相当于把 Claude Code 当作一个“Agent 执行框架”在用本质的对话模型已经换成了第三方服务。区别主要在几方面官方模型通道不登录就无法使用官方模型和配套的订阅额度。会话历史同步很多云同步、会话记录能力依赖账号体系不登录时通常只能本地管理。部分高级配置官方账号的一些特性在第三方模型接入时可能不可用。所以我的策略是日常重要任务用官方账号确保稳定性和数据同步某些实验性、高成本的批量任务如果公司内部已经有其他模型通道再用 cc-switch 切到第三方模型。两条路径分开配置互不污染。我个人强烈建议API Key 不要直接写进任何可能被提交到 Git 的配置文件里。用环境变量或独立的.env文件并加入.gitignore是最基本的底线。8. 从单步聊天升级到自动化工作流的避坑清单8.1 我踩过的最贵的三个坑第一把敏感 Key 放进项目配置里并提交到了仓库。有一次我在一个示范项目里为了方便直接把第三方 API Key 写进配置文件后来项目推到公开仓库才意识到问题。虽然马上删除重推了但这个记录已经留在历史里。现在我只用环境变量任何 Key 都不进配置文件。第二允许自动执行所有命令结果它差点删掉本地数据库。当时为了追求效率我开启了“自动接受所有命令”。结果 Claude Code 在处理一个清理脚本时误判了一个路径直接跑了删除命令。虽然没造成实际损失但把我吓出一身冷汗。从那之后危险命令一律加入 deny 列表重要目录必须二次确认。第三自愈循环没有上限token 消耗直接爆表。我让它在一次回归测试里自动修复没有限制循环次数结果它在同一个问题上反复尝试了几十次消耗了大量 token 也没解决。后来我所有的自愈循环都加了最大尝试次数两次失败就停下宁可人工介入也不盲目硬试。8.2 这套架构的安全边界怎么设自动化程度越高安全边界越重要。我现在坚持几条底线禁止在自动流程中加入不可逆操作。比如git push --force、清空数据库表、删除生产环境文件这些都不应该出现在白名单里。敏感操作使用独立沙箱或临时分支。自愈循环、批量修改如果可能影响生产代码就先在 feature 分支或容器环境里跑验证通过后再合并。每次自动改动都必须有 diff 审计。让 Claude Code 在修改后输出变更清单而不是默默改完所有文件。对 Routine 做版本管理。Routine 也是代码改完之后要有记录出问题能回退到上一个版本。8.3 什么情况不建议用这套重型架构多 Agent 编排、闭环自愈、Routine 脚本化听起来很强大但并不是所有项目都需要。如果是临时想了解一个函数怎么写直接聊天就够了如果项目只有十几个文件硬拆成多 Agent 反而增加沟通成本如果需求本身还在剧烈变化连验收标准都没定下来自动化的意义不大。我的判断标准很简单这个任务是不是高频、是否可验证、是否值得沉淀。只有这三个答案都是“是”的时候才值得投入精力去设计编排和 Routine。如果你刚开始尝试我建议从小处切入先把一个构建流程和测试流程串成最简单的自愈循环跑通了再加一个 Review Agent然后慢慢把日常任务固化成 Routine。不要一上来就搭一个多 Agent 大架构那样只会让你陷入配置地狱而不是提升效率。我现在回过头看最大的收益不是“代码写得快了”而是“过程被管理了起来”。Claude Code 的真正用法不是当一个更聪明的聊天机器人而是把它当成一支由 Agent 组成的小队有人负责拆任务有人负责执行有人负责检查有人负责补救。你要做的事情只有两件给出清晰的目标以及守住不能碰的底线。