企业官网建设流程全解析

1. 从“人肉流水线”到“AI Native”：为什么我们要重写研发手册

过去大半年，我一直在带着两个不同规模的团队做同一件事：把 AI 从“偶尔用一下的辅助工具”变成“研发流程里的一等公民”。踩了无数坑之后，我越来越确信一个判断——AI Native 不是给现有流程加一个聊天窗口，而是把 Agent 当成团队里的正式成员来重新设计 SDLC。这个区别听起来像文字游戏，但实际落地时，它决定了你是效率翻倍还是制造一堆没人敢合并的代码。

先说清楚这套手册是给谁看的。如果你满足下面任意一条，这篇内容应该能帮你省下至少两三个月的试错时间：

• 团队已经在用 Claude Code、Codex 这类命令行 Agent，但只停留在“帮我写个函数”的层面；
• 想搭建一套可复用的 Agent 工作流，却不知道从哪下手，网上的教程要么太浅要么太散；
• 正在纠结 Agent 的边界在哪、安全怎么控、记忆怎么管、多个 Agent 怎么协作；
• 单纯想搞清楚 AI Native SDLC 到底和传统 SDLC 差在哪，值不值得投入。

我会按“设计思路 → 核心机制 → 落地实操 → 问题排查”的顺序展开，中间会穿插大量我实际跑过的配置、参数和踩坑记录。所有涉及具体工具的地方，我都会说明为什么这么选，以及有没有替代方案。你不需要完全照抄，但希望你能从我的取舍逻辑里找到适合自己团队的那条路。

2. AI Native SDLC 的整体设计与思路拆解

2.1 传统 SDLC 和 AI Native SDLC 的本质差异

传统 SDLC 的核心假设是：人是执行主体，工具是辅助。需求评审、方案设计、编码、测试、部署，每个环节都由人主导，工具负责提效。而 AI Native SDLC 的核心假设变成了：Agent 是执行主体，人是审核者和编排者。这个转变带来的连锁反应比想象中大得多。

我拿一个具体场景对比。传统流程里，一个后端接口的开发是这样的：产品写需求文档 → 技术负责人拆任务 → 开发同学写代码 → 自测 → 提测 → 测试同学验证 → 上线。整个链路里，信息在人与人之间传递，每次传递都有损耗。AI Native 流程里，同样的需求会变成：需求以结构化格式喂给编排 Agent → 编排 Agent 拆解成子任务并分发给编码 Agent、测试 Agent、文档 Agent → 各 Agent 并行执行 → 人只审核关键节点的产出。

这里最关键的变化不是“快了”，而是信息传递的损耗被大幅压缩。因为 Agent 之间传递的是结构化的上下文，而不是自然语言的模糊描述。但代价也很明显：你需要把原本藏在人脑子里的隐性知识显性化，写成 Agent 能理解的规则和约束。这就是为什么 CLAUDE.md 这类文件在 AI Native 团队里如此重要——它是团队知识的“可执行版本”。

2.2 为什么选择 Agent 编排而不是单点工具

市面上有很多“AI 编程助手”，从 IDE 插件到网页版对话，用起来都很方便。但我在实际项目里发现，单点工具的天花板很低。原因有三个：

第一，上下文断裂。你在 IDE 里让 AI 写了一个函数，然后切到另一个窗口让它写测试，它根本不知道刚才那个函数的实现细节。你得手动复制粘贴，效率反而更低。

第二，无法形成闭环。真正的研发流程需要“写代码 → 跑测试 → 看结果 → 修 bug”这个循环。单点工具只能完成其中一步，剩下的还得人来衔接。

第三，知识无法沉淀。每次对话都是独立的，上次踩过的坑下次还会踩。而 Agent 编排体系里，你可以把经验写进配置文件，让所有 Agent 共享。

所以我最终选择的路线是：以命令行 Agent 为核心执行单元，以编排层为调度中枢，以配置文件为知识载体。命令行 Agent 的优势在于它能直接操作文件系统、执行终端命令、读取项目上下文，这是网页版工具做不到的。编排层负责把复杂任务拆解、分发、汇总。配置文件则承载了团队的编码规范、架构约束、常见陷阱。

