企业官网建设流程全解析

第一次真正感受到 Claude Code 多 Agent 编排的威力，是在一次跨模块重构里。之前我一直把它当“加强版单步聊天”用，让它改改文件、解释报错、写写测试，虽然方便，但遇到需要同时改后端接口、前端调用、数据库脚本的任务时，对话会越拉越长，上下文越滚越乱，经常修好 A 模块又弄坏 B 模块。后来我把任务拆成多个子 Agent 并行推进，配合闭环自愈让它在跑测试失败后自己修自己，再把这些高频流程固化成 Routine 脚本化架构，整个项目的推进速度和稳定性完全不一样。这篇文章我就把这套玩法的拆解思路、落地步骤和踩过的坑一次性讲清楚，适合已经在命令行里用过 Claude Code、但还没系统性用过多 Agent 的读者。

1. 单步聊天的天花板：为什么复杂任务总会卡在半路

1.1 一次实际重构暴露出的问题

我手头有个老项目，接口层和前端调用之间有个历史遗留的字段命名差异，牵一发动全身。按以前的习惯，我会在 Claude Code 里单步对话，先说“帮我找出所有用到旧字段的地方”，然后等它列出文件清单，再说“帮我逐个改成新字段”，最后再让它改测试。听起来没问题，但真正执行的时候，它在前 20 轮还能保持清醒，到后面经常会忘了最开始定的命名规则，自作聪明地引入新风格；或者改完接口层之后，前端那部分因为上下文里被太多中间讨论污染，出现了张冠李戴。

单步对话最大的问题不是模型能力，而是上下文管理。Claude Code 在主会话里会积累全部历史记录，任务越复杂，历史越长，模型在生成时就越容易被早期讨论带偏，回复延迟也会肉眼可见地上升。更难受的是，单步模式天然是串行的——你让它先改完 A 再改 B，它在处理 B 的时候没法同时验证 A 的测试结果，整个流程变成一条没有并发的生产线。

1.2 单步模式的三个结构性缺陷

我把单步聊天模式在多任务场景下的问题归纳成三个结构性缺陷，这也是后来我坚定转向多 Agent 编排的原因。

第一，上下文不可控。主会话的每一轮问答都会成为后续生成的前置信息。小型任务没问题，但跨文件、跨模块的大型任务，历史里大量无关内容会稀释真正的约束条件。模型本质上是在“模糊的记忆”里做决策，而不是在一个干净的任务容器里执行。

第二，串行等待浪费严重。单步模式下，Agent 只能一次做一件事。可真实的开发任务通常有天然的并行分支，比如前端参数校验、后端接口字段调整、数据库索引优化，这三件事本身就是独立的。强行串行不仅慢，还让每一步的结果互相干扰。

第三，没有主动纠错回路。单步对话中，命令执行失败了，模型只会把报错贴给你，然后等你下一条指令。它不会自己去跑一遍测试、分析失败原因、改完再跑。这就像请了个实习生，干一步停一步，每一处异常都要你来拍板，效率自然上不去。

这三条叠加起来，复杂项目的“单步聊天体验”就是：前期顺利、中期挣扎、后期失控。真正要摆脱这种状态，就得把 Claude Code 从“对话助手”升级成“多 Agent 协同系统”，也就是标题里说的多 Agent 编排。

2. 多 Agent 编排怎么落地：让多个子 Agent 各自干活

2.1 子 Agent 机制的基本拆解

多 Agent 编排的核心不是“多个模型同时聊天”，而是由主 Agent 作为编排器，把任务拆解成多个子任务，分发给具有独立上下文的子 Agent 去执行，最后再汇总结果。每个子 Agent 只看到自己那份任务描述和必要的工具权限，不会背着整个项目的对话历史干活，token 消耗也更可控。

我在实际使用中把子 Agent 的用法分成三类。第一类是单次任务型，主 Agent 通过任务调用派发一个一次性子 Agent，让它在隔离上下文里完成分析或修改，然后返回结构化结果。第二类是后台并行型，同时启动多个子 Agent 处理互不依赖的任务，比如一个去梳理接口文档，一个去扫描测试用例，一个去检查数据库脚本。第三类是长期协作型，给某些子 Agent 固定角色和能力边界，比如设置一个专门负责测试的 QA Agent、一个负责代码审查的 Reviewer Agent，让它们在一个项目周期里反复被调用。

