企业官网建设流程全解析

AI 编程这件事，真正让人上火的从来不是“写不出来”，而是“昨天明明说好的事，今天全忘了”。我遇到过太多类似的场景：有个跨平台桌面项目，第一天让 AI 帮我设计了模块划分和命名规范，当时聊得清清楚楚，第二天继续让 AI 补功能，它却开始用另一种风格写代码，甚至把已经定好的架构决策推翻重来。更崩溃的是，我还得重新花十分钟把背景、技术栈、约定一条条再喂一遍——这个过程重复了三五次之后，我终于意识到问题不在 AI 的“智力”，而在它的“记忆”。

这个痛点催生了一个我目前认为最值得投入的方向：给 AI 编程建立一套真正可控的 Memory 工程——从依赖无状态的对话窗口，转向在代码仓库里用 AGENTS.md 这种声明式文件，把关键上下文沉淀成持久化的项目知识。这篇文章就把我在这套范式转换中的完整思考、设计方法和踩坑经验一次性讲清楚。

1. AI 编程的核心困境：无状态模型如何拖垮生产力

1.1 无状态意味着什么

大模型本质上是一个“每次对话都重新开始”的系统。你在对话框里输入的每一句话、AI 回答的每一个字，都会在会话结束后被丢进“回收站”。即使工具把历史消息保留在界面上，模型下一次调用时真正能吃进去的也只是窗口内那点上下文，窗口之外的对话记录对它的“记忆”一点贡献都没有。

可以这样类比：AI 编码助手像一个每隔几小时就会失忆的程序员，你每次见到它都要从“我叫什么、项目用什么语言、数据库在哪台机器”开始介绍。有人说那我把要求都写在对话里不就行了？问题是对话越长，早期内容被“挤”出窗口的概率就越大，而且每次新对话还得重新复制粘贴。这个机制决定了：只要上下文不被外置成可持续引用的文件，AI 编程的效率就永远被锁死在一个低水平循环里。

1.2 无状态带来的四个具体代价

先把代价拆开来看，这样后面理解 AGENTS.md 的价值会更直观。

第一是信息重复成本。每开一轮对话，都要重复项目是干嘛的、目录结构是什么、错误处理规范是什么。中等复杂度的项目，一次完整“背景交代”可能要 500 到 1500 个 token，一天开二十轮就是几万 token 的浪费。

第二是决策漂移。这是最隐蔽也最致命的。AI 在上一轮对话里明明采用了方案 A，新会话里它可能给出方案 B，而且 B 和 A 的接口完全不兼容。代码里就开始同时出现两套风格、两套命名、两套架构模式。

第三是规则无法沉淀。项目里那些约定俗成的东西——比如“所有工具函数必须放在lib/下”“状态管理只用受控模式”“不得直接操纵 DOM”——人类成员能靠口口相传，AI 没法靠“猜”来遵守。你说一次它就执行一次，不说就不执行。

第四是验证成本上升。因为你没法确定 AI 是否还记得上一轮的关键约定，每次它生成完代码你都得额外花时间做一致性检查。代码本身的正确性反而变成了次要矛盾，主要矛盾是“它记没记住”。

1.3 从“让 AI 记住”到“让项目自带记忆”

理解了这四类代价之后，思路就清楚了：我们不应该花更多精力去“训练”AI 记住项目，而应该把项目本身变成一个自带记忆体的系统。只要 AI 每次进入项目时都能从文件中读取同一份、且可验证的上下文，无状态这个根本约束就等于被绕开了。

这正是 Memory 工程的核心主张：把记忆从“运行时状态”降级为“持久化文件”。这也是标题里“范式转换”的含义——从依赖交互过程中的临时记忆，切换到声明式的、可持续维护的项目知识。AGENTS.md 就是这个范式转换的一个非常具体、可落地的载体。

2. Memory 工程的底层逻辑：为什么是声明式配置

2.1 从命令式对话到声明式文件

过去我们和 AI 协作时用的是“命令式”的方式：每一步都要显式地告诉它“你记住，本项目技术栈是……”“你注意，错误码格式是……”。这样做的效率低，本质上是把重要的项目知识塞进了易失的对话流里。

