企业官网建设流程全解析

1. 从"每次重新解释一遍"说起：无状态模型到底卡在哪

如果你最近半年深度用过任何一款 AI 编程助手，大概率经历过这种循环：新开一个会话，先花五分钟把项目背景、技术栈、目录约定、命名规范、测试命令一股脑喂进去，然后才开始问正事。第二天再开一个会话，同样的五分钟再来一遍。更让人抓狂的是，同一个问题昨天已经纠正过一次，今天它又犯了——因为它根本不记得昨天发生过什么。

这不是模型变笨了，而是**无状态（stateless）**这个底层特性决定的。绝大多数对话式 AI 编程工具，每一次请求都是独立的：你发过去的上下文，加上系统提示词，构成这一次推理的全部输入。会话结束，一切归零。模型没有跨会话的长期记忆，也没有对"你这个项目"的持久认知。

于是问题就来了。我们过去几年习惯的编程范式是"人写代码，工具辅助"，工具是确定性的、可复现的。而 AI 编程助手是概率性的、上下文敏感的。当你把一个概率性组件塞进一个需要确定性的工程流程里，冲突就出现了：你希望它稳定遵守项目规范，但它每次都在重新猜你的意图。

我见过太多团队卡在这一步。有人选择写一个超长的系统提示词，每次粘贴；有人干脆放弃，只把 AI 当"高级搜索"用，写点独立函数就完事。这两种做法都没错，但都没触及问题的根子——缺一层"记忆工程"。

所谓 Memory 工程，说白了就是：把那些"每次都要重复告诉模型的东西"从临时对话里抽出来，变成项目里持久化、可版本管理、可被工具自动读取的声明式配置。而AGENTS.md这类文件，正是这套思路目前最务实的落地形态。它不神秘，本质就是一份放在仓库根目录的 Markdown，约定好"这个项目是什么、怎么跑、有哪些规矩"，让 AI 助手在每次会话开始时自动加载。

这篇文章想聊的，就是这次范式转换背后的完整逻辑：为什么无状态模型必须配记忆层、AGENTS.md这类声明式配置该怎么写才有效、从"提示词工程"到"记忆工程"的思维怎么切换，以及我在实际项目里踩过的那些坑。不管你是刚接触 AI 编程的新手，还是已经用了一阵子但总觉得"不够顺手"的老手，应该都能从中找到能直接抄作业的部分。

2. 无状态模型的三个真实痛点，以及它们为什么无法靠"更努力地写提示词"解决

2.1 上下文窗口不是记忆，它只是"这一次的草稿纸"

很多人有个误解：现在上下文窗口都几十万 token 了，我把项目文档全塞进去不就行了？理论上可以，实践上很糟。

第一，成本。每次请求都携带几万 token 的项目背景，token 消耗是实打实的，长会话下来账单很难看。第二，注意力稀释。上下文越长，模型对中间部分的关注度越容易下降，这是目前架构的普遍现象，你塞进去的规范文档很可能被"淹没"。第三，不可复用。这次会话塞进去了，下次还得重塞，没有任何沉淀。

上下文窗口是"草稿纸"，用完就扔；记忆是"笔记本"，写下来能反复翻。把草稿纸当笔记本用，是第一个认知误区。

2.2 提示词工程的天花板：它优化的是"单次表达"，不是"长期一致性"

提示词工程（Prompt Engineering）这两年很火，各种技巧满天飞。但它的核心目标其实是优化单次交互的输出质量——怎么问能让模型这次答得更好。它解决不了"跨会话一致性"的问题。

举个具体例子。你在提示词里写"所有函数必须加类型注解"。第一次会话，模型照做了。第十次会话，你换了个问法，它可能就忘了这条。因为这条规则只存在于那一次的系统提示里，没有成为"项目的一部分"。提示词工程是会话级的，而项目规范需要的是仓库级的。层级不对，再努力也白搭。

2.3 团队协作场景下，"每个人各自调教"等于没有规范

单人开发时，你脑子里记着项目约定，每次手动补进提示词，勉强能跑。一旦团队超过两个人，灾难就来了：A 同学习惯让 AI 用某种目录结构，B 同学习惯另一种，C 同学压根不告诉 AI 项目背景。结果就是 AI 产出的代码风格五花八门，review 成本飙升。

