企业官网建设流程全解析

最近复盘了几个用 AI 辅助开发的真实项目，我发现一个特别显著的变化：判断一个 AI 编程助手“好不好用”，不再是看它回答得有多快、代码写得有多长，而是看它“记不记得住事”。同样的项目、同一套代码，有的人用 AI 像是在指挥一个随时待命的老同事，有的人用 AI 却像每天在面试新实习生。差别不在模型本身，而在你有没有给模型搭好一套Memory 工程体系。

这个标题——AI 编程范式转换与 Memory 工程：从无状态模型到 AGENTS.md 声明式配置——说的就是这件事。过去咱们面对的是无状态模型，每一次调用都是一次“失忆后的重新开始”；现在越来越多的团队转向AGENTS.md 声明式配置，把项目规则、代码习惯、任务背景固化下来，让 AI 一进场就自带项目记忆。这篇博文会从无状态的问题根源讲起，把记忆分类、AGENTS.md 的写法、动态记忆补充和常见坑都过一遍，适合正在用 AI 辅助开发、又觉得 AI“不够顺手”的工程师。

1. 为什么 AI 编程助手换个场景就像换了个人

1.1 无状态模型的本质：每次对话都像新员工入职

先说一个最基本的背景知识：目前绝大部分大语言模型本身是没有记忆的。你调用一次接口，模型就针对这一次输入做一次推理。所谓的“多轮对话”，底层实现其实是把前面所有消息都重新塞进请求里发给模型。模型并没有一个“脑子”在后台帮你存着历史，它只是每轮都拿到一份越来越长的聊天记录。

这种行为放到编程场景里非常致命。假设今天你让 AI 给你写一个订单导出功能，第一轮它写得还不错，你告诉它“导出时金额要四舍五入保留两位小数、字段顺序按表格第一行来”。这轮对话里它懂了，但一旦你新建对话或者切换任务，它立刻变成一张白纸。更麻烦的是，在真实项目里，AI 需要知道的远不止当前功能，还包括：项目用的是什么框架、目录结构长什么样、有没有现成的工具函数、代码风格是分号派还是无分号派、测试跑起来要多久、哪些文件属于边界不能乱动。

没有记忆机制的时候，AI 就像一个每次上岗都被重新介绍一遍的新员工。新员工本身能力不差，但你每次都要花大量时间给它讲团队规矩，而且讲漏一点它就会犯错。这也是很多人在小型 demo 上用 AI 觉得“哇，好强”，一放到真实项目里就觉得“这玩意儿怎么这么蠢”的根本原因。模型没问题，记忆缺失才是问题。

1.2 靠“现场喂资料”解决记忆，为什么越喂越累

既然模型不记得，那咱们自己帮它记。最早大家用的土办法，就是把项目背景复制粘贴到聊天框里。比如把 README 粘进去，把 package.json 粘进去，把某个模块的代码片段粘进去，然后再开始问问题。

这个办法在小项目里确实有效，我早期也是这么干的。但用着用着，问题就全浮出来了。

第一是上下文窗口有限。你可以把模型的工作记忆想象成一张白纸，你贴的资料越多，纸上留给推理的空间就越少。硬是把一堆文档塞进去，最后模型回答到一半甚至会出现“忘记你最初问题是什么”的情况。第二是每次粘贴成本太高。你不可能每天都把整个项目文档重新复制一遍。项目一大，关键信息根本来不及贴，而且贴的时候很容易贴错版本，AI 拿着一份过期目录结构跟你分析得头头是道，实际上整个模块早就重构了。

第三点最反直觉——给得越多，模型反而越容易走神。模型从一大段材料里提取有效信息的能力，并不像搜索引擎那么稳定。材料里无关内容一多，它反而抓不住你真正在意的那个约束。你以为把所有信息都喂进去就万事大吉，实际上把重要的规则淹没在了噪声里。这也就是为什么单纯依赖“现场投喂”的路线，走得越远越痛苦。你不能把它当成可持续的工程方案，只能算是应急对策。

