说实话我第一次碰 Claude Code 的时候完全就是把终端当聊天框用——问一句答一句代码改了跑一遍报红字再贴回去让 AI 再改一轮。单步聊天模式用了一周效率确实有提升但远没到让人“哇”的程度更像是一个能看懂项目上下文的智能终端。直到我把多 Agent 编排、闭环自愈这两件事想明白再把重复流程固化成Routine 脚本化架构才真正找到了 Claude Code 的正确打开方式。这篇东西就是围绕这三个关键词展开的适合两类人看一类是已经装了 Claude Code 但还在单步聊天、感觉“也就那样”的人另一类是团队里想把 AI 编码能力沉淀成统一工作流、不想每次让每个开发都从头调教 AI 的工程负责人。我尽量把原理和能直接抄走的实操都写出来踩过的坑也一并交代。1. 单步聊天到底低效在哪先看清问题再谈解法1.1 一个典型的单步聊天事故现场我见过太多这样的场景甚至自己刚开始也这样需求是“给登录模块加个记住我功能”于是敲下第一句 Prompt——“帮我在登录页面加个记住我选项”。Agent 很听话马上改了页面加了 input 和 localStorage然后停下来等你验收。你一看发现没有把 token 存到 cookie 里于是第二句“记住我要把 token 写进 cookie”。Agent 改了又跑起来结果测试挂了。第三句“测试挂了帮我修一下”。修完了你又发现 CSRF 相关逻辑没考虑到……一整个下午就在这种“你说一步、它改一步”的循环里消耗掉。等到最后功能终于能跑了上下文已经塞满了二三十轮对话Agent 记不清前面改过什么甚至开始把不相干的文件也动了一遍。这不是个例是所有单步聊天模式的通病。它的本质问题不是 AI 不够聪明而是你把一个完整任务拆成碎片扔给了它却期待它能自动拼出全局。1.2 单步聊天的三个结构性缺陷第一个缺陷是上下文窗口被垃圾对话占满。每一轮“你发现错误 它修复”的对话都会永久留在上下文里真正有用的项目信息反而被挤到边缘Agent 的注意力被稀释。越往后它越容易犯低级错误比如改回之前的代码或者漏掉前面定下的约束。第二个缺陷是角色不分离。同一个上下文里Agent 既要当架构师去设计改动方案又要当开发去写代码还要当测试去验证结果。你见过一个团队让同一个人既写代码又测自己代码还不允许别人审查吗单步聊天就是这个状态。它在写代码时的自信会直接带进验证环节“我觉得没问题”替代了客观测试结果。第三个缺陷是没有验收标准。单步聊天里你很少在开头就说清楚“什么叫完成”Agent 只能靠猜。而你没说清楚完成标准它自然就按最省事的方式交差——改了页面就认为做完了测试挂了那是另外一回事。1.3 多 Agent 编排的本质把一个人的“角色分裂”变成团队的“职能分工”想明白单步聊天的病根之后解法其实很自然让不同的 Agent 扮演不同的角色把“人肉调度”变成架构上的强制分工。这就是多 Agent 编排的核心思路。打个比方单步聊天像你一个人既是产品经理又是开发又是运维脑子里来回切换肯定会乱多 Agent 编排像一个正规开发团队——项目经理拆任务、开发写代码、测试做验证、审查员挑毛病每个角色有且只有一个核心目标目标之间互补互斥。Claude Code 在原生层面就支持这套玩法CLAUDE.md 定义项目级规则Subagent 定义专职角色Hook 机制在关键节点做强制检查。你可以把任务拆成“规划 Agent → 执行 Agent → 审查 Agent”的三级流水线也可以按代码模块拆成“前端 Agent、后端 Agent、数据层 Agent”的水平分工。不管哪种核心就一句话一个 Agent 只负责一件事验证和修复交给别的角色用文件系统而不是对话记录做交接。2. 拆解多 Agent 编排CLAUDE.md、Subagent 与任务交接2.1 CLAUDE.md项目的“组织章程”很多人把 CLAUDE.md 当成一个简单的“项目说明书”写几句项目简介就完事了浪费了它真正的价值。CLAUDE.md 的作用更接近一份给所有 Agent 看的组织章程——无论是主 Agent 还是 Subagent启动时都会读它然后按照里面的规则约束自己的行为。我建议至少写清这四类内容。第一是项目结构与技术栈速览让任何 Agent 进来都能快速定位代码第二是构建、测试、lint 的具体命令并且强制要求“改完代码必须跑哪条命令”第三是代码规范与红线比如“禁止直接改数据库迁移文件”或“所有 API 返回必须走统一包装函数”第四是完成任务的定义也就是什么叫“Done”。举个例子我项目里的 CLAUDE.md 会有这么一段## 工作流强制规则 - 任何代码改动完成后必须执行 npm run lint 和 npm run test - 两条命令全部通过后才允许向用户报告任务完成 - 如果测试失败必须继续修复并重新运行禁止跳过或注释失败用例 - 涉及接口变更时必须同步更新 OpenAPI 文档关键不是规则写得漂亮而是它会被所有 Agent 读取并遵守。单步聊天里你每次都要复述一遍这些要求多 Agent 编排里写一次、全局生效。2.2 用 Subagent 定义专职角色Subagent 是 Claude Code 里定义“专职角色”的机制。你可以在项目的.claude/agents/目录下用 Markdown 文件定义一个带固定身份、固定工具、固定系统提示的 Agent主 Agent 在任务执行中可以动态把子任务指派给它。比如我定义一个“代码审查员”--- name: code-reviewer description: 资深代码审查员负责审查代码改动并找出回归风险。当需要评估变更质量时使用。 tools: Read, Glob, Grep, Bash --- 你是一位代码审查专家要求如下 1. 只审查 diff不直接修改代码 2. 检查逻辑错误、边界条件、安全隐患、性能问题 3. 对每个问题标注严重等级BLOCKER / MAJOR / MINOR 4. 输出简洁的审查结论最后给出 PASS 或 FAIL 5. 如果 FAIL必须列出前置的修复顺序同样还可以定义“架构规划师”负责读需求、拆任务、定验收标准“测试工程师”只负责补测试和跑回归。每个 Subagent 的 Prompt 尽量短但结构清晰因为它要的就是“边界感”而不是长篇大论。定义一个 Subagent 后你在交互模式里用code-reviewer就能把它叫出来在多 Agent 编排中主 Agent 也会根据 description 里的提示自动决定何时调用它。2.3 编排模式的两种主流形态实际跑下来我见过的多 Agent 编排形态基本可以归成两种流水线式和主管-员工式。流水线式适合任务边界清晰、先后顺序明确的场景典型就是“规划 → 执行 → 审查 → 修复”。上游 Agent 的输出直接变成下游 Agent 的输入每个环节都有独立的上下文不会互相污染。主管-员工式适合任务比较复杂、需要动态拆分的场景。主 Agent 扮演主管接收到需求后自己判断需要哪些角色把子任务派发给不同 Subagent回收结果后再做汇总。这种模式的灵活度高但对主管 Agent 的规划能力要求较大如果你发现它总在错误地调度角色多半是 CLAUDE.md 里的项目上下文给得不够。不管用哪种形态我发现了一条非常实用的经验不要依赖 Agent 之间的对话记忆来传数据。上了多 Agent 之后最忌讳的就是让 Agent A 说“我们刚才商定了方案 B”然后把方案 B 的口头摘要转述给 Agent B。摘要会失真必须把中间产物落到文件系统里。2.4 任务交接用文件系统作为 Agent 之间的“对接单”多 Agent 编排真正的难点不在定义角色而在任务交接。A 干完活怎么告诉 B 它改了什么、哪些是重点、哪些是已知风险靠聊天记录转述是最不可靠的。我的做法是在项目里划一个.agent-workspace/目录专门用来放 Agent 之间的交接文件比如plan.md规划产物、changes.json改动清单、review-report.md审查结论。规划 Agent 把任务拆解写入plan.md执行 Agent 只认这份文件审查 Agent 拿changes.json里的文件列表去逐个审查审查结论写进review-report.md再驱动下一个修复轮次。这样一来整个多 Agent 编排就像一条真正的流水线每个工位都只读取上游放到托盘里的工件不关心上游是谁、怎么干活的。好处很直接上下文窗口省下来了Agent 之间的“记忆串扰”也彻底消失每一级都只关注自己分内的事。3. 闭环自愈把“改了跑、跑了错”的人肉循环变成机器自律3.1 自愈闭环的四个要素“闭环自愈”这个词看着高级本质就是把你在单步聊天里手动做的事自动化。单步聊天为什么累因为“改代码 → 跑测试 → 发现又错 → 再改”这个循环是靠你人肉驱动的Agent 只管改不管验证更不管验证失败后怎么办。闭环自愈想要成立至少要具备四个要素变更、检测、修复、回归。变更就是 Agent 对代码做了修改检测是有一套客观的评判手段比如测试、lint、类型检查、构建脚本而不是让 Agent 用眼睛读代码修复是检测失败后 Agent 拿着错误信息对代码做定向修整回归是修复完成后重新跑一遍检测确认问题真的解决了而不是“看起来解决了”。这四个要素连成一个循环循环的退出条件只有一个检测全部通过。这就是为什么 CLAUDE.md 里我强制要求“测试失败必须继续修复并重新运行”——这是闭环自愈的根基。3.2 用 Hooks 给自愈装上“强制关卡”光在 CLAUDE.md 里写规则还不够因为模型偶尔会犯懒或“失忆”。真正靠得住的是 Hooks 机制——Claude Code 在执行流程的关键节点上触发外部脚本由脚本来做硬性校验Agent 想跳过都跳不过去。我重点用的是两种PreToolUse和PostToolUse。PreToolUse 在某个工具被调用前触发比如我拦截 Bash 命令禁止在非交互任务里执行rm -rf这类高危操作PostToolUse 在工具执行后触发可以在 Agent 跑完测试后立刻捕获输出判断成功还是失败。settings.json 里的一个 Hook 配置长这样{ hooks: { PostToolUse: [ { matcher: Bash, command: python3 .claude/hooks/check_test_result.py } ], PreToolUse: [ { matcher: Bash, command: python3 .claude/hooks/guard_dangerous_command.py } ] } }check_test_result.py的逻辑很简单当 Claude 执行了包含npm test或pytest的命令时把退出码和输出尾部捕获下来如果退出码非 0就写一个TEST_FAILED状态文件到.agent-workspace/目录如果通过就删除这个状态文件。这个状态文件会被后续的 Agent 看到骗不了人——因为它读取的是操作系统的真实退出码不是模型“自认为成功”。3.3 设置 Definition of Done根治“Agent 自嗨”闭环自愈反向的坑是Agent 太容易满足。模型天生有讨好用户的倾向你说“测一下”它可能真的跑了测试但如果测试用例覆盖率低或者测试本来就是空的它也会开心地告诉你“全部通过”。所以光有“测试通过”还不能算完成我引入了 Definition of Done 的概念在 CLAUDE.md 里明确列出完成一份代码改动必须满足的标准。比如lint 零报错、新增变更必须有对应测试、类型检查通过、构建通过、关键路径的日志要覆盖。任何一项不满足Reviewer Agent 就有权打回不算完成。这就把自愈的“检测”从“测试过不过”扩展成“一套客观质量红线是否全部命中”。Agent 想自嗨也嗨不动因为它在提交前必须逐项自证。3.4 收敛条件与防死循环设计闭环自愈最大的风险不是不干活而是死循环里空转。AI 修复同一个 bug 修了五次还不过每次换一种错误方案烧的是你的 API 额度耗的是你的耐心。我见过最夸张的一次Agent 在一个测试用例上反复折腾了 47 轮原因就是没人告诉它“你该换思路了”。我的防死循环设计有三道闸。第一道是最大重试次数在编排层设置比如一个自愈循环最多执行 5 轮修复超过就退出把难题交还给人类第二道是修复历史记录每轮把 Agent 当前的猜测和修复动作追加到fix-attempts.md下一轮 Agent 读取这个文件后就知道了“前面试过方案 A、B都失败了”避免它原地踏步第三道是降级策略连续失败两次后Prompt 里明确要求 Agent 必须停下来重新读完整错误堆栈和涉及的代码而不是继续打补丁。设置这三道闸之后自愈循环从“永不放弃的僵尸”变成了“高速但不失控的自主流程”大多数问题两三轮内就能收敛少数收敛不了的也会带着完整失败上下文交回给你而不是把日志刷没了。4. Routine 脚本化架构把复用手法变成“团队资产”4.1 从日常重复劳动到 Routine为什么值得投入多 Agent 编排和闭环自愈解决的是“任务怎么执行”但还有一个更普遍的问题被忽略了团队里每个人都在重复造轮子。A 让 Claude Code 做代码审查总结的质量不错B 也在做同样的事但 Prompt 写得稀碎输出格式也是自由发挥C 想生成 CHANGELOG每次都要花十分钟把各种上下文塞给 Agent。Routine 脚本化架构的思路就是把这一条条“高频、可重复、有固定流程”的需求沉淀成可复用的脚本模板。一旦固化任何人跑同一个 Routine输入一批参数拿到的都是同一格式、同一质量的输出。它是把个人技巧变成团队资产的最直接手段。4.2 Routine 脚本的核心骨架一个标准的 Routine 脚本不需要多复杂四部分组成就够输入参数、Prompt 组装、Claude Code 调用、结果输出。输入参数决定这次跑的变体比如日志文件路径、diff 范围、目标模块名Prompt 组装是把参数填进一个写死的模板里模板里会强调输出格式和必须遵循的工作流Claude Code 调用走非交互模式claude -p配合--output-format拿到结构化结果结果输出把 stdout 里的内容落盘到指定文件比如CHANGELOG.md或review-report.md。流程本身不新鲜但价值在于模板里的“工程智慧”是凝固的——比如审查模板里写了“必须检查 N1 查询和越权漏洞”这些是你多次踩坑后总结出来的团队成员在跑同一套脚本时自动继承了这些经验。4.3 三个可以直接抄的 Routine 脚本第一个是代码审查 Routine。入参是目标和对比分支Prompt 里要求审查 Agent 只读 diff、不直接改代码、按 BLOCKER / MAJOR / MINOR 三级输出问题清单最后给出 PASS 或 FAIL。我习惯让它把审查结论输出为 Markdown 表格方便直接粘贴到 MR 描述里。#!/usr/bin/env bash set -euo pipefail TARGET${1:-.} BASE_BRANCH${2:-origin/main} PROMPT请审查目录 ${TARGET} 中相对 ${BASE_BRANCH} 的全部改动。要求只读 diff不修改任何文件检查逻辑错误、边界条件、SQL注入、越权访问、并发安全按 BLOCKER / MAJOR / MINOR 分三级输出最后给 PASS 或 FAIL 并说明理由。用 Markdown 表格输出。 claude -p $PROMPT --output-format text第二个是CHANGELOG 生成 Routine。入参是起始提交点Prompt 里要求它读取 git log按类型分组feature / fix / refactor / docs / test输出可读性强的更新日志。它内部会调用 Bash 执行 git 命令我通过--allowedTools把允许的工具收窄到Bash, Read, Glob, Grep。第三个是依赖升级 Routine。这个比较重我把它做成了带自愈闭环的版本先让 Agent 读取 package.json 和测试报告识别可安全升级的依赖升级后强制跑完整测试测试失败的话读取错误信息继续修复最多重试三轮最后生成一份升级报告说明改了什么、测试结果如何、残余风险在哪。4.4 版本管理与沉淀Routine 也要走 GitRoutine 脚本一旦开始被团队共用就应该纳入版本管理。我把所有 Routine 放在一个独立的routines/目录里和项目代码一起走 Git这样每次修改都有历史记录谁在哪个环节加了新的检查项一目了然。沉淀 Routine 的时机也有讲究。不是一开始就大动干戈写一堆脚本而是在日常协作里留一个敏感度“同一件任务的调教对话如果出现超过三次就把它固化成 Routine”。这个阈值我个人觉得挺关键太早沉淀容易被个性化需求绑架太晚沉淀就变成重复劳动了。把 Routine 和前面的多 Agent 编排结合起来威力会更大Routine 负责定义“任务长什么样”多 Agent 负责“任务由谁执行”自愈闭环负责“怎么保证执行质量”三者是天然互补的关系。5. 实操落地从零到一搭建战斗工作流5.1 安装与基础配置安装这块其实没什么悬念Claude Code 官方提供了非常标准的安装方式。如果本机已经有 Node.js 18 以上的环境一条命令就完了npm install -g anthropic-ai/claude-code装完后跑claude --version确认版本然后直接在终端敲claude进入交互模式按引导完成官方账号认证。这里有一点要注意命令行的更新有个专属命令claude update别用 npm 全局更新去覆盖容易把本地配置弄丢。如果你不习惯终端工作VS Code 里也有官方扩展直接在扩展市场搜 Claude Code 安装装完重启窗口就能在侧边栏看到 Agent 会话面板多 Agent 的运行状态可视化比终端清晰不少适合刚开始摸索编排的新手。目前 Claude Code 可以接入第三方模型服务商比较常见的做法就是通过兼容网关改环境变量指向 DeepSeek、Qwen、GLM 这类国产模型成本能比官方模型低好几倍。我这里提醒一句切换模型前务必确认目标服务的服务条款和使用权限很多账号封禁和 API 滥用问题都出在这个时候省钱的愿望是好的合规边界是底线。我除了特殊场景主力流程还是用官方模型稳定性和工具调用质量对工作流的影响是决定性的。5.2 搭建三级 Agent 流水线我推荐的起步配置是三级流水线规划、执行、审查再加一个可选的修复。第一步在.claude/agents/下建三个文件planner.md、implementer.md、reviewer.md。每个文件里的身份描述要具体到“什么情况下该用我”和“我主要动哪些工具”这样主管 Agent 才能准确调度。第二步在 CLAUDE.md 里写清楚流水线规则最关键的一项是“接到需求后必须先调用 planner 产出 plan.md不能直接开始改代码”。这就是把编排方式固化进了项目基因。第三步跑一遍真实需求观察主管 Agent 的调度行为。大部分坑都出在 planner 产出文档不结构化导致 implementer 看不懂。我的解法是在 planner 的 Prompt 里明确要求输出格式固定成“目标 / 改动文件清单 / 每个文件的具体改动点 / 验证步骤”四段式implementer 只需要按图施工。5.3 把闭环自愈接进流水线流水线搭好后闭环自愈是最后一道拼图。我先在生产环境的 settings.json 里配好 PostToolUse Hook让它捕获每次 Bash 调用的退出码再在 CLAUDE.md 里定义全局的 Definition of Done最后在 implementer 和 reviewer 的 Prompt 里都加上“自愈规则”——测试失败必须查看.agent-workspace/test-status状态文件并继续修复累计重试达到 3 次必须提升给人类。实际效果最直观的变化是我提一个需求后terminal 里能看到流程完全自动跑完。规划 → 写代码 → 测试 → 挂了 → 修复 → 再测 → 通过 → 审查 → PASS。整个过程不需要我敲一个字。单步聊天时代这个循环可能需要我人工介入七八次而现在除非遇到自愈循环无法收敛的硬骨头否则我只需要在最后看结果报告。5.4 把常用流程固化成 Routine流水线稳定之后我开始把执行频率高的流程固化成 Routine。建议从代码审查和 CHANGELOG 这两个低风险、见效快的场景入手先跑通再往复杂场景扩展。把 Routine 接入日常工作后还有一个细节要注意claude -p的非交互模式默认可能有命令权限限制需要显式声明允许哪些工具。我习惯在脚本里多加一层防护把--allowedTools收紧到刚需工具宁可多写几个也不要用“允许所有工具”的宽松模式。权限越窄自动化越安全。另外Routine 的输出最好统一落盘而不是打到 stdout 就完事。比如 code review 报告我会让它同时写到review/目录下带时间戳的文件里方便追溯。毕竟自动化的价值是省时间但你不想为了找一份三周前的报告花掉省下来的时间。6. 常见问题排查实录6.1 多 Agent 上下文互相污染症状审查 Agent 在审查时“脑补”了执行 Agent 才了解的内部细节结论开始变得不可信或者执行 Agent 引用了规划 Agent 没写进 plan.md 的内容。排查思路是先确认交接文件是不是唯一的输入来源再看 Subagent 的 tools 里是不是给得太宽让它有能力乱翻上下文文件。解决方案通常两步一是强化职责边界在 Subagent Prompt 里写明“你只能基于 .agent-workspace/ 下的交接文件做判断”二是把不需要的工具从 tools 字段里删掉权限越少胡思乱想越少。6.2 自愈循环卡死之前提过的 47 轮血案就是典型。现在我的排查顺序是先看.agent-workspace/fix-attempts.md里的记录确认 Agent 是不是在反复尝试同一个方案如果是说明失败原因没有有效传递给下一轮检查 Hook 捕获错误信息时是否足够完整——只捕获 printf 最后三行往往会漏掉关键报错再者确认有没有设置最大重试次数没有的话立刻加上这是防止账单爆炸的保命闸。6.3 非交互模式下的权限、超时与输出截断claude -p跑长任务时我遇到过两种常见状况一是脚本里需要执行的命令被默认策略拦了表现是任务频繁中断一查日志全是 permission denied二是超时因为默认的非交互任务可能没有像交互模式那样良好的进度反馈。解决方案分别是显式声明--allowedTools、给外层脚本加 timeout 和重试机制。正则表达式在 shell 脚本里拼接时容易踩引号地狱的坑。解决方法是把 Prompt 写成单独的.md模板文件通过--prompt或占位符替换来加载不要硬拼在 bash 字符串里。把 Prompt 写进独立模板文件后还有一个好处是模板内容可以走 Git 评审而不是藏在脚本的字符串表达式里。这里的针对性建议是任何超过 10 行的 Prompt 都不该内嵌在脚本中。等价于你在代码里硬编码一坨 SQL 查询只给字符串拼接参数——你没做到“代码与数据分离”那你就等着维护翻车。6.4 成本失控API 账单比写代码快多 Agent 编排和自愈闭环真正让人肉疼的是 token 消耗比单步聊天大得多——因为现在 Agent 真的在自主循环。我的成本控制三板斧第一给自愈重试次数设硬上限即使固定 5 轮第二给高频 Routine 配一个专用于该 Routine 的轻量模型第三任务规模大时主动把 Long-running 任务拆成几段每段用独立上下文和独立预算避免单次长时间运行超出预期上限。还有个小技巧是分类预算。团队里跑 Routine 的是内部任务用轻量模型跑复杂架构设计走多 Agent用强模型跑。两类场景分开账单才能分开管理。6.5 输出格式不稳定自愈闭环和 Routine 依赖结果可信度而结果可信度有时会被“模型自由发挥”打败——输出 Markdown 表格明明指定了但某一次它偏偏用列表。我的化解方式是在 Routine 里加一个“准结构化”的验证步骤给 claude 一条指令要求它先按照指定 JSON Schema 输出中间结果再由外层脚本用jq做关键字段校验失败就重新触发一次。这样即便 LLM 偶尔幻觉也只是这一条重跑几分钟而不是埋下“看起来成功实际失败”的定时炸弹。7. 我的个人体会与阶段性总结这一套架构跑了大概两个月后我最大的感受不是“AI 变强了”而是工程方法论把 AI 的上限真正顶了出来。单步聊天里AI 是一个时而聪明时而拉胯的临时工在多 Agent 自愈 Routine 的架构里它变成了一个稳定、可度量、可复用的团队新成员——甚至有几次我交出去的活人力同事完全没发现有一半代码是 Agent 独立完成并自测通过的。最后再分享一个小细节无论你搭不搭这一整套给 Agent 写好完成定义永远不亏。我见过的大部分“AI 干活不靠谱”案例都不是模型不行而是你根本没告诉它什么叫“干完”。先把 Definition of Done 写清楚再谈多 Agent再上自愈再沉淀 Routine——这个顺序走下来每一步的收益都会被前一步放大。我的建议是别想着一天全部落地从第一次多 Agent 编排开始给每一层加一点约束流量和稳定性的拐点会很快出现。