2.3 核心组件选型与背后的考量

在具体工具选型上，我做过不少对比。编码 Agent 这块，Claude Code 是我目前用得最多的，主要原因是它对终端命令的执行能力比较成熟，而且支持通过 CLAUDE.md 注入项目级上下文。Codex 我也试过，它的优势在于和某些生态的集成更顺滑，但在自定义工作流方面灵活度稍弱。

编排层我没有用特别重的框架，而是基于 Agent Skills 的思路做了一套轻量编排。所谓 Agent Skills，本质上就是把一类任务的标准操作流程封装成可复用的“技能包”，Agent 在执行时按需调用。这样做的好处是：新增一类任务时，只需要写一个新的 Skill，而不需要改动整个编排逻辑。

记忆管理这块我单独拎出来说，因为它太容易被忽视了。Agent 的“记忆”分两种：短期记忆是当前会话的上下文，长期记忆是跨会话的知识沉淀。短期记忆靠上下文窗口管理，长期记忆我建议用文件系统来存——把重要的决策、踩过的坑、项目特有的约定写成 Markdown 文件，放在项目根目录，让 Agent 每次启动时读取。这比任何向量数据库都简单可靠。

提示：不要一上来就追求“全自动”。我见过太多团队想一步到位搞全自动流水线，结果 Agent 产出的代码没人敢合并，最后整个项目搁浅。正确的做法是从“半自动”开始，人审核每个关键节点，等信任建立起来再逐步放权。

3. 核心细节解析与实操要点

3.1 CLAUDE.md 到底该写什么：一份可复用的模板

CLAUDE.md 是 Claude Code 启动时会自动读取的项目级配置文件。它的作用相当于给 Agent 的一份“入职培训材料”。我见过很多人把它写成项目 README 的复制粘贴，这是浪费。CLAUDE.md 应该写的是Agent 执行任务时必须知道、但光看代码看不出来的信息。

我目前用的模板大概包含这几块：

# 项目上下文 - 项目类型：Node.js + TypeScript 后端服务 - 包管理器：pnpm（不要用 npm 或 yarn） - 测试框架：Vitest，测试文件放在 __tests__ 目录 # 编码规范 - 所有导出函数必须有 JSDoc 注释 - 错误处理统一用 Result 类型，不要抛异常 - 数据库操作必须走 repository 层，不要在 service 里直接写 SQL # 架构约束 - 新增 API 必须同时在 routes/ 和 docs/openapi.yaml 里注册 - 任何涉及金额的计算必须用 decimal.js，禁止用浮点数 # 常见陷阱 - 这个项目的时区统一用 UTC，不要用本地时间 - 环境变量读取必须走 config/index.ts，不要直接 process.env # 工作流约定 - 提交前必须跑 pnpm lint && pnpm test - 修改数据库 schema 后必须生成 migration 文件

这份文件的关键在于具体、可执行、有约束力。不要写“代码要整洁”这种废话，要写“函数不超过 50 行”这种可验证的规则。另外，这份文件不是写完就完了，每次 Agent 犯了新错误，你就应该把对应的规则补进去。它应该是一个活文档。

3.2 Agent Skills 的设计原则：从“会做”到“做对”

Agent Skills 是我认为 AI Native 团队最值得投入的基础设施。它的核心思想是：把重复性的任务流程封装成标准化的技能，让 Agent 按需调用。比如“新增一个 API 接口”这个任务，涉及创建路由文件、写 handler、加测试、更新文档、生成 migration，这一整套流程就可以封装成一个 Skill。

设计 Skill 时我遵循几个原则：

第一，单一职责。一个 Skill 只做一件事。不要搞一个“万能 Skill”试图覆盖所有场景，那样只会让 Agent 困惑。

第二，输入输出明确。Skill 的输入应该是结构化的参数，输出应该是可验证的结果。比如“新增 API”这个 Skill，输入是接口路径、方法、请求体 schema，输出是创建的文件列表和测试通过的报告。

