企业官网建设流程全解析

无状态模型折腾了我半年，然后把规则写进 AGENTS.md 之后，AI 终于记得项目的事了

最近在维护一个跨平台小工具项目，我发现一件很磨人的事：每轮让 AI 写代码，都得先花几分钟把项目背景重新交代一遍。用 TypeScript、用 Vite、别用 any、数据库字段叫 user_id 而不是 userId、构建命令是 pnpm build……这些规则我几乎天天说，AI 也天天忘。有时候同一轮对话里它记住了，下一轮新会话又回到“初次见面”的状态。我一开始怀疑是提示词写得不够长，后来发现问题的根源不在提示词，而在模型默认的“无状态”工作方式。

这半年折腾下来，我对“AI 编程范式转换”这件事有了非常具体的感觉：单论写代码的能力，模型已经很能打了，真正拖后腿的是它没有记忆。业内把给 AI 补记忆这件事叫 Memory 工程，而这个方向上最实用、最不花哨的落地形态，就是标题里说的 AGENTS.md 声明式配置。这篇文章把我从“每轮重复交代”到“项目自带规则文件”的完整经历写出来，包括原理、写法、迁移步骤和踩过的坑。如果你是重度使用 AI 编程助手、又觉得每次都要重复交代很烦的人，这篇应该能直接帮到你。

1. 无状态模型的硬伤：为什么每次对话都像初次见面

要理解为什么 AGENTS.md 有用，得先搞清楚我们面对的问题到底是什么。很多人以为 AI“记不住”是上下文窗口不够大，其实不完全是。

1.1 模型的本质是一个“失忆的天才”

大语言模型本质上是一个无状态函数：输入一段文字，输出一段文字，调用结束后不存在任何跨调用的状态。你可以把它想象成一位技术极强、但每隔五分钟就会彻底失忆的程序员。他能在失忆前那一分钟里写出惊艳的代码，但你无法靠“上轮说过”让他记住任何约定，因为他的记忆每轮都被清零。

这不是模型偷懒，是架构决定的。模型在推理时只看到当前输入，之前聊了什么、改了什么文件，对它来说都不存在。于是就有了一个很反直觉的现象：模型单轮任务完成度越来越高，复杂多轮项目却推进得磕磕绊绊。单论“会不会写代码”，模型已经是专家级别；但论“记不记得项目约定”，它基本是零。

1.2 上下文窗口只是“临时便签”，不是记忆

“那给它更大的上下文窗口不就行了？”这是最常见的误解。上下文窗口确实能装更多 token，但它本质上是临时便签，不是长期记忆。两个区别最要命：

第一，token 有预算。代码块、日志、readme 塞得越多，模型处理和“思考”的空间就越小，注意力被大量无关细节稀释。第二，上下文越长，模型对早期内容的注意力会自然衰减。哪怕你把 50 条项目规则放在第 2000 行，模型读到后段代码时也大概率抓不住重点。

我试过把整个项目的 README、接口文档、代码规范全部粘贴进对话，结果 AI 确实“知道”了这些内容，但真正写代码的时候，它更容易被眼前的一小段代码带偏，而不是遵循文档里的全局约束。原因很简单：文档是死的，项目上下文是活的，模型需要在海量信息里自己做取舍，一旦取舍错了，就是“照着文档说一套、写代码做另一套”。

1.3 无状态范式在单文件任务够用，在多文件项目失灵

如果只是让它写一个独立函数、改一个文件，无状态几乎不影响结果。但真实项目不是单文件，我有一次让它重构某模块，它改了 A 文件的调用方式，却没有同步改 B 文件的 import，因为 B 文件的内容压根没进它的上下文。它不知道 A 和 B 之间的依赖关系，不是因为笨，是因为我们没把“项目结构”这个状态给它。

为了补救，大家普遍在用三种“补丁式”做法：

• 超长 prompt 模板：把项目规则写在 system prompt 里，每轮都带上。有效果，但 prompt 越来越长，维护成本高，改一次规则要重新复制粘贴到每一个工具和会话。
• 动态检索再注入：开个向量库，把代码片段向量化，每次调用前检索相关文档塞进上下文。这是 RAG（检索增强生成）的思路，方向对，但对小项目太重，又容易检索到一堆废话。
• 把所有文档塞进上下文：干脆把仓库里的文档全量粘贴进去。简单粗暴，token 爆炸，模型反而抓不住重点。

