企业官网建设流程全解析

1. 从单步对话到多 Agent 协作：为什么需要架构升级

用 Claude Code 写代码这件事，很多人一开始的用法都差不多：打开终端，敲一句需求，等它回一段代码，复制粘贴，再敲下一句。这种单步聊天式的交互在写小脚本、改单个函数的时候确实够用，但只要任务稍微复杂一点，比如要重构一个模块、排查一个跨文件的 bug、或者搭一套完整的脚手架，问题就全暴露出来了。

最典型的痛点有三个。第一是上下文断裂，你让它改 A 文件，它改完你再去改 B 文件，两轮对话之间它已经忘了 A 文件里改了什么，导致前后逻辑对不上。第二是无法自验证，它写完代码不会自己跑一遍，你得手动执行、手动把报错贴回去，一来一回效率极低。第三是重复劳动，同一套流程（比如"读需求→改代码→跑测试→修报错"）每次都要你手动串一遍，没有任何沉淀。

我踩过最深的坑是一次做数据清洗脚本，涉及 5 个文件的联动修改。单步模式下我足足来回贴了 30 多次报错，每次它都只改一个文件，改完另一个又崩了。后来我才意识到，问题不在于模型能力，而在于交互架构——我把一个本该并行、可编排、能自愈的任务，硬塞进了一个线性的单步对话里。

这篇文章要拆的就是怎么跳出这个坑。核心是三件事：多 Agent 编排（把大任务拆给多个专职 Agent 并行/串行处理）、闭环自愈（让 Agent 自己跑、自己看报错、自己修，形成循环）、Routine 脚本化（把重复流程固化成可复用的脚本）。这三者叠起来，才算是把 Claude Code 从"聊天工具"用成了"工程流水线"。适合已经能跑通基础安装、想进一步提升自动化程度的开发者，纯新手也能看懂思路，但实操部分建议先补一下命令行基础。

2. 多 Agent 编排的核心思路与方案选型

2.1 为什么单 Agent 会撞墙

单个 Agent 的本质是一个"串行执行器"：它一次只能推进一个步骤，且所有状态都压在同一个上下文窗口里。任务一复杂，上下文就会被历史对话、文件内容、报错信息塞满，模型开始"遗忘"早期指令，输出质量断崖式下跌。这不是模型不行，是架构决定的——就像让一个人同时干产品、开发、测试三个角色，他一定会乱。

多 Agent 的思路很朴素：把角色拆开，每个 Agent 只干一件事，通过明确的输入输出接口协作。一个负责规划（Planner），一个负责写代码（Coder），一个负责跑测试和验证（Verifier），必要时再加一个专门查文档的（Researcher）。每个 Agent 的上下文都很干净，只装自己那部分信息，输出质量自然稳定。

2.2 三种主流编排模式怎么选

实际落地时，编排模式基本逃不出这三种，我按适用场景列个表：

我的建议是从串行流水线起步。原因很实在：串行模式每一步的输入输出都是显式的，出问题一眼能定位到是哪个 Agent 的锅。等你把串行跑顺了，再针对耗时长的环节做并行化。一上来就搞层级编排，调试起来会让你怀疑人生。

2.3 Agent 之间怎么"对话"

多 Agent 协作最容易被忽略的是通信协议。它们不能像人一样自由聊天，必须约定好数据格式。常见做法是用结构化的 JSON 传递任务和结果，比如：

{ "task_id": "refactor-001", "role": "coder", "input": { "file": "src/utils/parser.js", "instruction": "把回调风格改成 async/await" }, "output": { "status": "success", "changed_files": ["src/utils/parser.js"], "diff_summary": "3 处回调改为 await" } }

这样设计的好处是，Verifier Agent 拿到changed_files就知道该去验证哪些文件，Planner 拿到status就知道要不要继续下一步。接口一旦定死，Agent 之间就是松耦合的，你可以随时替换某个 Agent 的实现而不影响整体。

注意：不要用自然语言做 Agent 间的通信。自然语言有歧义，一旦某个 Agent 理解偏了，错误会沿着流水线一路放大，最后你根本找不到是哪一步出的问题。

3. 闭环自愈：让 Agent 自己跑、自己修

3.1 闭环自愈的本质是一个反馈循环

所谓闭环自愈，说白了就是给 Agent 装上"眼睛"和"手"：眼睛是执行结果（编译输出、测试报告、运行日志），手是修改代码的能力。流程是这样的——Agent 写完代码，自动执行验证命令，捕获输出，如果失败就把报错喂回给自己，让它分析原因并修改，然后再验证，直到通过或达到重试上限。

这个循环的价值在于把人从"贴报错"的体力活里解放出来。以前你是那个在模型和终端之间来回搬运信息的人，现在这个搬运工由脚本自己当了。

3.2 循环的四个关键环节