问题的本质是：项目知识没有单一可信来源（single source of truth）。每个人都在自己的会话里维护一份"私有记忆"，这些记忆互相不可见、不可同步。要解决它，必须把记忆从"个人会话"搬到"共享仓库"。

这三个痛点指向同一个结论：我们需要一层独立于会话、独立于个人的持久化配置。这就是 Memory 工程要干的事，也是AGENTS.md这类文件存在的理由。

3. AGENTS.md 到底是什么：一份被工具自动读取的"项目说明书"

3.1 它的本质：约定优于配置，Markdown 优于 JSON

先破除神秘感。AGENTS.md不是什么官方标准协议，它更像一个社区逐渐形成的约定：在仓库根目录放一个 Markdown 文件，用自然语言描述项目信息，AI 编程工具在启动会话时自动读取它，作为系统提示的一部分。

为什么是 Markdown 而不是 JSON/YAML？因为这份文件的读者是语言模型，不是程序。模型对自然语言的理解远好于对结构化配置的解析。你用 JSON 写"测试命令是 npm test"，模型还得解析字段；你直接用一句话写"跑测试用npm test，注意要先启动本地数据库"，模型理解得更准。给模型看的东西，就该用模型最擅长的格式。

为什么叫"约定优于配置"？因为它没有强制的 schema，没有必填字段。你写什么、写多细，完全取决于项目需要。工具只负责"读进来塞进上下文"，剩下的靠你自己组织。这种松散性既是优点（灵活）也是缺点（容易写歪），后面会专门讲怎么写好。

3.2 它和 README、CONTRIBUTING 的区别在哪

有人会问：我项目里已经有 README 了，为什么还要单独搞一个AGENTS.md？

关键区别在读者和目的。README 是写给人看的，重点是"这个项目是什么、怎么用、怎么贡献"，语气是介绍性的。AGENTS.md是写给AI 助手看的，重点是"你在这个仓库里干活时必须遵守什么"，语气是指令性的。

举个对比。README 里可能写："本项目使用 ESLint 进行代码检查。" 这是陈述。AGENTS.md里应该写："提交前必须跑npm run lint，不允许有 warning；如果 lint 报错，先修 lint 再谈功能。" 这是命令。同样的信息，后者对 AI 的行为约束力强得多。

所以两者不冲突，是互补的。README 面向人类协作者，AGENTS.md面向 AI 协作者。有些团队会把AGENTS.md里的通用部分同步到 CONTRIBUTING，保持人机规范一致，这是个好习惯。

3.3 一份最小可用的 AGENTS.md 长什么样

先给个能直接用的骨架，后面再逐块拆解：

# 项目：某内部数据看板 ## 技术栈 - 前端：React 18 + TypeScript + Vite - 后端：Node.js + Fastify - 数据库：PostgreSQL 15 - 包管理：pnpm（禁止用 npm/yarn） ## 常用命令 - 安装依赖：`pnpm install` - 启动开发：`pnpm dev`（前端 5173，后端 3000） - 跑测试：`pnpm test`（改完代码必须跑） - 类型检查：`pnpm typecheck` ## 代码规范 - 所有函数必须有显式返回类型 - 组件文件用 PascalCase，工具函数用 camelCase - 禁止 any，实在需要就用 unknown + 类型守卫 - 提交信息遵循 Conventional Commits ## 目录约定 - `src/components` 放通用组件 - `src/features` 放业务模块，每个模块自带测试 - `src/lib` 放纯工具函数，不允许 import 业务代码 ## 注意事项 - 改数据库 schema 必须同步更新 `migrations/` 下的迁移文件 - 不要动 `src/legacy/` 目录，那是待重构的旧代码

这份文件不到 40 行，但已经能解决 80% 的"AI 不懂我项目"问题。关键在于它把命令、规范、边界三件事说清楚了。

4. 从提示词工程到记忆工程：思维方式的四个转变

4.1 从"这次怎么问"到"以后都怎么答"

提示词工程的思维是面向单次的：我这次怎么措辞，能让模型给出好答案。记忆工程的思维是面向长期的：我怎么配置，能让模型在未来所有会话里都表现一致。