1.3 从 Prompt 工程到 Memory 工程：一次被忽视的范式转移

既然“现场喂资料”不是长久之计，那大家自然就开始想：能不能让模型每次进入项目时，自动获得一套稳定、可复用、可维护的上下文？这一个想法，本质上就是把注意力从Prompt 工程转向了Memory 工程。

过去我们讲 Prompt 工程，核心关注的是“怎么把一句话说清楚”，比如加系统提示、给角色设定、给 few-shot 示例，目标是把单次对话的效果调到最佳。这套方法在问答场景很有用，但在编程协作场景里，它有一个明显短板：你每次都在从零解释，换场景就得重新设计 prompt，而且 prompt 写得再漂亮，模型也无法真正了解你项目的独特历史。

Memory 工程则换了一个提问方式：把“如何让回答更好”变成“如何让模型在回答前已经知道该知道的”。它关注的不是一次对话，而是跨对话、跨任务、长期可复用的上下文管理。具体到实现端，就是先定义好哪些记忆必须常驻，哪些记忆按需检索，哪些知识可以沉淀到文件里让模型随时回读。

AGENTS.md 就是这一波范式转换里最典型的落地载体。它把原来“每次和 AI 啰嗦一遍的东西”沉淀成一份声明式配置文件，让 AI 在工作开始前先读取它，就像员工第一天入职时先读《员工手册》。这份文件不是给人看的 README，而是给智能体看的项目记忆底座。理解了这条主线，后面所有细节其实都是在回答同一个问题：怎么让 AI 拥有真正稳定的项目记忆。

2. Memory 工程入门：先给记忆分个类

2.1 工作记忆、场景记忆、长期记忆，各管各的事

Memory 工程听起来玄乎，其实拿到编程场景里，完全可以拆成三类我们都很熟悉的东西。

第一类是工作记忆，对应的是当前对话里的临时状态。比如你正在让 AI 改一个函数，刚刚讨论过“这个函数需要兼容空列表”，这类信息只需要在当前对话里存活就够了，不需要写进任何文件。实现工作记忆靠的是对话管理、摘要压缩这些技巧，不是 AGENTS.md 的职责。

第二类是场景记忆，对应的是“这个项目本身”的上下文。技术栈、目录结构、命名规范、测试命令、常用脚本、哪些模块是核心、哪些代码不许碰，这些内容几乎每次任务都会用到，而且与项目强相关。AGENTS.md 主要就是管这一层记忆，它会把项目里相对稳定的规则固化下来。

第三类是长期记忆，对应的是跨项目的通用知识与团队历史决策。比如“这个团队所有项目都不写分号”“接口错误码要统一以 E 开头”这类约定，或者“三个月前我们决定用方案 A 而不是方案 B，因为 B 的性能瓶颈暂时无法接受”这类架构决策。长期记忆通常由全局规则文件、架构决策记录、变更日志来管理。

很多人的失败在于把三类记忆混在一起，一股脑塞给 AI。结果就是：全局规则、项目规则、临时要求互相冲突，模型不知道该听哪条。做 Memory 工程的第一步，就是分清哪些记忆放哪一层。放对了，AI 才能在不同粒度上快速加载。

2.2 记忆不是堆越多越好：上下文窗口里的注意力稀释困局

很多人会有一种错觉：记忆工程嘛，就是把所有信息都塞给模型，塞得越多它越懂我。真这么干，你会立刻踩到第二个大坑——注意力稀释。

这里有个非常反直觉的细节：模型的上下文窗口虽然在不断扩大，但模型对“埋在长文本中间的信息”的利用率并没有同比例提高。你给它两万字资料，它可能只对开头和结尾印象最深，中间部分很容易被忽略。你把重要的记忆放在一大段文档的中间，它可能根本没读进去。