这三种做法的共同问题，是它们把“记忆”这件事完全压在每次调用的输入上，治标不治本。真正的解法，是把记忆从“对话中的临时交代”变成“项目里持久存在的、AI 每次开工前都能自动读到的东西”。这就是 Memory 工程的核心思路，也是 AGENTS.md 诞生的背景。

2. Memory 工程的分层思路：短期、长期与工作记忆

知道了问题根源，再看解决方案。Memory 工程听起来唬人，其实拆开就三层，和我们人脑的记忆机制非常像。

2.1 人脑记忆给我们的架构启发

人类做复杂任务时，靠的是三种记忆配合：工作记忆（当下正在处理的信息）、短期记忆（几分钟到几小时内可调用的信息）、长期记忆（跨天跨月沉淀下来的知识和经验）。

AI 编程想要真正“记住”项目，需要的也是这三层：

• 短期记忆：当前对话里已经讨论过的代码、错误、修改计划。上下文窗口承担的就是这个角色，但它装不满、没边界，需要主动管理。
• 长期记忆：项目里沉淀下来的文档、代码库、历史决策。RAG、向量库、数据库都属于这个范畴。
• 工作记忆：执行当前任务时“必须时刻记住的约束和上下文”。比如“本项目用 Python 3.11”“测试命令是 pytest”“不要改动 schema”这类直接影响下一步动作的信息。

有意思的是，大多数做 Memory 工程的人，注意力全放在长期记忆（RAG、向量库）上，反而忽略了工作记忆——而这恰恰是 AI 写代码时最缺的东西。它不需要在写一个函数时检索整个代码库的历史，它只需要知道“这批代码活在一个什么样的项目规则里”。

2.2 短期记忆层：上下文的压缩与摘要

短期记忆的典型技术是对话摘要。当对话超过一定长度，就把前面的对话压缩成一段结构化摘要，塞回上下文。比如“已明确项目使用 TypeScript；用户要求重构模块 A 并同步修改 B 文件；当前卡点在 C 文件的类型错误”。

这个层解决的是“会话过长导致信息丢失”，但它的缺点也很明显：摘要的粒度取决于压缩策略，除非每一步都做得非常细，否则总会有重要细节被压掉。我自己试过几轮摘要，发现长对话超过一小时，摘要本身就会变成一个“模糊的梗概”，细节还得靠原文。

所以短期记忆适合做“临时防丢”，不适合当“规则载体”。项目规则如果只存在于对话摘要里，第二天开新会话照样失忆。

2.3 长期记忆层：向量检索与结构化存储

长期记忆解决的是“跨会话的知识沉淀”。常见方案有：

向量库那套方案在超大代码库里确实有效，但小项目上它经常是杀鸡用牛刀。你为一个三五个人的项目搭一套 embedding 管线，索引要更新、检索质量要调，到头来 AI 该记错的还是记错。而且 RAG 检索来的大概率是“相关文档片段”，它不能保证这些片段里正好有“构建命令是什么、字段命名规范是什么”这类全局约束。

对大多数项目来说，最划算的长期记忆不是向量库，而是文件系统——把规则写进一个文件，让 AI 每次开工前自动读一遍。这也是 AGENTS.md 这类声明的底层思路。

2.4 被低估的工作记忆层：AGENTS.md 为什么重要

AGENTS.md 本质上是“工作记忆的持久化”。它把项目里最核心、最稳定的约束写成一个文件，放在仓库根目录，AI 工具启动时自动加载，相当于给每次调用的模型设置了一份“项目默认值”。

和“每次对话贴 prompt”相比，它的优势一目了然：

这正好回应了标题里的“范式转换”：从把记忆交给“每次对话时的临时输入”，转变成把记忆交付给“项目基础设施”。前者是每次靠人肉搬运，后者是项目自带记忆体。

3. AGENTS.md 声明式配置：让项目自己“记住”规则

现在说点能上手的。AGENTS.md 到底怎么用？它不是某个工具的专属功能，而是正在形成的一种社区约定——很多主流 AI 编程编辑器、命令行助手，启动时会自动在项目根目录查找 AGENTS.md，把它作为项目说明加载进上下文。你写好了，它就能被自动读取。