这种设计的价值在于，主 Agent 相当于项目经理，子 Agent 相当于多个可以并行干活、互不干扰的执行者。每个执行者拿到的需求都是明确且精简的，执行完只汇报结论，不把所有过程细节都塞回主上下文。

2.2 一份可复制的多 Agent 编排示例

分享一个我实际用过的编排描述方式。下面这段不是我发明的什么神秘语法，而是我在 Claude Code 里让主 Agent 把任务拆给子 Agent 时常用的表述，它会触发子 Agent 的并行执行路径。

请用多 Agent 模式处理这次接口重构： 1. 分配一个子 Agent 去扫描 src/api 目录下所有接口定义，整理出还在使用旧字段的位置，按文件路径输出 JSON 清单。 2. 分配另一个子 Agent 去扫描 frontend/src 下的所有请求函数，找出旧字段对应的前端映射位置，同样输出 JSON 清单。 3. 两个子 Agent 完成后，汇总结果，把清单合并成一份改动手册，标出每个文件需要修改的函数名和行号。 4. 清单确认无遗漏后，再分配执行型子 Agent 按顺序修改后端与前端文件。

关键点在于第一轮任务是“只扫描、不改动”，第二轮才进入“执行修改”。这能避免子 Agent 在信息不全的情况下自作主张。我遇到过的典型翻车就是让子 Agent 边扫描边修改，结果它把同名不同义的字段当成同一个，改出来全是问题。先摸清全貌再动手，这个顺序不要省。

2.3 编排中容易被忽略的执行顺序与依赖

多 Agent 并行不是无脑并行，依赖关系必须理清。我习惯用阶段门的方式管理：第一阶段只做信息收集，所有子 Agent 可以并行；第二阶段做方案确认，主 Agent 汇总所有收集结果后，生成统一的修改计划；第三阶段才是执行修改，执行型子 Agent 可以针对不同模块并行，但每个模块改完都要经过自检。

这里有个容易踩的坑：当你把多个修改任务同时派给不同子 Agent，而它们操作的是同一个文件的相邻区域时，文件写入冲突几乎是必然的。我的经验是按“文件边界”而不是“任务边界”来拆分并行单元。一个文件只交给一个子 Agent 去改，跨文件的协调由主 Agent 完成，这样既保留并行度，又不会出现互相覆盖的混乱。

依赖关系的表达也很重要。我通常会在任务描述里直接写明“等待前一阶段完成后再开始”，配合 Claude Code 的任务执行机制，主 Agent 会自然形成一个有先后顺序的调度图。看起来像废话，但很多人在实际使用中完全没这层设计，导致子 Agent 一拥而上，输出结果七零八落。

3. 闭环自愈：让 Agent 学会自己修自己的 Bug

3.1 闭环自愈的运行逻辑

闭环自愈这个词听起来高级，拆开看就是一条非常朴素的循环链：执行命令 → 观察结果 → 识别失败 → 分析原因 → 修改代码 → 重新执行。传统模式下，这条链的每一环都要人来接续；闭环自愈则是让 Claude Code 自己在循环里跑通，直到命令返回成功，或者到达设定的重试上限。

我在实际项目里最常用的场景是修测试。以前跑一遍单测，发现有红，我得把几百行报错日志复制粘贴给模型，然后它给出一版修复建议，我再手动改文件、再跑一遍。现在我会直接在 Claude Code 里起一个自愈循环任务，大概这样描述：

运行 npm test，当前测试失败率较高。请用闭环方式处理： 1. 执行测试命令，完整读取失败用例的报错信息。 2. 分析失败集中在哪几个模块，优先处理公共依赖层面的错误。 3. 修改对应源码或测试代码，注意不要为了过测试而删断言。 4. 修改完成后重新执行测试，如果仍有失败，继续修复，最多循环 5 轮。 5. 每轮结束后用一行摘要说明剩余失败数量。

实测下来，这种模式对“接口返回结构变化导致测试断言失败”“空指针/未定义变量”“配置项名称对不上”这类问题效果非常好。模型能读取真实报错，修改后又立刻验证，整个循环不需要我介入。项目里那种改了字段类型没同步改测试的小问题，一晚上可以自动修掉一大堆。

3.2 用 CLI 命令和 Hooks 把“修复”固化下来

闭环自愈要稳定运转，除了会描述任务，还得把周边的执行环境配好。Claude Code 的 CLI 本身就支持一些有用的参数，比如--continue可以基于上一次会话继续跑，--resume可以恢复到指定会话，-p模式适合跑无人值守的脚本。我常用的一个组合是把修复任务写成一条命令，在 CI 环境的低谷时段自动跑一遍。