声明式配置的思路正好相反。它不是去“命令”AI 记住，而是把关键信息静态地写进文件，让 AI 每次进入上下文时都能看到。这个思路对应软件工程里一个很经典的原则：约定优于配置。把那些容易变化的、容易漂移的规则显式化，而不是依赖参与者的自觉性和记忆力。

在这个原则下，AGENTS.md 扮演的就是“给 AI 看的入职手册”的角色。它不是记录历史的文档，而是一份指向未来行动的、可执行的决策基准。AI 读到它，不需要从零推断项目的意图，只需要把它当作判断依据就行。

2.2 AGENTS.md 和 README.md 的分工

一个很自然的问题是：已经有 README.md 了，为什么还需要 AGENTS.md？

我自己的理解是这样的。README.md 面向的是人类读者，它回答的问题是“这个项目是做什么的，怎么跑起来”；而 AGENTS.md 面向的是 AI 编码代理，它回答的问题是“在这个项目里，做改动时应该遵循什么规则”。一个偏理解，一个偏行动，虽然内容有重叠，但职责边界很清楚。

如果硬让 AI 去读 README，大概率会失败。因为 README 里充满项目背景、行业术语、设计目标的解释性文字，这些不是 AI 执行任务所必需的，反而会稀释有效指令。AI 需要的是一份精炼的、带约束的、可判断的行动指南。

2.3 Memory 工程的可持续性

任何记忆系统，难点都在于“更新”。

对话式记忆的问题在于它只存在于单个会话中，更新了也没法持久化。文档式记忆的问题在于很容易写着写着就过期了、没人维护了。AGENTS.md 这种文件的好处在于，它被纳入版本控制之后，就有了真正的“生命周期”：它和代码一起变更、一起 review，过期的内容会被主动删除，新增的技术决策会被立即纳入。这就形成了一个正向循环——项目越复杂，AI 能看到的约束越清晰，生成的代码就越稳定。

3. AGENTS.md 的完整设计：结构、内容与写法

3.1 放置位置与层级划分

AGENTS.md 最常规的做法是放在仓库根目录，命名保持全大写。值得注意的是，不同工具对文件名的支持程度不一样，有的只认AGENTS.md，有的还支持.agents/AGENTS.md这种目录级配置，但无论如何，仓库根目录的AGENTS.md是兼容性最好的起点。

我还建议按“两级配置”来设计记忆体系：

• 全局级：放在~/.agents/之类的用户目录下，内容是你个人或团队在所有项目中都必须遵守的编码规范，比如“默认使用 TypeScript”“注释不得包含个人信息”。
• 项目级：放在某个具体仓库的根目录，内容是只适用于该项目的信息，比如微服务的端口约定、数据库迁移规则、模块边界。
• 目录级：放在复杂仓库的特定子目录，比如web/AGENTS.md可以单独描述前端部分的构建命令和状态管理约定。

这种分层方式和后端配置里的“全局配置 + 局部覆盖”是一个套路，越底层的文件越具体、越靠近代码。

3.2 核心区块设计

一份能用的 AGENTS.md，不需要写成长篇大论，但必须包含下面几个关键区块。

项目角色与核心约束。用一两句话说明项目是什么，以及最高优先级的约束是什么。比如：“这是一个面向大型门店的库存管理系统，任何改动不得破坏幂等性约束。”这一节的作用是给 AI 一个决策的北极星。

技术栈清单与版本限定。列出允许使用和禁止使用的技术。明确写“使用 React 18 + TypeScript 5”“禁止引入 Redux，统一使用 Zustand”。AI 在选择依赖时就会优先匹配这一清单。

架构不变式。这是整个文件的重点。它是那些一旦违反就会导致严重问题的规则，比如“所有对外 API 必须走网关层”“所有金额计算必须使用 Decimal 类型”。AI 每次生成代码时，这些规则就是它的“死线”，不得跨越。

编码规范与风格偏好。包括命名方式、文件组织、注释要求、错误处理偏好。注意这里不要堆砌一股脑的通用规范，只写那些和项目历史经验紧密相关的特殊规矩。