3.1 它到底是什么

AGENTS.md 是一份给 AI 看、也给人看的“项目说明书”。传统 README 面向人类，讲安装、用法、贡献指南；AGENTS.md 面向 AI 编程助手，讲的是“这个项目的技术栈是什么、命令是什么、有哪些规则必须遵守、哪些地方容易踩坑”。

它不需要写得像代码规范那么细，它更像是给一位刚到岗的新同事看的“入职手册”：

• 我们用什么语言和框架？
• 构建、测试、运行命令是什么？
• 代码放在哪些目录？
• 命名、格式、数据库字段有什么硬性约定？
• 开发这个项目时最常见的错误是什么？
• 如果你要改代码，应该先看哪些文件？

AI 每次开工前读一遍 AGENTS.md 的效果，就像一个靠谱的新同事每天开工前翻一遍团队协作手册。问题在于，这份手册从前不存在，每次还得靠项目经理（也就是你）口述。

3.2 一份合格的 AGENTS.md 应该写什么

分享一份我调过很多轮才稳定下来的骨架，你可以直接拿去改：

# 项目名称与一句话定位 ## 技术栈 - 后端：Python 3.11，FastAPI - 前端：Vue 3 + TypeScript + Vite - 数据库：PostgreSQL，ORM 使用 SQLAlchemy ## 常用命令 - 安装依赖：pip install -r requirements.txt - 启动后端：uvicorn app.main:app --reload - 启动前端：pnpm dev - 测试：pytest tests/ -v ## 目录结构导览 - app/main.py：应用入口，路由注册 - app/models/：SQLAlchemy 模型定义 - app/api/：路由与视图逻辑 - frontend/src/：前端源码 ## 编码规范与约束 1. Python 代码必须加类型注解 2. 数据库字段命名一律 snake_case，禁止 camelCase 3. 禁止在代码中硬编码数据库连接串，必须从环境变量读取 4. API 错误统一返回 { "error": "..." } 结构 ## 高频易错点 - 修改 app/models/ 下的文件后，必须同步生成/更新迁移脚本 - 前端调用 API 时，时间字段统一传 ISO 8601 字符串，不要传时间戳 ## 工作流 - 修改代码后必须运行测试 - 提交 PR 前请先跑一遍 eslint 和 prettier - 如果修改了数据库模型，必须在提交说明中写明迁移脚本编号

看见没，这不是一篇论文，是一张“高频注意事项清单”。它不解释为什么，只声明状态和约束。读到这里你可能已经意识到，它跟我们平时写的 README 有很大部分重叠，区别在于：README 面向人，解释为主；AGENTS.md 面向 AI，命令和约束为主。

3.3 写作语法与组织技巧

AGENTS.md 没有统一标准语法，目前的惯例是 Markdown，重点靠标题和列表组织。但有几点是我试过值得注意的：

声明式优于命令式。不要写“你必须先读 app/models/base.py 再看 app/api/user.py 最后修改 app/main.py”，而要写“本项目路由层在 app/api/，模型层在 app/models/。改动数据库相关逻辑时，API 层和模型层可能都需要同步修改”。声明现状和约束，让 AI 自己规划路径，效果远好过给它硬编码执行步骤。

用链接和索引控制上下文预算。如果项目有详细文档，不要在 AGENTS.md 里全文复制，用链接指过去，交代清楚“更详细的设计说明见 docs/design.md，处理支付逻辑前先读它”。AI 会按需决定是否读取链接内容，这比把几十万字的文档塞进上下文聪明得多。

每条规则都要能执行。“代码质量要好”这种话别写，AI 没法判断，只会消耗注意力。要写“代码必须通过 eslint：pnpm lint”、“每个函数必须有 docstring”。凡是 AI 无法自检的规则，写了等于没写。

把最容易犯的错放在文件靠前位置。AI 读 AGENTS.md 时，前面内容权重更高。我把“数据库字段用 snake_case”这种高频错误放在编码规范第一条，后面隔几行又用易错点章节重复提醒，实际效果比只提一次好很多。

3.4 主流工具读取 AGENTS.md 的方式

我测过几种主流工具（不点名了），加载逻辑大同小异：工具开会话时，会从当前工作目录向上查找 AGENTS.md，找到后将其内容拼接到 system prompt 前部；有的工具支持在子目录再放一份，针对特定目录追加配置。