claude -p "闭环修复 src/core 下的单元测试失败，循环最多5轮，每轮输出失败数量" \ --allowedTools "Bash,Read,Write,Edit" \ --dangerously-skip-permissions

注意--dangerously-skip-permissions这个参数不是让你随便用的。它跳过权限确认是为了实现无人值守，但副作用是 Agent 可以自由改文件和执行命令。我只在隔离环境、代码已提交、可随时回滚的前提下用它。在有重要数据的机器上，我宁可多几轮手动确认，也不要为了省事把风险敞开。

除了 CLI 参数，Hooks 是另一个把闭环自愈固化的关键设施。Hooks 允许你在特定事件前后触发自定义脚本，比如在 Agent 执行某个 Bash 命令之后，自动跑一段日志采集脚本，把测试结果喂回给主会话。我在settings.json里配过一个采集测试失败的 Hook，作用是在npm test执行出现非零退出码时，把失败文件列表整理成摘要，附加到后续对话上下文中。这样模型修复时就不用从海量日志里自己捞重点。

{ "hooks": { "PostToolUse": [ { "matcher": "Bash(npm test)", "hooks": [ { "type": "command", "command": "node scripts/collect-failures.js" } ] } ] } }

Hooks 的字段格式和 matcher 写法在不同版本里可能有细节差异，建议以你当前所装版本的官方文档为准。我的核心建议是：把“采集失败信息”和“结果回传”自动化，而不是让模型在每一轮都从头解析输出。这会显著降低多轮自愈时的 token 浪费。

3.3 自愈失效的场景：哪些错不能指望 AI 修

我也得泼盆冷水，闭环自愈不是万能的。踩过几次坑之后，我总结了几类不能指望它自己修的问题。

第一类是环境层面的问题，比如 Docker 守护进程没启动、Nginx 配置语法错误导致服务起不来、Python 虚拟环境路径不匹配。这类问题不在代码逻辑里，模型即使能读到报错也很难凭现有信息修复，因为缺失的是环境上下文。我的做法是在任务描述里先把“环境状态检查”作为第一步，让子 Agent 执行docker ps、node -v这类探活命令，把环境信息前置到上下文中，再进入修复循环。

第二类是权限和数据安全问题。让 Agent 在无人值守模式下直接改生产数据库脚本，风险极高。它可能分析出“删除某条数据”是最短路径，然后就真干了。我的经验是给这类任务加一道“只读前置阶段”：先让它输出修复方案和影响面，确认无误后，再以手动切换的方式放行写操作。

第三类是测试本身有缺陷，断言写得不对，期望值是过时逻辑。这种时候模型会反复修改被测代码去迎合错误的断言，形成一种“劣质均衡”。我后来会在自愈任务里明确一句“如果修改源码来迎合测试，请停止并说明原因”，相当于给自愈循环加了一个安全阀，防止它在错误的方向上越陷越深。

4. Routine 脚本化架构：把高频流程沉淀成可复用脚本

4.1 Routine 不是 Prompt 模板，是有状态的执行脚本

很多人以为“把提示词写成模板”就是 Routine 化了，其实差的远。Prompt 模板解决的是“说得清楚”，Routine 脚本化解决的是“做得可复用”。一个真正能沉淀下来的 Routine，至少要包含四样东西：触发场景、执行步骤、验收标准、失败时的回退策略。

以发布流程为例。传统做法是每次发版都在对话里重新交代一遍“先跑测试，再构建，再打 tag，再推送，再通知”。这些话每次说都会消耗上下文，而且每次的细微差异会让 Agent 产生不同理解。Routine 化之后，我把整套流程写成一个固定脚本，存在项目里的命令目录中，每次需要发版时直接调用，Agent 按部就班执行，执行完回填结果。

这和“把话术背下来”有本质区别。Routine 把流程、标准、策略固化成了项目资产，任何人接手都能跑出相同质量的结果，不再依赖某一次对话里灵光一现的描述。

4.2 一个可以照抄的 Routine 脚本骨架

我在项目里习惯这样组织文件结构：

.claude/ ├── commands/ │ ├── review.md │ └── release.md ├── agents/ │ └── qa-agent.md ├── hooks/ │ └── collect-failures.js ├── settings.json └── CLAUDE.md