第三，包含验证步骤。Skill 不能只是“执行”，还要包含“验证”。比如写完代码后自动跑 lint 和测试，失败了就回滚或报告。这是保证质量的关键。

第四，可组合。复杂的任务应该由多个简单 Skill 组合而成，而不是写一个巨大的 Skill。这样复用性更高，也更容易调试。

我实际用下来，一个中等规模的项目大概需要 15 到 25 个 Skill 就能覆盖 80% 的日常任务。维护成本不高，但收益非常明显。

3.3 上下文工程：让 Agent 看到该看的，忽略不该看的

Agent 的能力上限很大程度上取决于你喂给它的上下文。喂多了，它会迷失在噪音里；喂少了，它会做出错误假设。我总结了一套“三层上下文”的管理方法：

第一层是全局上下文，也就是 CLAUDE.md 这类项目级配置。这层内容是常驻的，每次会话都会加载。所以要精简，只放最核心的规则。

第二层是任务上下文，也就是当前任务相关的文件、代码片段、需求描述。这层内容按需加载，任务结束后就丢弃。加载时要注意相关性，不要把整个代码库都塞进去。

第三层是历史上下文，也就是之前会话的决策记录、踩坑记录。这层内容我建议用文件系统管理，按主题分文件存放，Agent 需要时主动读取。

实际操作中，我发现一个很有效的技巧：在任务开始时，先让 Agent 自己列出它需要哪些上下文。比如你可以说“我要新增一个用户导出功能，你先告诉我你需要看哪些文件”。这样它会主动去读相关代码，而不是等你手动喂。这个技巧能显著减少上下文遗漏导致的错误。

3.4 安全边界：Agent 能做什么，不能做什么

Agent 安全是我最重视的一块，因为一旦出事就是大事。我目前的做法是分级授权：

这套分级不是拍脑袋定的，而是根据“操作的可逆性”和“影响范围”两个维度来划分的。可逆且影响小的操作自动放行，不可逆或影响大的操作必须人工确认。

另外，我强烈建议给 Agent 一个独立的沙箱环境。不要让它在你的主开发机上直接操作，而是用一个容器或虚拟机。这样即使 Agent 犯了错，也不会影响你的主环境。这个投入是值得的，我见过太多因为 Agent 误删文件或改错配置导致的惨案。

注意：Agent 的权限配置一定要在项目启动时就定好，不要等到出事再补。而且权限配置本身也要纳入版本管理，任何修改都要经过 review。

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

4.1 环境搭建：从零到可用的完整步骤

我以 Ubuntu 环境为例，走一遍完整的搭建流程。macOS 的步骤基本一致，Windows 建议用 WSL2。

第一步，安装 Node.js 和包管理器。Claude Code 依赖 Node.js 18 以上版本。我推荐用 nvm 管理 Node 版本，避免污染系统环境。

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc # 安装 Node.js 20 nvm install 20 nvm use 20 # 安装 pnpm npm install -g pnpm

第二步，安装 Claude Code。官方提供了 npm 安装方式，这是最省事的。

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

安装完成后，运行claude --version验证。如果提示命令找不到，检查 npm 全局 bin 目录是否在 PATH 里。

第三步，配置模型接入。Claude Code 默认使用官方模型，但很多团队需要接入第三方模型。这时候可以用 cc switch 这类工具来切换。配置的核心是设置好 API endpoint 和 key。我建议把配置写在项目级的.claude/settings.json里，而不是全局配置，这样不同项目可以用不同的模型。

{ "model": "your-model-name", "apiBase": "https://your-api-endpoint", "apiKeyEnv": "CLAUDE_API_KEY" }

注意 apiKey 不要直接写在配置文件里，而是通过环境变量注入。这是基本的安全习惯。

第四步，配置 VS Code 集成。如果你用 VS Code，可以安装 Claude Code 的官方扩展，这样就能在编辑器里直接调用 Agent。配置的关键是让扩展能找到你的项目根目录和 CLAUDE.md 文件。我一般会在.vscode/settings.json里加上：