这里有个排坑第一课：先搞清楚你的工具到底读哪个文件、从哪一层目录开始找。我踩过一个大坑——把规则写在子目录的 AGENTS.md 里，根目录没有，结果某工具只在根目录找，直接忽略。查了好久才发现是加载路径问题。

另外，不同工具的规则文件名可能有差别（AGENTS.md、CLAUDE.md、rules 之类都见过），如果你同时用多个工具，最好先确认它们的配置文件命名和优先级。我的做法是把核心规则写在根目录 AGENTS.md，其他命名文件只放一行转引：“项目规则请阅读 AGENTS.md”，避免多份文件互相矛盾。

4. 一次迁移实录：把“无状态提示词”改造成 AGENTS.md 驱动

光讲原理没用，我把一次真实的改造过程完整写出来。这是一个虚构的小型跨平台工具项目，但步骤完全是我实际用的那套，可以直接照抄。

4.1 改造对象与改造前状态

我维护着一个内部用的数据导出工具：Python 后端负责从数据库拉数据并生成中间文件，前端负责参数配置和结果预览。整个项目不大，但涉及 Python、SQL、前端三块，技术栈比较杂。

改造前，我每轮对话都要给 AI 重复交代的内容大概是这样的：数据库连接串要读环境变量、PostgreSQL 字段是 snake_case、导出文件的编码必须是 UTF-8、前端构建用 pnpm。这些内容加起来大约 20 行，我几乎每次都粘贴一遍。即便这样，AI 还是经常在细节上犯错：有一次它把数据库字段写成了 camelCase，导致导出功能直接报错；另一次它不知道后端跑在哪，把一个路由写错位置，花了两轮才改回来。

4.2 第一步：收集项目规则，形成清单

我没有凭空写 AGENTS.md，而是先花半小时做了一轮“规则收集”：

• 翻了一遍根目录的 README 和现有文档，把已经成文的约定摘出来；
• 翻最近 10 次 Git 提交记录，看 AI 或同事反复改过什么——反复改的地方就是规则缺失的地方；
• 翻了最近几条 PR 的评论，看 review 时都在强调哪些点，比如“记得加迁移脚本”“时间字段传 ISO 字符串”；
• 最后把这些零散约定去重、归类，浓缩成 10 条硬约束，外加 2 条工作流规则和 4 条常用命令。

这一步非常关键：AGENTS.md 不是从零创作的，是从项目里“挖”出来的。不这么做，你写出来的往往是想当然的规则，而不是项目真正需要的规则。

4.3 第二步：写成 AGENTS.md，并验证加载

我把 10 条硬约束按上面的骨架整理成文件，放到项目根目录，提交。然后做了三件事验证：

1. 新开会话，直接问 AI：“这个项目用什么数据库？字段命名规范是什么？构建命令是什么？” 如果它答对了，说明 AGENTS.md 被读取了。
2. 让它执行一个会触碰到规则的任务，比如“在用户模型里加一个 createdAt 字段”，看它是否自动用了 snake_case、是否主动提了迁移脚本的事。
3. 故意制造一个模糊场景：“帮我写一段导出 CSV 的代码”，看它是否主动遵守“编码 UTF-8、字段用 snake_case”这两条。

我最初第一次验证就发现 AGENTS.md 没生效——排查后才发现，工具找的是根目录文件，而我把内容放到了子目录。改回根目录后立刻正常。

4.4 第三步：效果对比

改造后我观察了两周，最直观的变化是“每轮对话前不用再粘贴那 20 行规则了”。更具体的对比如下：

这个提升不是玄学。AI 每轮都带着项目规则开工，相当于我给它配了一位“永远不失忆的同事”，它的每一步产出都建立在同一个规则底座上。而底层逻辑其实就是 Memory 工程里最朴素的那条：把该记住的东西从临时对话里解放出来，放进项目基础设施里。

4.5 和“把文档喂给模型”的本质区别

可能有朋友会想：这不就是把 README 塞进 system prompt 吗？还真不是。区别在于上下文预算和规则聚焦：

全量喂文档，AI 要读几十万个 token，核心规则淹没在安装步骤、截图说明、历史版本里，注意力被稀释；AGENTS.md 是经过提炼的摘要，可能只有两三百行，核心规则密度极高，AI 读起来成本低、执行起来易聚焦。