commands目录对应的是 Claude Code 的斜杠命令：你把一个 Markdown 文件放进去，文件名就是命令名。比如release.md就对应/release。文件内容会作为指令模板被加载进当前会话。我写release.md时，会把步骤、验收标准和回退策略都写清楚，下面是一个简化示例：

# 发布 Routine 当用户输入 /release 时，执行以下流程： 1. 运行 npm run test，全部通过才进入下一步；如果失败，直接停止并汇报失败原因。 2. 运行 npm run build，确认产物目录生成且包含最新 commit hash。 3. 读取 package.json 的 version 字段，按语义化版本规则增加 patch 版本号并提交。 4. 执行 git tag v<新版本号> 并推送 tag 到远端。 5. 推送完成后，输出发布摘要：版本号、commit hash、变更文件数量。 6. 如果第 1 步测试未通过，不要尝试修改测试来强行通过，改为汇报失败清单。

这个文件的好处是，任何会话里输入/release，Agent 都能拿到同一套执行标准。你不用重复解释，它也不会临时发挥。我曾经在没写这个 Routine 前让 Agent 发过版，它的“发挥”是跳过了测试直接构建，事后想想都后怕。

4.3 从“一次性任务”到“可维护 Agent 工厂”

Routine 脚本化的终极形态，是让项目里的高频任务全部变成可组合的模块。我现在的习惯是：每次完成一次高质量的多 Agent 任务，就把任务描述中的可复用部分抽出来，沉淀成一个新的命令文件。比如“扫描旧字段引用”“修复单测失败”“生成接口变更日志”，这些都会变成一个个独立命令，然后在更上层的发布 Routine 里按顺序调用它们。

这个过程像搭积木。单个 Routine 解决单一问题，组合 Routine 解决复杂链路。而且 Routine 之间可以通过环境变量或临时文件传递中间结果，相当于脚本化架构里的“管道”。实际操作中我不追求一次设计完美，而是先跑通一次，再根据失败点迭代。

CLAUDE.md 在这个架构里扮演“项目宪法”的角色。所有子 Agent 在启动时都会读取它，所以我会在里面写清项目结构、编码规范、禁止事项。Routine 负责“怎么做”，CLAUDE.md 负责“在什么约束下做”。两者配合，才能保证可复用的流程不破坏项目特有的边界。

5. 从安装到接本地模型：这套架构落地的环境准备

5.1 安装与 VSCode 接入的实测记录

新机器上我一般直接用 npm 安装 Claude Code，装完先确认版本和升级通道。社区里常见的几条基础操作：

npm install -g @anthropic-ai/claude-code claude --version claude update

Node 环境版本最好保持较新，某些老版本 Node 上装完后启动会报错。VSCode 里有对应的插件，安装后在编辑器里打开项目，通过侧边栏面板就能启动一个绑定当前工作区的会话。和我纯命令行使用相比，VSCode 版本的好处是能直接看到文件 diff，方便核对 Agent 的修改是否符合预期。

首次在项目里启动时，我建议先让它生成一份初始化的项目上下文文件，把目录结构、技术栈、启动命令等信息写进去。这一步看起来简单，但对后续多 Agent 编排的质量影响巨大：子 Agent 每次启动都会读这份上下文，信息越准确，任务跑偏的概率越低。

5.2 第三方模型与本地模型的接入姿势

标题里提到“多 Agent 编排”，很多人误以为只有官方订阅才能用。实际使用中，社区里常用类似 cc switch 这类工具来切换 API 接入点，把 Claude Code 的模型通道指到其他兼容服务上，比如 DeepSeek、通义千问 Qwen、智谱 GLM 这些第三方模型，或者通过 LM Studio 这类软件接入本地模型。

我试过把低风险任务接给本地模型跑，比如代码格式化、注释翻译、简单脚本生成。这类任务对工具调用能力要求不高，本地模型也能胜任，而且数据不出机器，隐私上更安心。但涉及多 Agent 编排的复杂场景，我仍然建议用官方模型或能力更强的云端模型。原因是编排任务高度依赖工具调用的一致性，子 Agent 要能准确触达 Read、Write、Bash 这类工具，第三方模型受限于工具调用协议，经常会出现“该调工具时不调，不该调时乱调”的情况。