我后来养成了一个习惯：核心规则必须放在文档前面，越重要、越靠前；次要细节要么放靠后、要么放到附录里供按需查阅。记忆工程的关键指标，不是“我喂了多少 token”，而是“模型实际能稳定运用多少规则”。与其堆砌一份冗长的项目说明，不如写一份精炼的“项目速查卡”，用最少的篇幅覆盖最高频的信息。真正做到让关键记忆出现在关键位置。

2.3 动态记忆与静态记忆：规则文本和运行状态要分清

再往深一层看，记忆还可以分成静态记忆和动态记忆两类。

静态记忆就是那些相对稳定、不太会变的内容。项目是什么、用什么框架、代码风格如何、测试怎么跑，这些在一个迭代周期内基本不会天天变。静态记忆适合用文件承载，比如 AGENTS.md、全局规则文件，甚至可以放进 Git 里做版本管理。文件的好处是稳定、可追溯、可评审，团队里任何一个人改了规则，其他人拉一次代码就能同步。

动态记忆则对应项目运行和开发过程中不断变化的状态。比如：这次迭代做到哪一步了、某个功能为什么临时改成这样、上次踩过的坑是什么、当前分支还有哪些未完成的改动。动态记忆需要被频繁写入和更新，如果硬塞进静态文件，文件会迅速腐化，里面全是过时信息。所以动态记忆通常交给变更日志、架构决策记录、任务清单这类文档，甚至让 AI 在每次任务结束时自动把结论回写进去。

静态记忆解决“AI 懂不懂规矩”，动态记忆解决“AI 清不清楚现状”。两者互补，缺了哪个都别扭。也只有分清这两类，你才知道 AGENTS.md 里该写什么、不该写什么，而不是把项目里所有发生过的事都塞进去。

3. AGENTS.md：把项目记忆写成一份声明式配置

3.1 AGENTS.md 到底是什么东西

简单说，AGENTS.md 是一份放在项目根目录（或者指定目录里）的 Markdown 文件，专门写给 AI 智能体看。很多主流的 AI 编程助手在进入项目时，会先扫描并读取这份文件，把它当成自己的“系统提示词”和“项目工作手册”。对智能体来说，它的作用比 README 更直接：README 是给人看的项目介绍，AGENTS.md 是给 AI 看的行动准则。

它为什么叫“声明式配置”？因为你要做的事情不是写一段命令让 AI 去执行，而是声明“这个项目有什么、约定是什么、不许做什么”，AI 读到之后会在后续所有任务中自觉地遵守。这跟我们熟悉的声明式运维、声明式 UI 逻辑很像：你描述目标状态，而不是一步一步控制过程。

在实际使用中，AGENTS.md 可以很简单，也可以很庞大，取决于项目的复杂度。一个小工具项目可能五六行就够了，一个多人维护的中大型项目可能需要拆成“根目录总则 + 子模块局部规则”的结构。关键在于它承载的是“团队与 AI 之间的长期契约”，一旦建立，你就可以在每次开发任务里少费很多口舌。

3.2 一份合格 AGENTS.md 的结构与写法

我自己维护了好几个带有 AGENTS.md 的项目，经过反复删改，最后沉淀下来一个比较顺手的文件骨架，核心段落大概是下面这七个。

第一段是项目概览。用三五句话说清项目是什么、核心目标是什么、主要模块怎么划分。这段不用长，但一定要准确，它的作用是让 AI 在第一次进入项目时迅速建立全局地图。

第二段是常用命令。包括启动、测试、构建、代码检查的具体命令。这里有个很容易被忽视的经验：命令必须写成 AI 可以直接复制执行的版本。如果你只写“跑测试”，AI 可能会猜错命令，然后跑到一半报错，又花额外时间解释。直接把命令和用途写成表格或清单，是最省事的。