这个转变很关键。举个例子，你发现模型总是忘记给函数加类型注解。提示词工程的做法是：这次在问题里补一句"记得加类型注解"。记忆工程的做法是：在AGENTS.md里写一条"所有函数必须有显式返回类型"，一劳永逸。前者解决一次，后者解决一类。

判断标准很简单：如果某条信息你重复说了超过两次，它就该进记忆文件，而不是继续留在对话里。

4.2 从"描述项目"到"约束行为"

新手写AGENTS.md最容易犯的错，是把它写成 README 的翻版——大段介绍项目背景、业务价值、架构图。这些对 AI 干活帮助有限。AI 需要的是可执行的行为约束。

对比一下：

右边这列才是 AI 真正需要的。它不关心你的项目"是什么"，它关心"我该怎么做"。把描述翻译成指令，是记忆工程的核心动作。

4.3 从"个人习惯"到"团队契约"

单人项目里，AGENTS.md是你自己的备忘。团队项目里，它是团队对 AI 的行为契约。这意味着它需要像代码一样被 review、被版本管理、被讨论。

我见过一个团队的做法很值得借鉴：他们把AGENTS.md纳入 PR 流程，任何人修改它都要走 review。理由是——这份文件影响所有人生成的代码风格，改它等于改团队规范，当然要慎重。这个思路把"记忆"从个人资产升级成了团队资产，是成熟团队该有的样子。

4.4 从"写一次就完"到"持续迭代"

AGENTS.md不是写完就锁死的。项目在变，规范在变，AI 工具的能力也在变。你需要定期回顾：哪些规则 AI 总是违反（说明写得不够清楚）？哪些规则已经过时（说明该删了）？哪些新踩的坑该补进去？

我的习惯是每次被 AI "坑"一次，就顺手往AGENTS.md里加一条。比如有次它擅自把测试文件放到了src/根目录，我就在目录约定里补了一句"测试文件必须和被测文件同目录，命名*.test.ts"。这种"踩坑即沉淀"的机制，让这份文件越用越顺手。

5. 手把手写一份真正管用的 AGENTS.md：分模块拆解

5.1 技术栈与命令：让 AI 知道"用什么跑"

这是最基础也最重要的一块。AI 需要知道两件事：用什么技术，以及怎么执行。

技术栈部分要具体到版本和关键选型。不要只写"用 React"，要写"React 18 + TypeScript + Vite"。因为不同版本、不同构建工具的写法差异很大，写清楚能避免 AI 给出过时或错误的代码。

命令部分要覆盖日常开发的全流程。我建议至少包含这几类：

• 安装：pnpm install（顺便注明禁用其他包管理器）
• 开发：pnpm dev（注明端口，避免 AI 猜错）
• 测试：pnpm test（注明"改完必须跑"）
• 检查：pnpm lint、pnpm typecheck
• 构建：pnpm build

提示：命令一定要写完整可复制的形式。别写"用 pnpm 装依赖"，要写pnpm install。AI 会直接照抄，写全了它就不会猜。

有个细节容易被忽略：注明命令的执行前提。比如"跑测试前需要先启动本地数据库"，或者"构建前必须先跑 typecheck"。这些前提不写，AI 可能直接跑命令然后失败，浪费一轮交互。

5.2 代码规范：把"团队默契"翻译成"明文条款"

代码规范是最能体现记忆工程价值的部分。团队里那些"大家都懂"的默契，对 AI 来说全是空白。你必须把它们写出来。

我通常分几类写：

命名规范。文件、变量、函数、组件的命名规则。比如"组件文件 PascalCase，工具函数 camelCase，常量全大写下划线分隔"。写清楚能避免 AI 一会儿getUser一会儿get_user。

类型规范。TypeScript 项目尤其重要。"禁止 any""优先用 interface 而非 type""所有导出函数必须有返回类型"。这几条能显著提升 AI 生成代码的质量。

格式规范。缩进、引号、分号这些，如果项目有 Prettier/ESLint 配置，直接写"遵循.prettierrc和.eslintrc，不要手动调整格式"。让 AI 知道有工具兜底，它就不会自作主张。

提交规范。如果用 Conventional Commits，写清楚格式和常用 type。AI 帮你写提交信息时就能直接对上。

