企业官网建设流程全解析

1. 从“用AI提效”到“AI原生”：一次研发范式的底层切换

这两年我参与过不少团队从零搭建 AI 辅助研发流程，也踩过很多坑。最开始大家的做法都很朴素：给工程师配个 AI 编程助手，写代码时补全一下、生成个单测、解释段报错，本质上还是“人写代码，AI 打下手”。这套模式在早期确实能提效，但很快会撞到天花板——因为流程没变、协作方式没变、知识沉淀方式没变，AI 只是个更聪明的输入法而已。

AI Native 团队要解决的就是这个天花板问题。它不是“团队里用了 AI 工具”，而是把 AI 当作研发流程里的一等公民：需求拆解、方案设计、编码、评审、测试、文档、复盘，每个环节都重新设计“人和 Agent 怎么分工”。配套的这套东西，行业里常叫AI-Native SDLC（软件开发生命周期），核心角色是Agent，核心约束文件是CLAUDE.md这类项目级上下文契约，核心工作模式是Plan Mode先规划后执行。

这篇手册适合三类人看：一是正在推动团队 AI 化转型的技术负责人，二是想搞清楚 Agent 到底怎么落到真实项目里的工程师，三是已经在用 AI 写代码但觉得“提效不明显、质量不稳定”的实践者。我会把整套落地路径拆开讲——从目录结构、上下文文件、Plan Mode 工作流，到 Agent 编排、并发、安全、记忆，再到常见故障排查。所有内容都基于真实项目里跑通过的方案，能直接抄作业。

先说一个我反复验证过的判断：AI Native 落地失败，九成不是模型不行，而是上下文没管好、流程没重设计、边界没划清楚。模型能力是外部变量，你能控制的是工程侧的一切。下面所有章节都围绕“你能控制的部分”展开。

2. 整体设计与思路拆解：为什么是这套组合拳

2.1 核心思路：把“隐性知识”变成“显性契约”

传统研发里，大量关键信息藏在人脑和口头沟通里：这个模块为什么这么设计、那个接口有什么坑、改这里要注意什么。人多了靠口口相传，人走了知识就断了。AI Native 的第一步，就是把这些隐性知识显性化、文件化、版本化，让 Agent 每次执行任务时都能读到同一份“事实来源”。

这就是CLAUDE.md这类文件存在的意义。它不是普通的 README，而是给 Agent 看的“项目宪法”：技术栈、目录约定、编码规范、禁止事项、常用命令、架构决策记录。Agent 每次进入项目，第一件事就是读它。读得越准，输出越稳。

我见过太多团队抱怨“AI 生成的代码不符合我们规范”，一问才知道，他们从来没把规范写下来过。人靠默契，AI 靠明文。这是范式切换的第一个认知门槛。

2.2 方案选型：为什么用 Plan Mode 而不是直接生成

直接让 Agent 生成代码，最大的问题是不可控。它可能理解错需求、选错方案、改错文件，等你发现时已经写了一堆要回滚的东西。Plan Mode的思路是：先让 Agent 输出一份执行计划——要改哪些文件、每个文件改什么、依赖什么、风险在哪——人确认后再执行。

这个设计背后的逻辑很朴素：规划的成本远低于返工的成本。让 Agent 花 30 秒列计划，比让它花 5 分钟写错代码再让你花 20 分钟修，划算得多。而且计划本身是可评审的，团队可以在计划阶段就拦住方向性错误。

我实测下来，引入 Plan Mode 后，Agent 产出的一次性通过率从大概四成提升到七成以上。剩下的三成里，大部分问题在计划评审阶段就被发现了，根本没走到编码。

2.3 架构分层：Agent、Harness、编排层各管什么

很多人分不清Agent和Harness。简单说，Agent 是“会思考、会决策、会调用工具的执行体”，Harness 是“给 Agent 提供运行环境、工具接口、生命周期管理的外壳”。打个比方，Agent 是司机，Harness 是车——司机负责判断怎么开，车负责提供油门、刹车、仪表盘。

再往上一层是编排层，负责调度多个 Agent 协作：谁先干、谁后干、结果怎么传递、冲突怎么解决。一个完整的 AI Native 研发体系通常长这样：

