Claude Code 发布之后很多人的第一反应是把它当成终端里的 ChatGPT贴一段报错问一句“怎么改”复制答案再贴下一段。我见过的最常见用法就是这样一问一答单步推进。这种用法不能说完全没用但它恰好浪费了 Claude Code 最值钱的部分——它不是一个聊天框而是一个跑在终端里的 Agent 运行时。它真正的价值在于能自己规划任务、自己调用工具、自己验证结果甚至在自己出错之后自己爬起来修好自己。这一篇我准备分四条线把 Claude Code 讲透多 Agent 编排怎么把单线程对话变成多角色并行作战闭环自愈怎么让 Agent 在测试失败时自动修复直到全绿Routine 脚本化怎么把重复劳动固化成一碰就能跑的流水线最后结合很多人都关心的安装、IDE 接入和第三方模型接入DeepSeek、Qwen、GLM 这类讲一下落地细节。目标只有一个把它从“高级问答工具”升级成真正能交付结果的“自动化工程师”。1. 单步聊天的瓶颈为什么Claude Code不该被当成聊天框用1.1 聊天框工作流的三个死穴先把话说透单步聊天模式在简单小问题上确实有效但一旦进入真实工程立刻会暴露三个致命问题。第一个是上下文断裂。你问完一个问题得到一段代码复制进编辑器跑一下报错再把新报错贴回去。每一轮都意味着大量的上下文重传项目的重要背景、之前的结论、已经改过的文件统统需要重复描述。任务稍微复杂一点人和 Agent 都会迷失在“刚才说到哪了”的混乱里。第二个是反馈回路缺失。聊天框只能输出建议不能真的动手。它说“把这两个函数抽出来”你改完发现单测挂了再贴给它看它再给建议你再去改。这个循环里真正干活的是人Agent 只是在旁边当参谋。而 Claude Code 不是这样——它能自己运行测试、自己读报错、自己改代码形成完整的行动-反馈-修正闭环。第三个是经验无法沉淀。聊天记录关掉就没了同一个项目的“提交前检查流程”下次还得从头再聊一遍。你从一次问答里得到的只有一段代码不是一个可以复用的工作流程。长此以往工具使用效率始终停留在第一周的水平。1.2 Claude Code的真实身份终端里的Agent运行时我们得先纠正一个认知Claude Code 和网页聊天最大的区别不在于界面而在于“它拥有执行权限”。Claude Code 底层是围绕工具调用Tool Use设计的 Agent。它手里有一整套工具读文件、写文件、执行 Shell 命令、运行测试、搜索代码、编辑代码片段。当它接到一个任务时它会自己做规划然后反复调用这些工具去验证自己的想法。这意味着它能直接在你的仓库里动代码、跑出真实的测试结果再根据结果调整策略。这看起来只是一个工程细节实际影响却是革命性的。网页聊天里的代码永远只是“建议”你需要手动搬运Claude Code 里的代码是“实施”它会自己改完自己跑测试。这个差异决定了它能接手的任务复杂度上限完全不同。我还想强调一个容易被忽略的点Claude Code 有主 Agent 和子 AgentSubagent的层级设计主 Agent 负责拆解目标和汇总结果子 Agent 负责具体执行。加上 hooks钩子机制可以在工具调用的生命周期里注入你自己的逻辑它天生就是为“可编排、可自愈、可固化”设计的。如果你只用它来一问一答等于开着一辆赛车在小区里遛弯。2. 多Agent编排从一问一答到多角色并行作战2.1 主Agent与SubagentClaude Code天然就是多Agent架构很多人不知道Claude Code 内部本身就是一个多 Agent 架构而不是单个模型死磕到底。主 AgentPrimary Agent负责理解你的目标、拆解任务、决定调用哪些工具、以及把子任务的产出合并成最终答案。当它遇到可以并行或需要专门处理的子问题时会通过 Task 工具派发一个 Subagent。每个 Subagent 都有自己的角色定义、自己的上下文窗口、自己的任务说明。子 Agent 跑完回来后把结论交给主 Agent 汇总。这种设计最直接的好处是上下文隔离。假设一个重构任务涉及前端组件、后端接口、测试用例三块如果只有一个 Agent 处理它会带着全部上下文来回切换很快就把注意力耗散在不同的代码区域里。拆成三个 Subagent 后每个子 Agent 只需要加载自己负责的那部分内容精力集中出错率低还可以并行推进。在项目里你可以通过.claude/agents/目录来定义自己的专属 Subagent。比如我想让一个专门做代码审查的 Agent 帮我挑毛病我就写一个reviewer.md# 文件名.claude/agents/reviewer.md 你是资深代码审查员具有 10 年工程实践经验。你的工作原则 - 只审查不修改发现问题必须清楚指出代码位置和修改建议 - 重点防范安全漏洞、性能隐患、可维护性三类问题 - 输出时按严重程度排序先列 P0 阻断性问题再列优化建议 - 不空谈理论每一条意见都要能落地主 Agent 需要审查时会把这个 Subagent 拉进子任务里让 review 专注于挑刺而主 Agent 自己专注在“怎么改”的决策上。这就是多 Agent 编排的价值不同角色负责不同职责而不是一个 Agent 又想写代码又想批评自己——自己审自己的代码审出来的问题通常都很浅。2.2 三种编排模式串行流水线、扇出聚合与多角色会商实际用下来我把多 Agent 编排总结为三种模式它们对应不同场景大家可以按需选用。第一种是串行流水线。上游 Agent 的产出是下游 Agent 的输入适合有明确依赖关系的链路。比如代码生成 Agent 先产出新模块测试 Agent 再对模块补测试文档 Agent 最后同步更新文档。每一环节的上下文都限定在本环节内逻辑清晰好排查。第二种是扇出聚合。主 Agent 把一个任务拆成 N 个独立的子任务同时派出多个 Subagent 并行执行最后把结果收回来合并。适合大量独立文件的批量处理比如多文件重构、多目录扫描。我记得有一次处理一个仓库的大规模命名规范调整拆成 6 个 Subagent 并行跑总共用了不到三分钟换成单 Agent 串行至少得翻三倍时间。第三种是多角色会商。开发 Agent 产出代码审查 Agent 输出问题清单主 Agent 再综合两边意见做决策。这特别适合“既要快又要稳”的场景相当于在团队里强行塞进了一个独立评审角色。我简单放一个对比表方便大家在方案设计时快速做选择编排模式适用场景优势主要风险串行流水线有明确上下游依赖的流程职责清晰结果可控单环节失败会阻塞整条链路扇出聚合批量独立任务并发提速明显结果合并需要主 Agent 做归纳多角色会商写码加审查的组合质量兜底强消耗 token 更多决策链路变长2.3 编排粒度与上下文管理的权衡关于多 Agent 编排我必须提醒一句不是拆得越细越好。Subagent 虽然能隔离上下文但隔离也意味着信息壁垒。子 Agent 之间不能直接对话所有跨子任务的信息都必须经过主 Agent 中转。如果你把一个本来很简单的任务拆成七八个子任务主 Agent 会花大量精力在“传递上下文”和“合并结论”上反而得不偿失。我自己的经验是一个子任务拆分的边界应该是“它能否独立完成验证”。如果这个子任务跑完能自己给出确定性的结果——比如“Lint 通过”“测试全绿”“文件已生成”那它就值得拆出去。如果它必须依赖另一个子任务的结果才能继续那它更适合作为串行链路中的一环而不是独立 Subagent。还有一点Subagent 的上下文通常比主 Agent 更小。越是复杂的上下文越应该留在主 Agent 里把具体的、局部的、机械性的操作推给 Subagent。这就像搞工程项目经理应该掌握全局而水电工只需要管好自己那面墙。3. 闭环自愈让Agent在报错之后自己爬起来3.1 hook机制把自动反馈装进工具调用生命周期闭环自愈核心就一句话Agent 错了能自己知道然后自己修复、自己验证直到满意。Claude Code 实现这一步的关键是 hooks 机制。hooks 可以理解成一组“监听器”。Claude Code 在工具调用的各个阶段都会触发特定事件你可以在这些事件上挂自己的脚本注入额外的逻辑。常见的有几类PreToolUse工具执行前触发、PostToolUse工具执行后触发、NotificationClaude Code 需要发送通知时触发、UserPromptSubmit用户提交 prompt 时触发、StopAgent 完成一轮回答后触发。真正构成自愈闭环的是PostToolUse和Notification的组合。举个例子我想让 Claude Code 在跑测试失败后自动进入修复模式可以在项目根目录的.claude/settings.json里配一个 hook{ hooks: { PostToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 .claude/scripts/auto_repair.py } ] } ] } }这段配置的意思是每次 Claude Code 执行完 Bash 工具后自动运行auto_repair.py。脚本会读取 hook 传入的 JSON里面包含刚执行的命令、返回码、输出摘要如果发现命令是测试命令且返回码非零就把“测试失败”作为一条明确指令追加到当前会话的上下文里让 Agent 知道需要修复并重新运行。3.2 一个测试失败自动修复的自愈循环实例这里我写一个简化版的自动修复脚本逻辑方便理解整套闭环是怎么转起来的# .claude/scripts/auto_repair.py import json, sys data json.load(sys.stdin) tool_name data.get(tool_name, ) command data.get(tool_input, {}).get(command, ) exit_code data.get(tool_response, {}).get(exit_code, 0) stderr data.get(tool_response, {}).get(stderr, )[-2000:] # 只对测试类命令生效 if tool_name ! Bash or pytest not in command and npm test not in command: sys.exit(0) if exit_code ! 0: # 通过标准输出向 Claude Code 注入修复指令 print( 测试命令返回了非零退出码。请立即分析上述错误定位失败的用例 修复对应源码后重新运行相同的测试命令直到测试全部通过。 f最近错误{stderr} )这个脚本的逻辑很直接监听到测试失败就把失败信息和修复指令打包成一段 prompt 塞回对话流。Claude Code 收到这段指令后会自己去查代码、改代码、重新跑测试。如果又失败hook 再次触发再次注入修复指令。循环往复直到通过或者达到某个终止条件。这样构建出来的闭环本质上是把“人肉搬运报错信息”这个环节省掉了。效果很明显——以前测试挂了你要复制报错、贴给 Agent、等答案、复制修改、再跑测试。现在测试挂了Agent 自己就能跳起来处理。3.3 自愈的边界什么时候要人为介入闭环自愈不是万能的它有非常明确的适用边界。我在实际项目中给自愈循环设了严格的“护栏”否则它会变成一个吞 token 的无底洞。第一个护栏是轮数限制。我会在 prompt 里明确告诉 Agent“如果连续修复 3 轮测试仍未通过停止并报告等待人工决策。”没有这个限制有些棘手的连环 bug 能让 Agent 跑几十轮消耗惊人而且大概率是白费。第二个护栏是权限白名单。自愈脚本只能触发“测试、修改源码、重新运行测试”这类安全操作。像生产环境部署、清空数据库这类危险操作绝不能放进自愈循环里。具体做法是限制 Claude Code 的允许工具列表或者通过 hook 对危险命令直接拦截。第三个护栏是问题类型的判断。自愈机制最擅长的是机械性问题编译报错、单测断言失败、类型不对、路径写错。这些问题是确定的修复目标明确的Agent 自己就能搞定。但如果是设计层面的问题比如模块职责混乱、接口方案不合理、状态管理设计有缺陷我不建议让 Agent 自己闷头修。这种问题需要人来拍板Agent 的自愈只会让代码在错误的框架下变得更复杂。4. Routine脚本化把重复性工作固化为可复用流水线4.1 CLAUDE.md项目记忆的根Routine 脚本化的起点是先解决 Agent 的“项目记忆”问题。Claude Code 在每次会话启动时都会自动读取项目根目录下的CLAUDE.md把它作为理解项目的核心依据。这个文件里写的不是代码而是“这个项目是什么、技术栈是什么、代码结构如何、有哪些约定和禁忌”。CLAUDE.md 写得好不好直接决定 Agent 的初始行为像不像一个“老团队成员”。比如我会在 CLAUDE.md 里明确写# 项目约定 - 前端使用 React TypeScript组件统一放在 src/components - 后端使用 Node.js禁止在服务端代码里写业务逻辑 - 所有公共函数必须有 JSDoc 注释 - 提交前必须运行 pnpm lint 和 pnpm test:unit - 禁止直接修改 lockfile依赖变更需通过 pnpm add/remove这些约定有什么用当 Agent 被要求“新增一个页面”时它读一遍 CLAUDE.md 就知道该往哪个目录放文件、用什么语法风格、完成后要跑什么校验。你不需要在任何一次任务里重复交代这些背景这就是“经验沉淀”。4.2 ROUTINE.md操作流程的复用模板如果说 CLAUDE.md 是“项目是什么”那 ROUTINE.md 就是“这类事情怎么做”。Routine 这个概念来自工程实践中的“标准操作流程”SOP思想把固定重复的工作流程变成一份 Agent 可以直接照做的模板。以 PR 发布前检查为例我一般会在.claude/routines/目录里放一份流程文件# 文件名.claude/routines/release-check.md ## 触发条件 任何 PR 在打上 release 标签前按此流程执行。 ## 执行步骤 1. 运行 pnpm lint若有 error 则修复后重跑直到 0 error 2. 运行 pnpm test:unit若有失败则定位原因并修复再重跑直到全绿 3. 运行 pnpm build确认构建产物正常生成 4. 对比本 PR 涉及的文件生成一份风险清单写入 .claude/changes.md 5. 若步骤 2 或 3 修复轮数超过 3 次停止并请求人工介入 ## 完成标准 - lint 0 error - 单测全部通过 - build 产物存在且无异常警告 - .claude/changes.md 已生成内容包含变更文件清单和高风险项说明这份 Routine 解决了什么问题你不需要在任务描述里一点点交代“先做什么再做什么”只需要一句话“执行 release-check routine”。Agent 会自动读取这份模板按步骤逐项执行。每次流程的颗粒度一致结果质量和执行路径都可预期。4.3 把Routine串进CLI与Git工作流Routine 文件本身只是“说明书”想让它真正跑起来还需要把它和 Claude Code 的命令行能力串起来。Claude Code 支持claude -p 指令这种非交互式执行模式我经常拿它和脚本配合。比如在package.json里加一个脚本{ scripts: { release-check: claude -p \请按照 .claude/routines/release-check.md 的流程执行本次发布前检查\ --allowedTools Bash,Read,Edit,Write } }这样不管是本地开发还是 CI 里一行npm run release-check就能触发整套标准流程。Routine 不再只是 Agent 的参考文本它变成了团队工作流中的一等公民可固化、可复用、可通过命令行随时调用。4.4 Routine拆分的颗粒度把“怎么做”和“为什么做”分开最后聊一个我踩过坑的经验Routine 文件一定要把“怎么做”写清楚把“为什么做”留给 CLAUDE.md 或者代码注释。原因很简单——Agent 是目标驱动型执行者你给它留的自由度越小它跑出来的结果越可控。我最早写 Routine 时犯过一个错喜欢把“为什么要跑 lint、为什么要跑单测”也写进去。结果 Agent 遇到“某一步看起来无关紧要”的情况时会基于自己的理解跳过步骤产出完全不可预期。现在我的习惯是Routine 里只写“必须做什么、按什么顺序、完成标准是什么”所有解释性内容全部删掉。流程文件就应该是无情、机械、不容变通的。那如何防止 Agent 在 Routine 中途跑偏可以在步骤里反复强调“严格按顺序执行不要跳过任何一步”。再加上我在 3.3 节说的轮数护栏基本上能把不可控因素压到最低。5. 环境部署与模型接入从安装到切换DeepSeek/Qwen/GLM5.1 三平台安装与版本升级先解决环境问题。Claude Code 最常见的安装方式是 npm 全局安装macOS、Ubuntu、Windows建议配合 WSL 或 Git Bash 使用都可以这样装npm install -g anthropic-ai/claude-code claude --version装完在终端直接敲claude就能进入交互模式。升级也很简单Claude Code 内置了claude update命令可以自动拉取并安装最新版本省去了手动卸载重装的麻烦。如果你关心“在线升级最新版本”这个事claude update就是最省心的路径。网上还有通过原生安装器装的方式体验更好但 npm 方式胜在跨平台统一我目前主力环境就是 Ubuntu Server WSL 的组合npm 安装一次可以同时覆盖几种使用场景省心。5.2 不支持地区提示怎么应对分区配置与验证这里有一个很多人会遇到的情况安装或运行时终端可能会提示“Claude Code might not be available in your country. Check supported countries”。这并不是安装失败而是 Claude Code 在启动时做的一次区域可用性检查。它会在提示后照常打开交互界面但它确实会影响部分用户的使用预期。一个稳妥的做法是安装完成后先确认 npm 源正常再用claude --version验证版本号能打印出来。只要版本号正常输出核心运行时就已经就位了。同时建议保留我的经验这类工具经常更新每次claude update之后都重新跑一次claude doctor如果有该命令或者claude --version做环境自检能省掉不少后续排错的时间。5.3 用cc-switch切换DeepSeek、Qwen、GLM等模型Claude Code 默认是绑定 Anthropic 账号的但很多人手头用的是 DeepSeek、通义千问Qwen、智谱 GLM 这类模型的 API。这就要用到 cc-switch 这类配置管理工具。cc-switch 做的事情很简单替你维护多套 API 供应商配置一键切换 Claude Code 指向的接口地址和鉴权信息。原理其实一点都不神秘Claude Code 本身支持通过环境变量改写后端地址和 token核心就是这样几个变量export ANTHROPIC_BASE_URL你的供应商兼容接口地址 export ANTHROPIC_AUTH_TOKEN你的供应商API Key export ANTHROPIC_MODEL模型名称如 deepseek-chat / glm-4-plus 等不同供应商的兼容接口地址不一样具体要以各家官方文档为准。DeepSeek、阿里云百炼、智谱 AI 都提供 Anthropic 兼容接口所以 Claude Code 可以无缝切换过去使用。cc-switch 的价值在于它把这些配置从“每次手动 export”变成了“配置文件里点几下就切完”。它会修改 Claude Code 的配置文件写入不同的 base URL、token 和默认模型名下次启动claude时自动生效。切换模型时不需要动你的系统环境变量确实是第三方 API 使用场景下的常用工具。5.4 VS Code联调与插件配置如果你习惯在编辑器里工作Claude Code 官方提供了 VS Code 扩展。装完扩展后侧边栏会多出一个 Claude 面板你可以在里面发起会话。它和终端的核心能力是打通的同一个 Agent 运行时同一个工具调用体系区别只是多了一个可视化的 diff 预览和文件追踪功能。我自己在 VS Code 里的用法是终端负责跑命令行层面的 Routine 和自愈闭环编辑器面板负责需要逐行审阅代码的场景。两个入口共用一套配置和记忆不会出现“终端里的 Agent 不知道我改了什么”的情况。配置方面扩展会在首次使用时引导你选择可执行文件路径和登录方式如果走了第三方模型路线确保 5.3 的环境变量在启动 VS Code 前已生效即可。6. 一次真实改造把PR检查从单步聊天升级为编排流水线6.1 改造前人肉搬运的聊天式PR检查最后我把前面三条线串起来讲一个真实的改造案例你会发现这几个概念的组合威力比单独用大得多。我有一个开源项目过去每次提 PR 都挺痛苦的。过程是这样的我先自己在本地跑 lint有错就手动改改完跑单测挂了再手动修修完 build 又报错再接着改。偶尔想偷懒就把报错信息复制给 Claude Code 聊天窗口让它给修改建议然后我再复制回编辑器。一个 PR 检查流程快的时候 20 分钟碰上复杂的 bug 能折腾一晚上。6.2 改造后Routine固化流程多Agent并行检查自愈兜底后来我花了半天时间把整个流程重构成了现在的样子。第一步写release-check.mdRoutine把 lint、test、build 的步骤和完成标准全部固化塞进.claude/routines/目录。第二步在.claude/agents/里定义了三个 Subagent一个负责跑前端 lint 并修复一个负责跑后端单测一个负责检查构建产物和生成风险清单。第三步在 settings.json 里加了 PostToolUse hook让任何测试类命令失败时自动触发修复指令。现在执行 PR 检查只需要在项目根目录敲一行claude -p 按 release-check routine 执行 PR 发布检查发现问题就地修复直到满足完成标准主 Agent 会按 Routine 的步骤拆解任务把前端检查、后端测试、构建检查分别派给三个 Subagent 并行推进。某个环节挂了hook 感知到测试命令返回非零码自动把失败信息塞回上下文让 Agent 修完再跑。如果修了 3 轮还没好Agent 停下把详细日志和它尝试过的方案交给我。这个改造带来的变化是质变级的。同样一个 PR 检查流程我从 20 分钟起步的折腾变成了“一条命令走完通过就合不通过看日志”。最关键的还不是快而是可预期——每次跑的步骤一样质量标准一样失败处理策略一样。它终于从“靠人临时发挥”变成了“靠流程兜底”。6.3 这套组合拳最怕什么三个容易翻车的细节这个方案跑了两个月我踩过三个坑值得单独写出来。第一个坑是 Routine 文件写得不够“死”。有一次我在步骤里写“运行构建并确认产物正常”Agent 检查完只看了构建日志就报告成功了没去验证产物文件是否真的存在。后来我把完成标准改成“检查 dist 目录下 index.js 文件存在且大小非 0”从此没再翻过车。第二个坑是并行 Subagent 之间的文件冲突。两个子任务同时改同一个文件可能出现互相覆盖。现在我的做法是不同 Subagent 只允许操作自己负责的目录在 Subagent 的角色定义里写清楚“你只能修改 src/ 下的文件”主 Agent 汇总时再做一次交叉检查。第三个坑是自愈循环卡在“同一类错误上反复修”。Agent 修完跑、跑完挂、挂了再修如果根因是同一个设计问题它会浪费大量轮次。所以我给 Routine 加了轮数上限就像 3.3 节说的3 轮不过立刻上报。这个护栏让自愈机制只处理它擅长的问题剩下的留给人工决策。最后分享一点个人体会。多 Agent 编排、闭环自愈、Routine 脚本化这三板斧单独拿出来都不算新鲜真正让工作流质变的是它们组合在一起Routine 提供流程框架多 Agent 提供执行效率自愈提供容错兜底。如果你也想在自己的项目里落地这套打法我的建议是别贪多先挑一个每周都在重复的琐碎流程做成第一个 Routine配一个自愈 hook等跑顺了再往里加 Subagent。从一个小闭环开始你会明显感觉到它和之前聊天式用法的差距。