{ "claudeCode.projectRoot": "${workspaceFolder}", "claudeCode.contextFile": "CLAUDE.md" }

第五步，初始化项目上下文。在项目根目录创建 CLAUDE.md，按前面说的模板填写。然后创建.claude/skills/目录，用来存放自定义 Skill。

第六步，验证环境。跑一个简单的任务测试，比如让 Agent 读取项目结构并生成一份说明文档。如果它能正确读取文件、理解项目结构、生成合理输出，说明环境搭好了。

4.2 一个完整任务的 Agent 执行流程拆解

我拿“新增一个用户列表查询接口”这个任务来演示完整流程。这个任务看似简单，但涉及路由、handler、service、repository、测试、文档多个环节，很适合展示 Agent 编排的价值。

任务启动阶段。我在终端里输入任务描述：“新增 GET /api/users 接口，支持分页和按用户名模糊搜索，返回用户列表和总数”。编排 Agent 收到任务后，先做三件事：读取 CLAUDE.md 了解项目规范，扫描项目结构找到相关目录，列出它认为需要修改的文件清单。

任务拆解阶段。编排 Agent 把任务拆成子任务：创建路由定义、实现 handler、实现 service 层查询逻辑、实现 repository 层数据库查询、编写单元测试、更新 OpenAPI 文档。每个子任务分配给对应的 Skill。

并行执行阶段。这里有个关键决策：哪些子任务可以并行，哪些必须串行。路由定义和文档更新可以并行，因为它们不依赖其他产出。但 handler 依赖 service 的接口定义，service 依赖 repository 的接口定义，所以这三层必须串行。我实际配置的是：先并行跑路由和文档，然后串行跑 repository → service → handler，最后并行跑测试和 lint。

验证阶段。所有子任务完成后，编排 Agent 自动跑pnpm lint && pnpm test。如果失败，它会读取错误信息，尝试修复，最多重试三次。三次还失败就停下来报告给我。

人工审核阶段。我收到的是：修改的文件列表、测试通过报告、以及一份变更说明。我只需要 review 关键逻辑，确认没问题就合并。整个流程从启动到可审核，大概 8 到 12 分钟，比我手动写快 3 到 4 倍。

这个流程里最值得说的是失败重试机制。Agent 第一次跑测试失败是常态，关键是要让它能读懂错误信息并自我修复。我实测下来，简单错误（比如类型不匹配、导入路径错误）Agent 基本能自己修好，复杂错误（比如业务逻辑错误）还是需要人介入。所以重试次数设 3 次比较合理，再多就是浪费时间。

4.3 多 Agent 协作的编排配置

当任务复杂度上升，单 Agent 就不够用了。我目前用的多 Agent 编排配置大概是这样的：

orchestrator: name: "task-orchestrator" model: "claude-sonnet" skills: - task-decomposition - agent-dispatch - result-aggregation agents: - name: "coder" model: "claude-sonnet" skills: - create-route - create-handler - create-service - create-repository constraints: - "只能修改 src/ 目录下的文件" - "不能执行数据库迁移" - name: "tester" model: "claude-haiku" skills: - write-unit-test - run-test - analyze-coverage constraints: - "只能修改 __tests__/ 目录下的文件" - name: "documenter" model: "claude-haiku" skills: - update-openapi - update-readme constraints: - "只能修改 docs/ 目录下的文件"

这个配置的核心思路是按职责划分 Agent，每个 Agent 有明确的权限边界。coder 只能改源码，tester 只能改测试，documenter 只能改文档。这样即使某个 Agent 出错，影响范围也是可控的。

编排器负责协调这三个 Agent 的工作顺序和数据传递。比如 coder 完成后，把产出的接口定义传给 tester，tester 据此写测试。tester 完成后，把测试结果传给 documenter，documenter 据此更新文档。

这套配置我跑了大概两个月，最大的感受是：Agent 之间的接口定义比 Agent 本身的能力更重要。如果接口定义模糊，Agent 之间就会互相误解，产出对不上的东西。所以我现在会花很多时间在设计 Agent 之间的数据契约上。