这里有个经验：规范要写"为什么"，不只是"是什么"。比如"禁止 any，因为我们要保证类型安全，any 会让类型检查形同虚设"。带上理由，AI 在边界情况下更容易做出正确判断，而不是机械照搬。

5.3 目录结构与边界：告诉 AI"什么能碰，什么别碰"

目录约定这块，核心是划清边界。AI 不知道你的项目里哪些是核心代码、哪些是历史遗留、哪些是自动生成的，你不说它就可能乱改。

我一般会写三类信息：

目录职责。每个主要目录放什么。比如src/components放通用组件，src/features放业务模块，src/lib放纯工具函数。写清楚职责，AI 就知道新代码该放哪。

依赖方向。这是很多人忽略的。比如"src/lib不允许 import 业务代码""features之间不允许互相 import，公共逻辑抽到lib"。这些约束能防止 AI 写出循环依赖。

禁区。明确哪些目录不要动。比如"src/legacy/是待重构旧代码，不要修改""generated/是自动生成的，改了会被覆盖"。禁区写清楚，能省掉大量"AI 改错地方"的返工。

注意：边界规则要写得可判定。"不要写烂代码"这种没法执行，"lib不允许 importfeatures"这种才能被 AI 判断和执行。

5.4 注意事项与踩坑记录：把"血泪教训"变成"团队资产"

这是最有个性、也最有价值的一块。每个项目都有自己独特的坑，这些坑不写下来，AI 就会反复踩。

我习惯把这块写成"清单式"的，每条一句话，说清楚"什么情况"和"怎么办"。比如：

• 改数据库 schema 必须同步写迁移文件，否则本地和线上不一致
• 环境变量新增后要同步更新.env.example，否则别人拉下来跑不起来
• 涉及金额计算一律用整数分，禁止浮点数，避免精度问题
• 第三方 API 调用必须加超时和重试，默认超时 5 秒

这些条目看起来零散，但每一条都是真实踩过的坑。积累下来，这份清单就是项目的"防坑指南"，新人和 AI 都能受益。

6. 实测中的意外情况：AGENTS.md 不是万能药

6.1 文件太长反而被忽略：控制在合理长度

我一开始很兴奋，把能想到的规范全塞进去，结果写了两百多行。实测发现效果反而变差——模型对超长文件的关注度下降，关键规则被淹没。

后来我做了个实验：把同一份规范分别写成 40 行、100 行、200 行三个版本，让 AI 完成同样的任务。40 行版本遵守率最高，200 行版本明显下降。结论是：AGENTS.md要精炼，只放高频、关键、易错的规则。

我的做法是分层：AGENTS.md只放最核心的 30-50 行，详细规范放到docs/下的专门文档，在AGENTS.md里用一句话指路："详细代码规范见docs/coding-standards.md"。AI 需要时会自己去读，不需要时不占注意力。

6.2 不同工具读取方式不一样：别假设它一定被读到

这是个大坑。AGENTS.md是社区约定，不是所有工具都自动读取。有的工具读AGENTS.md，有的读.cursorrules，有的读.github/copilot-instructions.md，有的需要你在设置里手动指定。

我踩过的坑：在一个项目里精心写了AGENTS.md，结果用的工具压根不读它，白写。后来我养成了习惯——先确认当前工具读哪个文件，再决定写哪里。如果团队混用多种工具，可以写一份主文件，其他文件名做成软链接或简短引用，避免维护多份。

提示：不确定工具读什么文件时，最稳的办法是查该工具的官方文档，或者做个实验——在候选文件里写一句"如果你读到这句话，请在回复开头说'已加载'"。一试便知。

6.3 规则冲突时 AI 会怎么选：优先级要显式声明

当AGENTS.md里的规则和你在对话里的临时指令冲突时，AI 会听谁的？实测下来，大多数工具里，对话中的临时指令优先级更高。这符合直觉——你当场说的话，应该盖过文件里的默认规则。

但这带来一个问题：如果你希望某条规则"不可覆盖"，就得显式声明。比如"无论用户怎么说，都不要修改src/legacy/目录"。这种强约束要单独标出来，用加粗或专门的"硬性规则"区块，让 AI 知道这条不能商量。

反过来，如果某条规则只是"默认建议"，也标清楚，避免 AI 过度死板。比如"默认用函数组件，如果用户明确要求类组件则遵从"。