这个分层的好处是职责清晰、可替换。模型换了不影响编排逻辑，编排框架换了不影响上下文文件。工程上最怕的就是全耦合，一动全动。

2.4 为什么强调“AI Native”而不是“AI Assisted”

这两个词差一个字，差的是整个设计哲学。AI Assisted 是“人主导，AI 辅助”，流程不变，只是每个环节快一点。AI Native 是“流程围绕 AI 重新设计”，有些环节人主导，有些环节 Agent 主导，交接点重新定义。

举个具体例子。传统代码评审是“人写、人评”。AI Assisted 是“人写、AI 先扫一遍、人再评”。AI Native 是“Agent 写、Agent 自评、Agent 互评、人只评审关键决策点”。评审的粒度和关注点完全变了——人不再逐行看代码，而是看 Agent 的决策依据和风险标注。

这个切换对团队的要求更高：你得信任 Agent 到一定程度，同时又得设计好“什么必须人拍板”的红线。红线划不清，要么人累死，要么出事故。

3. 核心细节解析与实操要点：上下文、Plan Mode 与 Agent 编排

3.1 CLAUDE.md 怎么写才真正管用

CLAUDE.md 是项目级上下文契约，写得好不好直接决定 Agent 的输出质量。我总结了一个“四段式”结构，实测最稳：

第一段：项目定位与技术栈。一句话说清项目是干什么的，然后列核心技术栈和版本。比如“这是一个基于 Kotlin 的后端服务，用 Spring Boot 3.x，数据库 PostgreSQL 15，构建工具 Gradle”。Agent 拿到这个，就不会给你生成 Python 代码。

第二段：目录结构与职责。把关键目录列出来，说明每个目录放什么。Agent 改文件时就知道该往哪放，不会把测试代码塞进业务目录。

第三段：编码规范与禁止事项。这部分最容易被忽略，但最重要。包括命名约定、错误处理方式、日志规范、禁止使用的库、禁止的操作（比如禁止直接改生产配置）。写得越具体越好。

第四段：常用命令与工作流。构建、测试、格式化、部署的命令都列上。Agent 需要验证自己的改动时，直接调用这些命令。

注意：CLAUDE.md 不是一次写完就完事的。每次发现 Agent 犯了重复性错误，就回来补一条规则。它是活的文档，跟着项目一起演进。

我踩过的一个坑是：早期把 CLAUDE.md 写得太长太全，结果 Agent 每次读都要消耗大量上下文，反而影响推理质量。后来改成“核心规则精简 + 详细文档外链”，Agent 按需读取，效果好很多。上下文不是越多越好，是越准越好。

3.2 Plan Mode 的完整工作流

Plan Mode 不是简单地“让 AI 先说说怎么做”，而是一套有明确阶段的工作流。我把它拆成五步：

1. 任务输入：人用自然语言描述需求，越具体越好。模糊需求会让 Agent 在计划阶段就开始猜。
2. 上下文加载：Agent 读取 CLAUDE.md、相关代码文件、历史决策记录。
3. 计划生成：Agent 输出结构化计划，包含改动文件清单、每处改动说明、依赖关系、风险点、验证方式。
4. 计划评审：人（或另一个 Agent）评审计划，确认、修改或打回。
5. 执行与验证：计划确认后执行，执行完跑验证命令，输出结果。

这里有个关键细节：计划要结构化，不能是散文。我要求 Agent 用固定格式输出，比如每个改动项包含“文件路径、改动类型、改动原因、影响范围”。结构化之后，评审效率高很多，也方便后续自动化处理。

3.3 Agent 编排：单 Agent 还是多 Agent

这是被问得最多的问题之一。我的答案是：从单 Agent 开始，遇到明确瓶颈再拆多 Agent。

单 Agent 的优势是简单、上下文连贯、调试容易。多 Agent 的优势是并行、职责隔离、可专业化。但多 Agent 的代价是通信开销、状态同步、冲突处理，复杂度指数级上升。

什么时候该拆多 Agent？我总结三个信号：一是任务能明显分成独立子任务且互不依赖；二是单个 Agent 的上下文已经装不下所有信息；三是需要不同专业能力（比如一个写代码、一个做安全审查）。

拆的时候，编排层要定义清楚三件事：任务怎么分、结果怎么合、冲突怎么解。我见过最失败的多 Agent 案例，就是三个 Agent 各干各的，最后产出的东西互相矛盾，人还得花更多时间收拾。