接第三方模型时，要特别注意 API 的兼容层是否完整支持 Anthropic 的工具调用协议。只支持普通对话接口的服务，即使在 Claude Code 里接上了，也只能做单步聊天，跑不了真正的多 Agent 编排。判断方法很简单：让它执行一个需要读文件再修改文件的多步骤任务，如果中途卡住或答非所问，基本就是工具调用能力不达标。

5.3 踩坑清单：Windows 64 位兼容、组织禁用、地区不可用

安装和使用这阶段，我帮朋友排查过不少问题，有几类高频坑值得单独列出来。

有用户在 Windows 上遇到“与 64 位版本的 Windows 不兼容”这类报错。这种情况通常不是程序本身不兼容，而是下载到了不对应的安装包版本，或者系统的某些运行库缺失。优先做两件事：一是从官方渠道重新下载最新安装包，确认安装包架构与系统位数一致；二是检查 PATH 环境变量，确保命令行能正确找到可执行文件。

另外两类提示很吓人但解法很简单：一类是your organization has disabled claude subscription access for claude code，这是组织级策略限制了订阅权限，个人用户只需联系管理员，或者用个人账号登录即可；另一类是claude code might not be available in your country，这是官方基于支持地区列表做的可用性限制，正确做法是查看官方最新的支持地区列表，确认账号订阅状态，而不是尝试非常规规避手段。这些限制本身就是为了合规，没必要去绕。

网上还有一些“XX 网盘下载的安装包”，我劝你们别用。这类来路不明的包可能被二次打包，轻则功能异常，重则有证书和隐私风险。宁可慢几分钟走官方渠道，也别图省事给自己埋雷。

6. 从单步到编排的转型：我的实操建议

6.1 什么任务值得编排，什么任务不值得

多 Agent 编排虽然强大，但不是所有任务都应该用。我自己的判断标准是：如果任务需要修改两个以上文件、涉及多个模块之间的数据流、或者有“改完必须跑验证”的需求，才考虑编排。而像“帮我解释这段代码”“把这个文件里所有 TODO 列出来”这种轻量任务，单步聊天就够了，强行拆成多个子 Agent 反而增加 token 消耗和响应延迟。

还有一种情况我建议慎重编排：任务目标本身不清晰，需要在探索中逐渐明确。这种情况主 Agent 自己都还在摸索方向，强行拆解子任务只会把模糊的目标放大成多个方向的错误执行。先单步聊清楚方案，再进入编排执行，才是正确顺序。

6.2 成本与 Token 控制

多 Agent 编排虽然省时间，但 token 消耗不一定更低。并行子 Agent 会同时消费额度，如果任务拆得太碎，光来回传递中间结果的开销就能超过单步模式的成本。我的经验是控制好单次编排的子 Agent 数量，三个以内为佳，每个子 Agent 的任务目标要集中，避免一个子 Agent 干三件小事。

闭环自愈也是 token 消耗大户。每轮“报错-分析-修改-重试”都会产生完整上下文。我通常会给自愈循环设定严格轮数上限，并在任务描述里要求“每轮只输出关键差异”，避免模型把无关代码也打印一遍。另外，阶段性使用第三方模型或本地模型承接低风险子任务，也能有效拉低收入模型的调用成本。

6.3 渐进式引入路线

不要一上来就把整个项目改造成多 Agent 编排架构，那样你会发现连排查问题都变得很难。我推荐一个渐进式路线：

第一阶段，先把 CLAUDE.md 写完整，把项目的结构、规范、命令梳理清楚。这个阶段不用编排，只把基础打牢。第二阶段，把重复使用的流程逐步抽成commands下的 Routine，比如每次都重复交代的“跑测试后修改”的流程，先固化成一个命令。第三阶段，开始尝试多 Agent 并行，从两个子 Agent 的“扫描+执行”组合开始，跑通了再增加并行度。第四阶段，给高频任务配置 Hooks 和自愈循环，让 Agent 在失败时自动进入修复链路。

每进入一个新阶段，都要留出时间观察效果，不要贪多。我自己就是从一条“测试修复”链路开始做闭环自愈，跑了一周确认稳定了，才把发布流程也 Routine 化，然后才扩展到更多场景。

多 Agent 编排、闭环自愈、Routine 脚本化这三个能力，本质上是同一件事的三个层次：先用编排把复杂度拆开，再用自愈把执行质量兜住，最后用 Routine 把经验留下来。我现在接手一个新项目，做的第一件事已经不是去读代码，而是先建好这三层基础的骨架。框架搭稳了，后面所有复杂任务都能稳稳接住。