4.4 记忆系统的落地实现

Agent 记忆这块，我用的是最朴素的方案：文件系统 + 约定。具体来说，项目根目录下有一个.claude/memory/目录，里面按主题分文件：

• decisions.md：记录重要的技术决策和原因
• pitfalls.md：记录踩过的坑和解决方案
• conventions.md：记录项目特有的约定
• glossary.md：记录业务术语和领域概念

每次 Agent 启动时，会先读取这几个文件。任务执行过程中，如果遇到新的决策或坑，Agent 会主动追加到对应文件里。我每周会 review 一次这些文件，把过时的内容清理掉，把重要的内容提炼到 CLAUDE.md 里。

这个方案的好处是简单、透明、可版本管理。你随时可以打开文件看 Agent 记住了什么，也可以手动修改。比向量数据库那种黑盒方案靠谱得多。缺点是当文件变大后，读取会变慢。我的经验是每个文件控制在 500 行以内，超过就拆分。

提示：记忆文件的内容要定期清理。我见过有的团队记忆文件积累了几千行，Agent 每次启动都要读半天，反而拖慢了速度。记住，记忆的目的是“让 Agent 少犯错”，不是“记录一切”。

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

5.1 Agent 执行终端命令失败的排查思路

这是最高频的问题。Agent 说它要执行某个命令，但实际执行失败。排查顺序我一般是这样的：

先看权限。Agent 有没有执行这个命令的权限？如果是需要确认的操作，是不是确认流程卡住了？检查.claude/settings.json里的权限配置。

再看环境。命令依赖的环境变量有没有设置？工作目录对不对？我遇到过好几次 Agent 在错误的目录下执行命令，导致找不到文件。解决办法是在 Skill 里明确指定工作目录。

然后看命令本身。命令语法对不对？依赖的工具装了吗？我建议在 Skill 里把常用命令封装成脚本，而不是让 Agent 直接拼命令。这样更可控。

最后看输出解析。有时候命令执行成功了，但 Agent 解析输出出错，误以为失败了。这种情况要检查 Agent 的输出解析逻辑，必要时调整提示词。

下面是我整理的一份速查表：

5.2 上下文丢失和幻觉的应对策略

Agent 幻觉是另一个高频问题。表现是：Agent 信誓旦旦地说某个文件存在，实际不存在；或者说某个函数有某个参数，实际没有。这类问题的根源通常是上下文不足或上下文过时。

我的应对策略是强制验证。在 Skill 里加入验证步骤，Agent 在做出任何假设之前，必须先读取实际文件确认。比如它要说“修改 userService.getUser 方法”，就必须先读取 userService 文件，确认这个方法存在。

另一个策略是缩小上下文范围。不要让 Agent 一次性看到整个代码库，而是按任务需要逐步加载。这样它能更专注，幻觉也更少。

还有一个技巧是让 Agent 自我质疑。在提示词里加入“如果你不确定某个信息，先读取文件确认，不要凭记忆回答”。这句话能显著降低幻觉率。

5.3 多 Agent 协作时的冲突处理

多 Agent 并行工作时，冲突是难免的。最常见的是两个 Agent 同时修改同一个文件。我的处理方式是文件级锁：在编排层维护一个文件锁表，Agent 要修改文件前先申请锁，拿到锁才能改，改完释放。这样能避免并发写入冲突。

另一种冲突是逻辑冲突。比如 coder 改了接口签名，但 tester 还在用旧签名写测试。这种冲突靠锁解决不了，需要在编排层做依赖管理。我的做法是：明确每个子任务的输入输出，只有上游任务完成并验证通过后，下游任务才能开始。这样虽然牺牲了一些并行度，但保证了正确性。

还有一种冲突是风格冲突。不同 Agent 可能用不同的代码风格。解决办法是在 CLAUDE.md 里把风格规范写死，所有 Agent 都必须遵守。如果规范没覆盖到，就在 Skill 里补充。

5.4 性能优化的几个实用技巧