第三段是技术栈与约束。写清楚项目基于什么语言、什么框架，允许用什么库、禁止用什么库。尤其要把“技术债边界”写出来，比如“现有模块仍然用旧版 ORM，新增代码不要迁移新框架”，否则 AI 很容易自作主张给你升级依赖。

第四段是编码风格。命名规范、格式化工具、注释习惯、错误处理风格，越具体越好。比如“错误信息统一用中文”“接口返回格式必须是 { code, message, data }”这类内容。

第五段是任务流程。这部分是给 AI 立规矩：它接手一个任务时，应该先做什么、再做什么。比如“改代码前先读对应测试文件”“改完后必须跑一次 lint 和全量单测”“提交前不允许删除测试用例”。

第六段是边界与禁忌。这是最容易出效果的段落。比如“不要修改 generated 目录下的代码”“不要动数据库迁移脚本”“遇到兼容性问题先问人，不要自己改公共模块”。AI 在边界内干活，出问题的概率会断崖式下降。

第七段是引用入口。如果你的项目里还有更详细的架构文档、接口设计文档、ADR 记录，就在 AGENTS.md 里给出路径。AI 读到“需要更详细的信息时，请看 docs/architecture.md”，就会按需去读取，而不是只依赖当前片段。

整个文件写下来，应该像一个“工牌加速查卡”，而不是一本百科全书。核心目的永远是让 AI 在最短时间内理解最关键的约定。

3.3 分层配置策略：全局规则、项目规则、局部规则怎么叠

AGENTS.md 不是孤零零存在的，它通常要和另外两层配置叠加使用。

第一层是全局规则，放在用户主目录里，适用于该用户所有项目。典型内容是你的个人编程偏好、通用沟通方式、不希望 AI 做的事。比如“所有生成的代码必须附带注释”“不回答与编程无关的问题”这类。

第二层是项目规则，就是根目录的 AGENTS.md，适用于当前仓库的所有任务。内容就是我们上面说的那七段。

第三层是局部规则，放在子目录里，适用于特定模块。比如你的项目里有个 legacy 目录，里面全是很老的代码，你就可以在该目录下放一个局部的规则文件，写明“此目录代码禁止重构，只能做最小修复”，这样 AI 在该目录里干活时就会收到更细的约束。

这三层不是平等的，加载顺序一般是：全局规则先进入上下文，项目规则再叠加，局部规则最后覆盖。实际执行中，越具体的规则优先级越高。所以你做 Memory 工程，最好不要把所有东西全塞进根目录的一个大文件里，而是拆开管理。全局管通识、根目录管项目共性、子目录管模块个性。这样每个文件都能保持短小精悍，AI 读取负担也小，长期维护成本还低。

4. 实操：从无状态工作流升级为记忆驱动工作流

4.1 改造前的基线：先量化“现在的 AI 协作有多健忘”

在你动手写 AGENTS.md 之前，我建议你先花半小时做一次“健忘度体检”。不然你改了半天，也说不清楚到底有没有变好。

我自己常用的自查清单是这样的：

• AI 是否反复问你项目里已经写清楚的问题，比如“用什么框架”“测试命令是什么”？
• AI 生成的代码风格，是否经常和项目现有代码不一致？
• AI 是否经常建议你修改那些不该动的文件？
• AI 是否会在任务中途忘记你开头提的约束？
• 切换一个新对话、或者隔一天再来继续工作，AI 是不是像失忆了一样？
• 你的提示词里，是否每次都要复制一大段项目背景？

每一条，如果符合就记 1 分，不符合记 0 分。如果总分超过 2 分，说明你的工作流确实处于“无状态 + 临时投喂”的阶段，非常值得引入 AGENTS.md 来打底。

这步不是为了凑仪式感，而是给改造前后留一个可对比的基线。很多人在引入配置文件后觉得“好像顺了一点”，但又说不出顺在哪。有了基线，你就能精确看到改进点：比如“AI 再也没问过测试命令”“没再动过 generated 目录”。

4.2 落地步骤：从最小可用 AGENTS.md 开始