一个健壮的自愈循环必须包含这四步，缺一不可：

1. 执行：调用真实的构建/测试命令，比如npm test、pytest、cargo build，而不是让模型"想象"结果。
2. 捕获：把 stdout、stderr、退出码全部抓下来，尤其是退出码，它是判断成功与否最可靠的信号。
3. 诊断：把报错信息结构化后喂回给 Agent，最好带上出错的文件和行号，减少它的猜测空间。
4. 修复与重试：Agent 输出修改，重新进入执行环节，同时记录重试次数。

3.3 重试上限与熔断设计

这里有个必须强调的经验：一定要设重试上限。我见过有人不设上限，结果 Agent 陷入死循环，一个下午烧掉大量额度还在原地打转。通常设 3 到 5 次比较合理，超过就停下来，把当前状态和所有尝试记录输出给你，由人来判断。

熔断的另一个维度是错误类型识别。如果报错是"依赖没装"这种环境问题，重试一百次也没用，应该直接终止并提示你手动处理。只有"代码逻辑错误"这类 Agent 能修的问题，才值得进入重试循环。区分方法很简单：看报错是否指向源码文件的行号，指向源码的才交给 Agent 修。

# 一个简化的自愈循环伪代码 MAX_RETRY=5 for i in $(seq 1 $MAX_RETRY); do run_test > result.log 2>&1 if [ $? -eq 0 ]; then echo "验证通过，退出循环" break fi echo "第 $i 次失败，交给 Agent 修复" feed_error_to_agent result.log done

提示：把每次重试的 diff 和报错都存到日志文件里。事后复盘时，你能清楚看到 Agent 是怎么一步步逼近正确答案的，这对调优提示词极有帮助。

4. Routine 脚本化：把重复流程沉淀成资产

4.1 什么是 Routine，为什么它重要

Routine 就是把一套固定的 Agent 协作流程封装成可重复调用的脚本。比如"新增一个 API 接口"这件事，每次都包含：建路由文件、写 controller、加校验、写测试、跑测试。这套流程如果每次靠你手动敲提示词，既慢又容易漏步骤。把它写成 Routine，一条命令就能跑完。

Routine 的价值在于把经验固化成资产。你今天调好的一套流程，明天、下个月、甚至交给同事，都能一键复用。这才是从"会用工具"到"会搭系统"的分水岭。

4.2 Routine 的目录结构设计

我习惯把 Routine 按功能分目录管理，结构大致这样：

routines/ ├── new-api/ │ ├── routine.yaml # 流程定义 │ ├── prompts/ # 各步骤的提示词模板 │ └── validators/ # 验证脚本 ├── refactor-module/ │ ├── routine.yaml │ └── ... └── fix-bug/ ├── routine.yaml └── ...

routine.yaml里定义步骤、每个步骤用哪个 Agent、输入输出怎么衔接、失败怎么处理。这样一套 Routine 就是一个自包含的单元，迁移和分享都很方便。

4.3 参数化：让 Routine 真正通用

写死的 Routine 只能干一件事，参数化之后才能复用。核心是把变化的部分抽成变量，比如文件路径、模块名、接口名。一个参数化的 Routine 定义大概长这样：

name: new-api params: - name: resource required: true - name: method default: GET steps: - agent: planner prompt: "为 {{resource}} 资源规划一个 {{method}} 接口" - agent: coder prompt: "根据规划创建路由和 controller" - agent: verifier command: "npm test -- {{resource}}" retry: 3

调用时只需run routine new-api --resource=user --method=POST，剩下的全自动。参数化的关键是只暴露必要的变量，暴露太多反而增加使用负担。

5. 实操过程与核心环节实现

5.1 环境准备与基础配置

先把基础环境跑通。Claude Code 的安装方式因平台而异，Mac 和 Linux 用户相对顺畅，Windows 用户建议走 WSL，能避开不少路径和权限的坑。安装完成后第一件事是验证版本和登录状态，确保 CLI 能正常调用。

配置层面，我建议单独建一个项目级的配置文件，把模型选择、超时时间、重试次数这些参数集中管理，而不是散落在各个脚本里。这样换项目时只改一处。如果你用的是 VS Code，装好对应插件后可以在编辑器里直接调用，省去切终端的麻烦。

注意：安装过程中如果遇到权限相关的报错（比如写入 npm 全局目录失败），优先检查目录权限，而不是反复重装。这类问题九成是权限配置导致的。

5.2 搭建第一个多 Agent 流水线

我们从最简单的三 Agent 串行流水线开始：Planner 拆任务，Coder 写代码，Verifier 验证。

第一步，定义 Planner 的输出格式。让它输出一个任务列表，每个任务包含目标文件、操作类型、具体指令。格式必须固定，否则 Coder 没法解析。

第二步，Coder 逐个消费任务。每完成一个任务，输出修改的文件列表和 diff 摘要，交给 Verifier。