常用命令与构建流程。直接列出“如何安装依赖”“如何跑测试”“如何做 lint”。AI 在执行任务时经常需要判断是否运行现有测试，这份清单能大幅减少无效猜测。

AI 特别注意事项。这一节用来记录“上一代 AI 在这里犯过的错”。比如：“实现对 API 的调用时，必须统一使用api/目录下的封装，禁止在组件中直接 fetch。”这相当于把过去踩过的坑直接喂给了下一任 AI。

3.3 写法的关键技巧

AGENTS.md 的写法有一个核心原则：指令必须是可以直接执行的判断规则，而不是描述性的背景介绍。

糟糕的写法是：“本项目是一个面向企业的人力资源系统，系统架构采用微服务模式，具有重要意义……”这堆话 AI 读完什么也做不了。有效的写法是：“处理员工相关功能时，必须优先调用hr-service的接口，禁止直接在web层访问数据库。”

另外一定要多用祈使句。AGENTS.md 不是让你“理解”，是让你“执行”。动词尽量明确：必须、禁止、优先、推荐、不要、只有……才。少用模糊词，比如“可以”“可能”“酌情”。

我还习惯在文件开头放一段“快速共识”，就像开会前先对齐一句话目标。AI 无论后续执行什么任务，都先接受这份共识的约束。

4. 实操过程：从零搭建一份可用的 AGENTS.md

4.1 第一步：复盘你最近三次 AI 对话

不要一上来就凭空写。我建议先打开你最近和 AI 协作的三次会话，逐个找出重复出现的基本问题。比如“AI 反复问你项目用的什么语言”“它一直在用错误的测试框架”。把这些高频问题列成一张表，这张表就是你 AGENTS.md 的第一版目录。

我自己的复盘结果里，最常出现的三类问题是：技术栈不明确、目录结构没说明、代码风格不一致。对应到 AGENTS.md 里，就是技术栈清单、目录职责表和风格约束三个小节。这一步做完，整份文件已经有 70% 的准确度了。

4.2 第二步：从 README 和代码注释中提炼规则

接下来打开 README 和代码里比较集中的注释块，把那些反复强调的内容摘出来。README 里介绍项目架构的部分，可以压缩成两条架构不变式。代码注释里写着“注意这里不要直接用字符串拼接 SQL，必须走 ORM”，就直接变成一条 AI 特别注意事项。

注意不要照搬原文，要提炼成指令。这段技巧非常重要：很多人在这一步就直接把 README 复制粘贴进来了，结果文件冗长又低效。一定要把它压缩成 AI 能够快速消耗的、条理清晰的规则语句。

4.3 第三步：按区块套模板

完成前两步之后，你可以按照第 3 节提到的核心区块往模板里填内容。下面是我常用的一种基础模板结构，你可以直接拿来用：

# AGENTS.md ## 快速共识 这是一个[项目一句话简介]。最高优先级约束是[一句话说明]。 ## 技术栈 - 使用: TypeScript 5.x, React 18, Node.js 20 - 禁止: Redux, 任何 UI 组件库的全局样式覆盖 ## 架构不变式 1. 所有跨服务调用必须通过 `gateway/` 层 2. 所有金额计算必须使用 Decimal 类型 3. 所有数据库变更必须新增迁移文件，不得直接修改表结构 ## 编码规范 - 组件文件使用 PascalCase，工具函数使用 camelCase - 错误处理必须优先使用 `Result<T>` 模式，禁止裸抛异常 - 注释只写“为什么”，不写“是什么” ## 常用命令 - 安装依赖: `pnpm install` - 运行测试: `pnpm test` - 类型检查: `pnpm typecheck` ## AI 特别注意事项 - 不要直接在业务组件中调用 `fetch` - 不要生成 `any` 类型 - 修改公共 API 前必须先在相应目录下查看类型定义 ## 维护记录 - [日期]: [本次修改了什么，新增哪条规则]

这个模板的好处是结构固定、穷尽性比较好，AI 每次读到它的成本也低。

4.4 第四步：用“重开会话测试”验证配置效果

写完 AGENTS.md 之后，最有效的验证方法是“重开会话测试”。操作很简单：新建一个全新会话，不提供任何背景，只发一句话——“请阅读仓库中的 AGENTS.md，并回答以下问题：……”，然后提几个只有看了 AGENTS.md 才能答对的问题。