第一次写 AGENTS.md，千万别一上来就追求大而全。我见过不少人花一整天写出一份两千行的项目规则，结果 AI 根本不读后面的部分，而且规则之间互相冲突，维护者自己也改不动。正确策略是从最小可用版本开始，先跑起来，再迭代。

我的做法是分四步走。

第一步，只写“项目概览 + 常用命令 + 红线禁忌”。这三块就能覆盖大部分“AI 犯低级错误”的场景，写起来也快，100 行以内就能搞定。第二步，让 AI 在每个任务开始时明确读取这份文件，观察它的行为有没有立即变化。如果有些规则没生效，别急着加内容，先排查是不是文件路径不对、是不是被其他指令覆盖了。

第三步，把 AI 反复问你的问题整理成规则写进去。比如它每次都要问“这个项目用什么包管理器”，那你就直接把“使用 pnpm，其他管理器一律不认”写进命令段。第四步，把 AI 反复犯的错整理成禁忌写进去。比如它总是试图修改公共工具函数，那你就写明“改变公共函数必须先在 AGENTS.md 中标注影响面”。整个过程保持小而稳，每加一条规则都要想清楚“这条能避免什么实际错误”，而不是为了显得专业而堆砌。

4.3 一个完整的示例：后端项目记忆文件长什么样

光讲理论不如给一份示例。下面是我整理的一份虚构后端项目 AGENTS.md，你可以把它当成模板来裁剪。

# AGENTS.md - 订单管理服务 ## 项目概览 这是一个内部订单管理服务，提供订单创建、查询、导出、对账四个核心模块。 代码仓库中包含 admin 后台 API 和 worker 异步任务两部分。 目录结构： - app/ 核心业务逻辑 - app/api/ HTTP 处理器 - app/services/ 领域服务层 - app/repositories/ 数据访问层 - worker/ 异步任务（订单状态流转、报表生成） - migrations/ 数据库迁移脚本 ## 常用命令 - 安装依赖：pnpm install - 本地开发：pnpm dev - 运行测试：pnpm test - 单测某个文件：pnpm test -- run app/services/order.spec.ts - 代码检查：pnpm lint - 类型检查：pnpm typecheck - 构建：pnpm build ## 技术栈与约束 - 运行时：Node.js 20，使用 TypeScript。 - 框架：Fastify，不要引入 Express 或 NestJS。 - 数据库：PostgreSQL，通过迁移脚本管理表结构。 - 消息队列：RabbitMQ，worker 模块消费队列消息。 - 禁止在 API 层直接操作数据库，必须经过 service 层。 - 禁止在已有代码中使用 any，新代码必须显式标注类型。 ## 编码风格 - 文件名统一使用 kebab-case，比如 order-service.ts。 - 接口返回格式统一为 { code, message, data }，code 为数字，0 表示成功。 - 错误处理：自定义业务异常类，由全局错误中间件统一捕获，不要散落 try/catch。 - 注释只写“为什么”，不写“是什么”，因为代码本身已经能表达是什么。 ## 任务流程 1. 开始任务前，先读相关模块的现有代码和测试文件。 2. 修改前先搜索是否已有同名工具函数，避免重复封装。 3. 每完成一个功能，必须补一个对应测试用例。 4. 提交前必须依次跑 lint、typecheck、test，全部通过才能结束任务。 ## 边界与禁忌 - 不要修改 migrations/ 下已生成的历史迁移文件。 - 不要改动 worker 里与其他服务共用的消息协议字段。 - 不要直接修改 generated/ 目录下的代码，如需要调整生成逻辑，请先说明目标。 - 遇到涉及公共模块的改动，不要直接实施，先向使用者说明影响范围。 ## 引用入口 - 架构设计说明：docs/architecture.md - 接口协议文档：docs/api-protocol.md - 历史决策记录：docs/adr/