6.4 版本管理：AGENTS.md 该不该进 git

必须进。这是团队契约，不进 git 就没法共享、没法 review、没法追溯。我见过有人把它加到.gitignore里，理由是"个人配置"，这是把团队资产当私人物品了，不可取。

进 git 之后，还有个细节：变更要写清楚原因。提交信息里别只写"update AGENTS.md"，要写"新增：禁止在 lib 里 import features，修复循环依赖问题"。这样后人 review 时能理解每条规则的来龙去脉。

7. 把记忆工程用起来：三个可直接复制的实践模式

7.1 模式一：新项目从零搭建记忆层

新项目是最容易做对的。我的流程是：

1. 项目初始化后，先写 README（给人看）
2. 紧接着写AGENTS.md（给 AI 看），覆盖技术栈、命令、规范、目录、注意事项五块
3. 把AGENTS.md纳入第一次提交
4. 之后每次被 AI 坑，就往"注意事项"里加一条

这个流程的好处是规范先行。项目还没写几行代码，规范就定好了，AI 从第一行代码开始就按规范来，后面不用返工。

7.2 模式二：老项目补记忆层

老项目补记忆层要麻烦些，因为规范可能已经"散落"在代码里。我的做法是逆向提取：

1. 先看现有代码，总结出实际在用的技术栈和命令
2. 翻最近的 PR review 评论，把反复提到的规范整理出来
3. 看目录结构，归纳出职责划分
4. 回忆最近被 AI 坑的几次，写成注意事项

不用一次写全，先写个 60 分的版本，后面持续补。关键是先有，再优。

7.3 模式三：多工具共存时的记忆同步

团队混用多种 AI 工具时，最怕规范不同步。我的方案是单一主文件 + 引用：

• 主文件：AGENTS.md，写全部内容
• 其他工具需要的文件：只写一行"本项目规范见AGENTS.md，请先读取该文件"

这样规范只有一份，改一处全生效。如果某工具不支持引用，就写个脚本在提交时自动同步，避免手动维护多份。

8. 我踩过的几个坑，以及现在回头看该怎么避

第一个坑是把AGENTS.md写成技术文档。我一开始写了大段架构说明、模块关系图，结果 AI 该犯的错还是犯。后来才明白，AI 要的是"行为指令"，不是"背景知识"。现在我的原则是：每写一条，都问自己"这条能约束 AI 的某个具体行为吗"，不能就删。

第二个坑是规则太抽象。"写高质量的代码"这种规则等于没写。什么叫高质量？AI 没法判断。必须具体到"函数不超过 50 行""嵌套不超过 3 层""所有异步操作必须处理错误"这种可判定的标准。

第三个坑是忘了更新。项目从 Vite 换到 Next.js，AGENTS.md里还写着 Vite 的命令，AI 就按旧的来，跑不通。现在我养成了习惯：任何影响开发流程的变更，都同步更新AGENTS.md，把它当成项目配置的一部分。

第四个坑是过度依赖。有段时间我完全放手让 AI 干，结果它虽然遵守了AGENTS.md的规则，但规则本身有漏洞，产出的代码在边界情况下出问题。教训是：AGENTS.md是辅助，不是替代。关键决策还得人来把关，规则也要定期 review。

9. 关于这套范式，我现在的真实看法

用了一年多，我的体会是：记忆工程的价值不在于让 AI 变聪明，而在于让 AI 变稳定。它不会让模型突然理解你那些复杂的业务逻辑，但它能确保模型每次都记得"这个项目用 pnpm""改 schema 要写迁移""别碰 legacy 目录"。这种稳定性，才是把 AI 真正纳入工程流程的前提。

AGENTS.md只是当前阶段的一个务实形态。未来可能会有更标准的协议、更智能的记忆机制，但底层逻辑不会变：无状态模型 + 持久化记忆 = 可用的工程助手。理解了这一点，具体用什么文件、什么格式，都是次要的。

如果你现在还没开始搞记忆层，我的建议是别追求完美，先写 20 行。把最常重复的那几条规范写进去，用起来，然后持续补。这份文件会随着你的项目一起成长，最后变成团队里最有价值的那份"隐性知识显性化"的资产。