比如问“这个项目禁止使用哪种状态管理库”“金额计算用什么类型”“数据库变更如何执行”。如果 AI 的回答全部正确，说明这个文件的信息可被有效读取；如果答错了，不是文件不够好，就是工具没有把文件注入上下文，需要进一步排查。

4.5 第五步：把 AGENTS.md 纳入版本管理

很多人写完 AGENTS.md 就忘在仓库里不管了。我强烈建议把它和代码一样纳入 PR review 流程。任何人在任何时候新增一条技术约定，都应该在同一个 PR 里更新 AGENTS.md 的对应区块。只有这样，记忆工程才能真正“活”起来，而不是变成一份自娱自乐的死文档。

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

5.1 AI 完全无视 AGENTS.md 怎么办

这是最开始最打击人的问题。我首次写出 AGENTS.md 后，发现 AI 理都不理，我才意识到：文件放在仓库里不假，但工具不会自动读它。很多 AI 编程工具的上下文默认只包含当前打开文件或显式引用的文件。

解决方法很简单：在首条消息里显式引用 AGENTS.md，告诉 AI“先读仓库根目录的 AGENTS.md，再开始执行任务”。大部分主流工具都支持这种引用机制。你可以把这个指令固化到使用习惯里，之后再问就是顺畅的了。

5.2 内容太长导致 token 浪费怎么办

AGENTS.md 写得越详细，AI 每次读取消耗的 token 就越多。一开始我薅羊毛一样把能想到的都写进去了，结果一个大型仓库的 AGENTS.md 有 200 多行，每次对话光读它就消耗几千 token，效率反而下降。

解决思路是“分层摘要 + 子文件拆分”。根目录的 AGENTS.md 保持精简，只放最高频的 20 条规则；更细的内容放到.agents/子目录的独立文件中，AI 需要时再去读。比如.agents/web-guidelines.md只负责前端细节，根文件里留一行“前端开发规则见 .agents/web-guidelines.md”。

5.3 AGENTS.md 更新后，AI 仍然用旧规则怎么办

这个问题的根源在于缓存。部分工具会缓存上下文或历史消息，即使文件已经更新，AI 可能在当前会话中仍然沿用旧信息。所以遇到这种情况，最简单有效的操作就是开启新会话，让 AGENTS.md 作为新鲜上下文被重新加载。

使用中我还有一个习惯：每次修改 AGENTS.md 后，在“维护记录”区块里追加一条日期和说明。下次打开新会话时，我会顺手提到“注意 AGENTS.md 最新更新于某日期，请优先遵守新增规则”，这样能大幅降低旧规则残留的概率。

5.4 团队协作时同事不习惯维护这份文件

这个问题其实最好解决，只要用一次“重开会话测试”让大家亲眼看到差别就行。准备同一个问题，开两个新会话，一个让 AI 直接回答，另一个让它先读 AGENTS.md 再回答。结果差异一目了然。

我在团队里做过同样的事情，从那之后，维护 AGENTS.md 就不再是“额外负担”，而成了每个人写代码时都会自觉更新的常规动作。另外建议把 AGENTS.md 的 review 放在 PR 模板里作为一个勾选项，哪怕是一句话“本次改动是否涉及架构决策？如有请同步更新 AGENTS.md”，效果都非常明显。

说了这么多，还是想再强调一件事：AGENTS.md 的核心价值不只是“让 AI 更听话”，更在于它逼着我们把项目里那些默认大家都会的隐性知识，一件件摆到台面上。这个过程本身就是一次高质量的项目复盘。我踩过不少坑，从最开始把它写成产品宣传手册，到后来改成一条条可执行的行动指令，这份文件才真正变成了 AI 协作里的“定海神针”。

最后分享一个小技巧：每季度挑一个下午，花 30 分钟把 AGENTS.md 从头到尾读一遍，删除已经不再适用的旧决策，合并重复条目，保持文件小而锐利。记忆工程从来不是越厚越好，而是越精确越好。做完这轮裁剪，你会发现 AI 生成的代码又稳妥了一个档次。