我实际测试过，全量 README 方案下，AI 知道“项目是做什么的”，但它不知道“字段命名是 snake_case”这种实际操作层面的约束——因为 README 里根本没写。而 AGENTS.md 存在的目的，就是解决“文档里没有、但干活时必须知道”的高频规则。它不是 README 的替代品，是 README 面向 AI 的那一面。

5. 边界与教训：AGENTS.md 不是万能药

用了半年 AGENTS.md，我越来越确定它是“AI 编程记忆化”里性价比最高的起步方案。但该泼的冷水也得泼：它有自己的边界，用不好会变成负担。

5.1 配置膨胀陷阱：规则越多，AI 越记不住

一开始我恨不得把所有规则都写进 AGENTS.md，写了大几百行，包括各种边缘情况、禁止事项、历史背景。结果半个月后发现问题：AI 开始“选择困难”，它对大量规则的遵守率反而下降了。原因是注意力被稀释——规则太多，模型不知道哪些是重点，只能分散关注。

我的经验阈值：单文件控制在 200-300 行以内。超过这个量，就要做减法：删掉那些靠直觉就能做到的常识性规则（比如“代码要有注释”），只保留“违反过、且会出问题”的硬约束。万一项目确实复杂，规则超过 300 行，就把详细内容拆到单独文档，用链接引用，保持 AGENTS.md 本身是精炼索引。

5.2 多工具配置冲突：别让规则互相打架

我同时用着两个 AI 编程工具，一个编辑器插件，一个命令行助手。它们读配置文件的方式不完全相同：一个以 AGENTS.md 为准，一个优先读自己的规则文件。刚开始我没意识到，结果两边规则不一致，AI 在后一个工具里按旧规则写代码，改了半天才发现。

后来我定了一条规定：AGENTS.md 是唯一事实来源，其他配置文件只写转引。所有规则都改在 AGENTS.md 维护，其他命名文件里只放“项目规则见 AGENTS.md”一句话，彻底避免两份规则漂移。另外，不同工具读文件时的目录优先级也不同，统一放在仓库根目录是最稳妥的，子目录配置只放“该目录特有”的规则，冲突时以根目录为准。

5.3 规则漂移：AGENTS.md 没有编译期，过期了也不会报错

这是 AGENTS.md 最隐蔽的坑。代码有编译器和测试兜底，规则文件没有。项目换了构建工具、改了目录结构、数据库字段统一改名，AGENTS.md 里的旧规则却一直躺在那里，AI 照着过时规则写代码，出错你还得背着。

给两个实操建议：一是把 AGENTS.md 纳入 code review，改配置走跟改代码一样的流程；二是每季度做一次“规则审计”，对着当前项目结构逐条核对，失效规则直接删。另外，如果你发现 AI 连续两次犯同一个错，大概率不是它笨，是 AGENTS.md 里缺这条规则——立刻补上，这是规则迭代最实在的时机。

5.4 别让 Memory 工程变成“自嗨”

说了这么多，最后必须提醒一点：AGENTS.md 的价值是减少重复劳动，不是制造新的维护工作。如果你维护配置的时间超过了省下的时间，它就是负担而非杠杆。我自己判断的标准很简单：每季度看一次“没有 AGENTS.md 时，我每个任务开头要花多少时间交代规则、要返工几次”，如果答案已经不明显优于改造前，就说明配置该优化而不是继续堆内容。

其实 Memory 工程的方向是对的，但落地形式越重越容易失败。AGENTS.md 这种“一个文件、随仓库走、调参成本低”的思路，恰好踩在了成本和收益的甜点上。先把它用起来，你才能真实感受到“AI 有记忆”和“AI 没记忆”之间的差别有多大。

我一直觉得，AI 编程的下一个分水岭不是模型又多强，而是项目能不能把自己的上下文稳定地交给模型。AGENTS.md 是我目前找到的最顺手的那把钥匙：它让记忆从玄学变成了工程，从对话里的一次性交代变成了仓库里的基础设施。如果你也在天天跟 AI 反复解释项目规则，不妨今晚就把根目录那个文件建出来，先写三行：技术栈、常用命令、最容易踩的坑。剩下的，等踩过坑再慢慢补。