你可能发现了，这份文件里的很多内容并不深奥，但每一句都是从真实踩坑里提炼出来的。比如“不要改动历史迁移文件”，就是因为 AI 很容易在改字段时顺手改了旧迁移文件，导致别人从零建库时直接挂掉。这类边界写得越明确，AI 的自由发挥空间就越小，项目的安全性就越高。

4.4 如何让 AI 真的读进脑子里：上下文注入与内置加载

文件写好了，你肯定还会碰到另一个问题：AI 不读怎么办？

不同的 AI 编程工具对项目内指令文件的加载方式不太一样。有些工具会自动扫描项目根目录，识别到 AGENTS.md 后会自动把它放进去；有些工具则需要你手动引用；还有一些工具内置了其他命名的项目记忆文件。所以第一步是确认你用的工具到底认哪个文件名、放在哪个路径。路径和命名错了，后面全白搭。

如果工具不支持自动加载，我还有两个土办法。一是在每次任务的初始指令里明确写一句“开始工作前，先读取项目根目录的 AGENTS.md，并严格遵循其中的约束”，把它当成每次对话的开场白。二是把 AGENTS.md 的内容封装成一个系统提示片段，在新建对话时直接粘贴到上下文的开头。这样虽然每次还要贴一次，但贴的是同一份稳定内容，而不是每次临场发挥，维护成本和出错率都会低很多。

另外一个容易被忽略的点：就算工具支持自动加载，它也只是把 AGENTS.md 放进了上下文，并不代表模型真的会“优先执行”里面的规则。如果用户的即时指令和 AGENTS.md 冲突，模型很可能选择听用户的。所以在实际协作中，我会习惯性地在关键任务里加一句“以 AGENTS.md 里的边界为准”，帮助模型在冲突时做出正确选择。

5. 动态记忆补齐短板：仅有配置文件还不够

5.1 动态记忆三件套：变更日志、架构决策记录、任务台账

AGENTS.md 解决的是“项目是什么、规则是什么”，但它回答不了“现在进行到哪了”。要补齐这块，我建议你在项目里建立三份动态记忆文档。

第一份是CHANGELOG（变更日志）。记录每个版本的显著变更。AI 在接手任务时，读到最近的变更日志，就能理解当前代码为什么会变成这个样子，避免“看到某段奇怪代码就想重构，其实人家是有意为之”。

第二份是ADR（架构决策记录）。记录关键的技术选型和设计决策，以及决策的背景。比如“为什么从单体拆成两个服务”“为什么选 RabbitMQ 而不是 Kafka”。这类信息通常不会出现在代码里，但 AI 做后续修改时会用到。没有 ADR，AI 很可能会在“旧决策”上作出“看起来更优但违背初衷”的新改动。

第三份是任务台账。可以简单理解成一个 TODO 进度表，记录当前迭代的任务状态。比如“用户导出功能已完成，对账报表仍在开发”“已知问题：大订单导出偶发超时，待排查”。问题是 AI 每次进项目时，能快速续上之前的工作，而不是每次都从零探索一遍代码库。

这三份文档和 AGENTS.md 配合起来，就形成了一个比较完整的记忆体系：AGENTS.md 管稳定规则，CHANGELOG 管时间线，ADR 管决策，任务台账管现状。

5.2 存储选型：普通文件、结构化文档、向量索引，怎么选

Dynamic memory 存哪？很多新人一上来就考虑向量数据库、知识库，我觉得有点过度设计了。先盘一下四种常见存储形态的差异，你就有判断了。

第一种是普通 Markdown/文本文档。优点是没有学习成本、可以直接用 Git 管理、人类和 AI 都能读，非常适合团队规模不大、文档更新频率不高的场景。第二种是结构化文档（YAML、JSON）。优点是可以被程序解析，方便自动化流程提取状态，适合任务台账这种需要定期更新的内容。第三种是代码领域里的常量配置。比如把项目约束直接写进配置里，让 AI 在读取代码时自然看到，不过这种做法一般只能用于技术规则，表达不了复杂上下文。