3.4 Agent 记忆：短期、长期与项目记忆

Agent 记忆分三层，别混在一起：

• 短期记忆：当前任务的上下文，任务结束就丢。存在对话历史里。
• 长期记忆：跨任务的经验沉淀，比如“上次改这个模块踩了什么坑”。存在向量库或结构化存储里。
• 项目记忆：项目级的稳定知识，其实就是 CLAUDE.md 和架构决策记录。

很多团队一上来就想搞复杂的长期记忆，结果发现维护成本高、收益不明显。我的建议是：先把项目记忆做扎实，短期记忆靠框架自带，长期记忆等真有跨任务复用需求了再上。顺序反了，就是给自己找麻烦。

3.5 Agent Skill：把能力封装成可复用单元

Agent Skill是把某类具体能力封装成标准单元，让 Agent 按需调用。比如“把网页保存成 Markdown”可以是一个 Skill，“生成数据库迁移脚本”可以是另一个 Skill。

Skill 的价值在于复用和隔离。写一次，多个 Agent、多个项目都能用。而且 Skill 的边界清晰，测试和调试都容易。

写 Skill 有几个要点：输入输出要明确、错误处理要完整、依赖要声明清楚、要有使用示例。我见过太多 Skill 写得像黑盒，Agent 调用时不知道传什么、拿到什么，结果就是反复试错。

4. 实操过程与核心环节实现：从零搭一套可跑的流程

4.1 环境准备与项目初始化

假设你要在一个已有项目里落地 AI Native 流程，第一步不是装工具，是梳理现状。把项目结构、技术栈、构建命令、测试命令、部署流程都摸清楚，这些是后面写 CLAUDE.md 的原料。

然后创建上下文文件。我的习惯是在项目根目录放一个CLAUDE.md，内容按前面说的四段式组织。同时在.agent/目录下放更详细的文档：架构决策记录、接口约定、常见问题。

接着配置 Agent 运行环境。这里的关键是沙箱隔离——Agent 执行命令、改文件必须在受控环境里，不能直接动生产。我通常用容器做隔离，Agent 在容器里跑，容器挂载项目代码的副本，验证通过后再合并。

4.2 第一个任务：用 Plan Mode 跑通闭环

别一上来就搞复杂任务。选一个中等复杂度的需求，比如“给某个接口加参数校验”，走一遍完整流程。

任务描述要写清楚：改哪个接口、加什么校验、校验失败返回什么、要不要加测试。写得越具体，Agent 计划越准。

计划评审时重点看三件事：改动范围对不对、有没有漏掉关联文件、验证方式是否充分。我一般会问 Agent“这个改动会影响哪些调用方”，让它主动分析影响面。

执行阶段让 Agent 按计划改，改完自动跑测试。测试不过就让它自己排查，排查不出来再人工介入。这个“自愈”能力是 AI Native 流程的关键——Agent 能自己发现问题、自己修，人的介入点就少了。

结果验证不能只看测试过没过，还要看代码质量。我会让 Agent 输出一份改动摘要，说明每处改动的原因和影响，人快速扫一遍。

4.3 参数与配置：并发、超时、重试怎么定

Agent 扛并发是个实际问题。我的经验值是这样的：

这些值不是拍脑袋来的。单 Agent 并发超过 2，上下文会互相污染，输出质量明显下降。多 Agent 并行超过 5，编排层的状态同步就成了瓶颈。超时设太长，一个卡住的任务会拖垮整条流水线。

4.4 安全边界：Agent 能做什么、不能做什么

Agent 安全是落地时最容易被低估的部分。我划的红线是这样的：

• Agent 可以读代码、写代码、跑测试、生成文档。
• Agent 不可以直接操作生产环境、不可以改密钥和凭证、不可以执行删除类高危命令。
• 涉及数据库 schema 变更、权限变更、对外接口变更的，必须人工确认。

实现上，靠 Harness 层的权限控制。Agent 的工具调用要经过网关，网关按规则放行或拦截。高危操作直接拒绝，中危操作要求二次确认。

注意：安全边界要写在 CLAUDE.md 里，让 Agent 自己也知道红线在哪。光靠外部拦截不够，Agent 内部有约束，行为会更稳。