第三步，Verifier 拿到文件列表后，执行对应的测试命令。通过则标记成功，失败则把报错回传给 Coder 触发自愈循环。

整个链路的编排逻辑用一个主脚本串起来，主脚本只负责调度和状态传递，不掺和具体业务。这样职责清晰，任何一环出问题都能快速定位。

5.3 参数计算：重试次数与超时怎么定

这两个参数没有标准答案，但有个估算方法。重试次数取决于任务的可修复性：纯代码逻辑错误，3 次通常够；涉及复杂依赖的，可以放宽到 5 次。超时时间则看单次执行耗时：如果一次测试跑 30 秒，那单步超时至少设 2 分钟，给模型分析和输出的时间。

我的经验公式是：单步超时 = 命令平均耗时 × 3 + 模型响应时间。模型响应时间按 30 到 60 秒估。宁可设宽松点，超时中断一次的成本，往往比多等一会儿高得多。

5.4 把流程固化成 Routine

流水线跑通后，立刻把它固化成 Routine。把提示词模板抽到单独文件，把参数抽成变量，把验证命令写成可配置项。这一步做完，你就有了一个可以反复调用的"新增接口流水线"。

我实测下来，一个调好的 Routine 能把原本需要 20 分钟手动操作的任务压缩到 3 分钟左右，而且步骤不会漏。更重要的是，它不依赖你的记忆——哪怕隔了一个月再用，流程依然完整。

6. 常见问题与排查技巧实录

6.1 典型问题速查表

6.2 三个独家避坑技巧

技巧一：给报错信息"瘦身"。完整日志动辄几百行，直接喂给 Agent 会挤爆上下文。我的做法是只截取报错堆栈的前 20 行加上出错文件的相关代码片段，信息密度高，Agent 定位更快。

技巧二：验证命令要幂等。自愈循环会反复执行验证命令，如果命令有副作用（比如往数据库写数据），重试几次后环境就脏了。所有验证命令必须保证跑多少次结果都一样。

技巧三：保留"人工检查点"。不是所有步骤都适合全自动。涉及删除文件、改配置、动数据库的操作，我会在 Routine 里插一个暂停点，等人工确认后再继续。全自动很爽，但一次误删的代价可能远超省下的时间。

6.3 调试多 Agent 的通用思路

多 Agent 出问题时，最忌讳的是盯着最终结果猜。正确做法是逐层往上游查：先看 Verifier 的报错是不是真的，再看 Coder 的 diff 是否符合预期，最后看 Planner 的任务拆解是否合理。九成的"Agent 变笨了"，根源都在最上游的任务拆解——任务拆得含糊，后面全乱。

我一般会在每个 Agent 的输出里强制带上"我的理解是……"这样一句话，方便快速核对它的意图是否跑偏。这个习惯帮我省下了大量排查时间。

7. 架构扩展与个人实践体会

7.1 从三 Agent 到可插拔架构

跑顺三 Agent 流水线后，扩展方向有两个。一是增加专职 Agent，比如加一个专门查文档的 Researcher，或者一个专门做代码审查的 Reviewer。二是把 Agent 做成可插拔的，通过配置文件决定这次任务用哪几个 Agent，而不是写死在代码里。

可插拔的关键是统一 Agent 接口：每个 Agent 都实现run(input) -> output这个契约，主调度器只认接口不认具体实现。这样你想换掉某个 Agent，改一行配置就行。

7.2 成本与效率的平衡

多 Agent 不是越多越好。每多一个 Agent，就多一次模型调用，成本和延迟都上升。我的原则是：能用脚本解决的，不要用 Agent。比如文件重命名、格式化这种确定性操作，写个 shell 脚本比让 Agent 干又快又稳。Agent 只用在需要"理解"和"判断"的环节。

7.3 我个人的实践体会

这套架构我用了大半年，最大的感受是：它改变的不是写代码的速度，而是工作的组织方式。以前我是一个"操作员"，在模型和终端之间来回搬运；现在我是一个"流程设计者"，把精力花在怎么把任务拆得更合理、把验证做得更严密上。

踩过的坑也不少。最开始我贪心，一上来就想搞全自动，结果一个 Routine 里塞了七八个 Agent，调试时根本不知道哪一步出的问题。后来老老实实退回三 Agent，跑稳了再逐步加，反而更快。所以我的建议很直接：别追求一步到位，先把最小的闭环跑通，再谈扩展。一个能稳定跑通的三 Agent 流水线，价值远大于一个花哨但三天两头崩的复杂架构。

最后分享一个小技巧：每次调好一个 Routine，花五分钟写个简短的 README，记下它的适用场景、参数含义和已知限制。这个习惯看起来不起眼，但当你手上有十几个 Routine 的时候，它就是你的救命稻草。