第四种是向量索引/向量知识库。适合超大规模项目里做语义检索，AI 可以根据问题去检索相关记忆片段。但它需要构建和维护索引，资料更新后还得重新同步，很多小团队根本没有人力持续维护。

我的建议很简单：先用普通文件撑住，等项目的记忆量级到了“文件多到连人眼都找不到重点”的时候，再考虑向量化检索。绝大多数项目，AGENTS.md、ADR、CHANGELOG 三个文件夹在一起，就已经能覆盖八成需求了。Memory 工程的价值在于体系，而不在于堆砌基础设施。

5.3 把记忆工程做成项目里的“第二文档体系”

如果你把记忆工程真正推行下去，你的项目里慢慢会形成一套“第二文档体系”。

第一套文档体系面向人类，包括 README、架构说明、使用手册，核心是让新人快速理解项目。第二套文档体系面向 AI，核心是 AGENTS.md + 动态记忆文件，核心是让 AI 在每次任务开始前获得正确的上下文。它们之间当然有重叠，但关注点完全不同。README 里可能写“这是一个订单管理服务，它解决了订单全生命周期的问题”，而 AGENTS.md 里写“订单状态字段的合法取值是这些，流转必须走状态机，不允许直接改库”。

为了不把两套文档搞混，我建议在项目里统一一下放置位置。比如根目录放 AGENTS.md，docs/ 下面建一个 memory/ 子目录，放 CHANGELOG、ADR、任务台账。然后在 AGENTS.md 的“引用入口”里，把这几份动态记忆文件的路径写清楚，这样 AI 才会知道需要时该去哪里查。

再往深一层，这套系统还要形成闭环：每次任务结束时，让 AI 把变更摘要追加到 CHANGELOG，把决策理由追加到 ADR，把遗留问题更新到任务台账。一开始你可能会觉得麻烦，但坚持几周就会发现，AI 的跨会话记忆能力会明显提升。它不再是一个“每次重新入职的新员工”，而是“有交接文档的连续劳动者”。

6. 踩坑与排查：记忆工程实战中的高频问题

6.1 配置不生效，规则被忽略

这是用 AGENTS.md 最常遇到的第一个问题。你辛辛苦苦写好了规则，结果 AI 还是我行我素。我排查这类问题，通常会按下面几个顺序检查。

先看文件名和路径。很多工具只认特定名字的文件，比如 AGENTS.md，如果你写成 agents.md 或者放到了子目录里，加载逻辑可能就不认了。再看工具是否支持自动加载，如果不支持，你需要在任务指令里手动标明。再看规则内容是否过长。一条规则埋在一千五百行文件的中后部，AI 很容易漏掉。重要的规则靠前放，规则总数控制在 30 条以内。

还有一个隐蔽原因：全局规则和项目规则冲突。比如你在全局层面写了“每次回答都要附上完整代码”，项目规则却要求“只输出 diff 片段”。当两层规则存在张力时，模型的行为可能变得极其不稳定。排查办法是，先在项目层面只留一条最简单的规则，比如“所有回复必须以中文的好的开头”，看 AI 是否执行。如果执行，说明加载链路没问题；如果不执行，那就回到文件路径和命名上继续查。

6.2 上下文被新指令挤爆，记忆被冲刷

即使 AGENTS.md 成功加载，你还会遇到另一种更微妙的情况：对话久了之后，模型开始“遗忘”文件里的规则。这不是规则没加载，而是上下文被后续内容淹没了。

大模型的注意力机制有一个特点：对上下文中间部分的关注度往往低于开头和结尾。如果你在处理一个非常长且复杂的任务，后续的大量代码片段、错误输出、日志会不断推挤前面的 AGENTS.md 内容，规则本身还在上下文里，但被淹没在其他信息中间，模型实际上已经很难有效调用它们了。