4.5 一个完整的实操记录

我拿一个真实场景走一遍。需求是“给用户查询接口加分页，默认每页 20 条，最大 100 条”。

第一步，任务输入：我把需求写清楚，附上接口路径和现有代码位置。

第二步，Agent 生成计划：它列出要改的文件——controller 加参数、service 加分页逻辑、mapper 改查询、加测试。风险点标注了“分页参数校验”和“默认值处理”。

第三步，评审：我发现它漏了“最大 100 条”的边界校验，让它补上。它还主动提出“要不要加索引优化”，我说先不加，这次只做分页。

第四步，执行：Agent 改完代码，跑测试，两个用例失败。它自己排查发现是默认值逻辑写反了，修完再跑，通过。

第五步，验证：我看了改动摘要，确认边界校验到位，测试覆盖了默认值和最大值场景。合并。

整个过程大概 15 分钟，其中人工介入两次，加起来不到 3 分钟。同样的任务，传统方式大概要 40 分钟。这个效率差，就是 AI Native 流程的价值。

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

5.1 Agent 输出不符合规范怎么办

这是最高频的问题。排查顺序是：先看 CLAUDE.md 里有没有写这条规范，再看 Agent 有没有读到，最后看规范写得够不够具体。

我遇到过一个典型案例：Agent 总是用错日志格式。查下来发现 CLAUDE.md 里只写了“用统一日志格式”，但没说什么格式。补上具体示例后，问题消失。规范要具体到能照抄，不能停留在原则层面。

5.2 计划总是太粗或太细

计划太粗，评审没意义；太细，评审成本高。我的调法是：在 CLAUDE.md 里定义计划的粒度标准——每个改动项对应一个文件或一个逻辑单元，改动说明控制在 2-3 句话。Agent 按这个标准输出，基本就合适了。

如果还是不对，就在任务描述里加一句“计划粒度参考 XX 任务的输出”。给个范例，比讲一堆道理管用。

5.3 多 Agent 协作时结果冲突

冲突的根源通常是职责边界不清。两个 Agent 都觉得自己该改某个文件，就会打架。解决办法是在编排层明确“文件所有权”——每个文件同一时间只能被一个 Agent 改。

如果冲突已经发生，让编排层做仲裁：按优先级选一个结果，另一个丢弃并记录原因。别让两个结果都进代码库，那是灾难。

5.4 Agent 执行中断或报错

agent execution terminated due to error这类报错，排查思路是：先看是模型侧还是工具侧。模型侧通常是上下文超限或推理超时，工具侧通常是命令失败或权限不足。

我整理了一个速查表：

5.5 几个独家避坑技巧

技巧一：给 Agent 一个“退出条件”。明确告诉它什么情况下该停下来问人，而不是硬着头皮往下做。比如“如果发现需要改超过 5 个文件，先停下来汇报”。

技巧二：定期回看 Agent 的失败记录。失败记录是最好的改进素材。每周花半小时看一遍，把重复出现的问题转化成 CLAUDE.md 里的规则。

技巧三：别追求全自动。有些环节人工介入反而更快。我的原则是“高频、低风险、可验证”的任务交给 Agent，“低频、高风险、难验证”的留给人。全自动是目标，不是起点。

技巧四：上下文文件要版本化。CLAUDE.md 的每次修改都提交到版本库，这样能追溯“哪条规则是什么时候加的、为什么加”。团队协作时，这个历史很有价值。

6. 团队协作与能力建设：让流程真正跑起来

6.1 角色重新划分

AI Native 团队里，角色会重新洗牌。传统的前端、后端、测试分工还在，但多了一层“Agent 协作”的维度。我观察到几个新角色在冒出来：

上下文维护者：负责 CLAUDE.md 和项目文档的质量，确保 Agent 读到的信息准确、及时。这个角色通常由资深工程师兼任，因为要判断什么信息值得沉淀。

Agent 编排设计者：负责设计多 Agent 协作流程，定义任务分解和结果聚合规则。偏架构性质，需要同时懂业务和 Agent 能力边界。

质量守门人：负责定义“什么必须人工确认”，以及评审 Agent 产出的关键决策点。这个角色是安全阀，不能省。

小团队不用设专职，但职责要有人认领。我见过最混乱的情况就是“大家都觉得 AI 的事有人管”，结果没人管，流程跑两周就散了。