Agent 跑得慢是很多团队的痛点。我总结的几个优化技巧：

第一，模型分级。不是所有任务都需要最强的模型。编排和复杂编码用强模型，简单的文档更新、测试生成用轻量模型。这样能省不少成本和时间。

第二，缓存常用上下文。CLAUDE.md 和记忆文件这些常驻上下文，可以用缓存机制避免每次重新读取。Claude Code 本身有缓存机制，但你需要确保文件没有频繁变动。

第三，并行化独立任务。前面说过，独立的任务要并行跑。我实测下来，合理的并行化能把整体耗时降低 40% 到 60%。

第四，减少不必要的验证。验证很重要，但过度验证会拖慢速度。我的做法是：关键路径上的产出必须验证，非关键路径的产出抽样验证。

第五，定期清理记忆文件。记忆文件太大是隐形的性能杀手。我每个月会清理一次，把过时内容删掉，把重要内容提炼到 CLAUDE.md。

5.5 我踩过的几个大坑

最后分享几个我实际踩过的大坑，希望能帮你避开。

坑一：一开始就追求全自动。我最早想搞全自动流水线，Agent 写完代码直接合并。结果第一周就出了三次事故，都是 Agent 理解错了需求。后来改成半自动，人审核关键节点，事故率立刻降下来了。教训是：信任要慢慢建立，不要一步到位。

坑二：CLAUDE.md 写得太泛。我最早写的 CLAUDE.md 都是“代码要整洁”“注释要清晰”这种废话，Agent 根本没法执行。后来改成具体规则，比如“函数不超过 50 行”“所有导出函数必须有 JSDoc”，效果立刻不一样。教训是：给 Agent 的规则必须可验证。

坑三：忽视 Agent 的权限边界。我有一次让 Agent 直接操作生产数据库，差点出事。后来加了严格的权限分级，所有涉及数据的操作都必须人工确认。教训是：Agent 的权限宁紧勿松。

坑四：记忆文件不清理。我的记忆文件一度积累到 3000 多行，Agent 每次启动要读十几秒，而且经常被过时信息误导。后来改成每月清理，性能立刻回升。教训是：记忆要定期维护，不是越多越好。

坑五：Agent 之间接口不清晰。多 Agent 协作时，我最早没定义清楚数据契约，结果 coder 产出的接口和 tester 理解的接口对不上，测试全挂。后来花时间设计了 Agent 间的数据格式，问题才解决。教训是：Agent 协作的瓶颈往往在接口设计，不在 Agent 能力。

6. 从半自动到全自动的演进路线

如果你问我 AI Native 团队应该怎么起步，我的建议是分三个阶段走。

第一阶段是辅助模式。Agent 只做建议，不直接改代码。人看完建议后手动改。这个阶段的目标是建立信任，让团队熟悉 Agent 的能力边界。大概持续两到四周。

第二阶段是半自动模式。Agent 直接改代码，但每个关键节点都要人确认。比如写完代码后，人 review 通过才跑测试；测试通过后，人确认才合并。这个阶段的目标是优化流程，找到最适合团队的审核粒度。大概持续一到两个月。

第三阶段是自动模式。Agent 自主完成整个任务，人只做最终审核。这个阶段的前提是前两个阶段积累的规则、Skill、记忆足够完善，Agent 的产出质量稳定。不是所有团队都需要走到这一步，取决于任务的风险等级。

我目前带的团队处在第二阶段向第三阶段过渡。大部分日常任务已经可以自动完成，只有涉及核心逻辑和数据的任务还需要人工介入。这个节奏我觉得比较健康，既享受了效率提升，又控制了风险。

最后分享一个我最近在用的技巧：让 Agent 自己写复盘。每个任务完成后，让 Agent 输出一份简短的复盘，包括它做了什么、遇到什么问题、怎么解决的、有什么经验可以沉淀。这份复盘会自动追加到记忆文件里。这样 Agent 的经验积累是自动化的，不需要我手动整理。实测下来，这个技巧对提升 Agent 的长期表现很有帮助。