解决思路是把“记忆源”从对话历史挪到项目文件里。当对话变长时，不要继续在当前会话里硬顶，而是开启新对话，然后让 AI 重新读取 AGENTS.md 和动态记忆文件。关键规则始终存在于文件里，聊天历史只是临时工作区。另外，如果你发现哪条规则特别重要，可以在中途任务指令里再强调一次，比如“还是按 AGENTS.md 里提的，不要动 migrations 目录”，这相当于把一个重要记忆从中间位置重新提回注意力焦点。

6.3 维护成本失控：记忆腐化和过度设计

AGENTS.md 一旦进入维护期，另一个方向的风险又来了：文件膨胀和规则腐化。

文件膨胀的后果很直观，规则太多太长，AI 每次读取都要消耗大量 token，而且它只对开头的几条规则反应最灵敏，后面的规则边际效果越来越差。我自己控制过一个经验阈值：单个记忆文件最好不要超过三百到五百行。超过这个规模，就得考虑把内容拆到子目录局部规则里，或者把细节挪到“引用入口”指向的补充文档里，让 AI 按需读取，而不是一次性全塞进去。

规则腐化则更隐蔽。项目在演进，有些历史约束可能已经不再适用，但没人清理，AGENTS.md 里还留着“禁止使用新版 ORM 的语法”，而实际上团队上个季度已经全面迁移到新 ORM 了。腐化的规则比没有规则更糟糕，AI 会一本正经地遵守一项已经过时的约定，导致代码风格和现状脱节。所以建议每两到四周做一次规则审计，让团队成员过一遍 AGENTS.md，专门删除“我们早就不是这样干的了”的条目。记忆工程里，遗忘和记住同样重要。

6.4 几个非常实用的小技巧

最后分享几个我在实践中越用越顺的小技巧，都是常规文档里不会写、但真实场景经常救命的东西。

第一个：把“禁止项”写成“触发条件 + 处理方式”的结构。比如“当遇到 public 目录下代码与设计稿不一致时，不要直接改，先和对应模块负责人确认”。只写“不要改 public 目录”，AI 可能理解成“永远不碰它”，遇到其实应该修的情况它也缩手了。写清楚触发条件和替代动作，AI 的行为才会符合你的真实意图。

第二个：用自检清单让 AI 收尾。在 AGENTS.md 里加一个“提交前检查清单”，列出“是否跑过 lint？是否补充测试？是否更新 CHANGELOG？是否检查兼容性？”。AI 在完成任务时会照着清单逐项确认，这比在聊天里一遍遍催它有效得多。

第三个：让 AI 反向总结项目上下文。每隔一段时间，把项目里的关键文件和最近的提交记录丢给 AI，让它生成一份“我目前对项目的理解”，然后你和它对一遍。它能帮你发现 AGENTS.md 里没覆盖但其实很重要的隐性约定，顺便也把记忆文件更新得更完整。

第四个：给 AI 的规则编号。在 AGENTS.md 里，每条规则都编号，比如 R1、R2、R3。之后任务里需要让 AI 优先执行某一条时，直接说“按 R3 处理”就可以了，比复述一遍原文靠谱得多，也不容易导致上下文里的理解偏差。

我个人在实际操作中的体会是，AI 编程好不好用，很多时候不是模型的智商问题，而是你给它的“记忆工程”有没有搭起来。从我自己的项目经验看，AGENTS.md 从三行备忘录逐步长到几十行的过程中，AI 生成的代码一次通过率肉眼可见地提高了。最让我惊讶的不是它记住了命令，而是它会在改动公共模块时主动问一句“这个变更需要同步更新 ADR 吗”，那种协作感，和以前每次像面试新实习生完全不同。

如果你也被“AI 总是健忘”困扰，建议别急着继续在聊天框里堆提示词，先建一个最小可用的 AGENTS.md，配上变更日志和任务台账，跑上一周。范式转换的实感，一定会比你想象中来得更直接。