6.2 学习路线：从入门到能独立搭建

如果你是从零开始，我建议这个顺序：

1. 先会用：拿现成的 Agent 工具，在个人项目里跑通“Plan Mode + 执行 + 验证”闭环。这一步的目标是建立手感。
2. 再会配：学会写 CLAUDE.md，学会定义 Skill，学会配置权限边界。这一步的目标是让 Agent 在你的项目里稳定工作。
3. 后会编排：学多 Agent 协作，学任务分解和结果聚合。这一步的目标是处理复杂任务。
4. 最后会调优：学并发控制、记忆管理、故障排查。这一步的目标是让流程规模化。

每一步都别跳。我见过直接上多 Agent 结果一团糟的，回头补基础反而更慢。

6.3 度量与迭代

流程跑起来后，要度量效果。我关注四个指标：

• 一次性通过率：Agent 产出不用返工的比例。这个指标反映上下文和计划质量。
• 人工介入次数：每个任务平均需要人介入几次。这个指标反映自动化程度。
• 任务周期：从任务输入到合并的时长。这个指标反映整体效率。
• 返工率：合并后发现问题需要回改的比例。这个指标反映质量。

这四个指标每周看一次，哪个掉了就查哪个环节。别只看效率不看质量，也别只看质量不看效率，平衡最重要。

6.4 一个真实的团队落地时间线

我参与过的一个团队，从决定落地到流程稳定，大概花了两个月：

• 第 1-2 周：梳理现状，写 CLAUDE.md，搭沙箱环境。这周基本没产出，但地基必须打。
• 第 3-4 周：单 Agent 跑通闭环，选低风险任务试水。这周开始有产出，但效率还不明显。
• 第 5-6 周：优化上下文和计划粒度，一次性通过率从四成提到六成。效率开始显现。
• 第 7-8 周：引入多 Agent 处理复杂任务，建立度量体系。流程基本稳定。

两个月不算快，但每一步都扎实。急着上规模、跳过基础建设的，后面都要还债。

7. 扩展方向：这套流程还能怎么用

7.1 从研发扩展到运维和文档

AI Native 流程不只适用于写代码。运维侧的告警分析、故障定位、变更评审，文档侧的 API 文档生成、变更日志维护，都可以套同一套模式：上下文文件 + Plan Mode + Agent 执行 + 人工确认。

我试过用这套流程做变更评审，Agent 读变更内容、读相关代码、读历史事故记录，输出风险评估。准确率比纯人工初筛高，而且快很多。

7.2 跨项目复用

CLAUDE.md 和 Skill 都是可复用的资产。把通用部分抽出来做成模板，新项目初始化时直接套用，能省大量时间。我维护了一套内部模板库，新项目接入 AI Native 流程从两天缩短到半天。

复用的关键是分层：通用规则放模板层，项目特定规则放项目层。别把项目特定的东西塞进模板，那样模板会越来越臃肿，最后没人用。

7.3 与现有工具链集成

AI Native 流程不是另起炉灶，要跟现有工具链打通。代码托管、CI/CD、项目管理、监控告警，这些系统都要能跟 Agent 流程对接。对接点通常是 API 和 Webhook。

集成时注意幂等性。Agent 可能重复触发同一个操作，接口要能处理重复请求。我踩过这个坑，Agent 重试导致重复创建了工单，后来加了幂等键才解决。

7.4 后续可以深挖的方向

如果你已经把基础流程跑顺了，可以往这几个方向深挖：一是 Agent 的长期记忆和跨任务学习，让 Agent 越用越懂你的项目；二是更精细的权限模型，支持按任务类型动态授权；三是 Agent 产出的自动化质量评估，减少人工评审负担。

这些方向都有价值，但前提是基础流程已经稳定。基础不牢，深挖就是空中楼阁。

我个人在实际操作中的体会是，AI Native 落地最难的不是技术，是认知和习惯的切换。团队要接受“Agent 是同事不是工具”，要愿意花时间写上下文文件，要忍住“什么都自己来”的冲动。技术问题都有解，认知问题只能靠时间和实践慢慢磨。我见过技术选型最先进的团队落地失败，也见过工具很朴素的团队跑得风生水起，差别就在这儿。