从无状态到有状态：AGENTS.md 如何重塑 AI 编程记忆工程

1. 从无状态到有状态：AI 编程范式转换的底层逻辑

1.1 为什么无状态模型是当前 AI 编程的最大瓶颈

用过 AI 辅助编程的人都有一个共同感受：每次开新对话，就像换了一个失忆的搭档。你昨天刚跟它讲清楚项目用的是什么框架、目录结构怎么组织、命名规范是什么，今天开个新窗口，它又变回一张白纸，你得从头再讲一遍。这不是模型不够聪明，而是当前主流大模型 API 的调用方式决定的——每次请求都是独立的，模型本身不保存任何跨会话的状态。

这个特性在简单场景下问题不大，比如你只是让它写一个排序算法、解释一段正则表达式，一次对话就能搞定。但一旦进入真实项目开发，问题就暴露了。一个中型项目动辄几十个模块、上百个文件，涉及特定的架构约定、错误处理模式、日志规范、测试策略。你每次让 AI 帮你写一个新模块，都得把相关的上下文重新喂一遍，token 消耗巨大不说，还经常因为上下文窗口限制而丢三落四。

我自己的体验是，在一个前端项目里让 AI 帮忙写一个表单组件，它默认用了受控组件写法，但我们项目统一用的是非受控加 ref 的方案。我没提，它就按自己的习惯来。等我发现不对再纠正，它改了，但下一个组件它又忘了。这种反复纠正的成本，累积起来非常可观。

所以核心矛盾在于：AI 编程的效率瓶颈已经从“模型能力不足”转移到了“上下文管理低效”。模型本身能写出高质量代码，但它不知道你的项目长什么样、有什么约定、之前做过什么决策。每次都要靠人肉去补全这些信息，本质上是在用人的记忆力弥补模型的失忆。

1.2 Memory 工程要解决的核心问题到底是什么

Memory 工程这个词听起来很玄，但拆开看其实很朴素：让 AI 在多次交互之间保持对项目上下文的一致认知。它要解决的不是“让模型更聪明”，而是“让模型更懂你”。

具体来说，Memory 工程要处理三类信息。第一类是静态约定，比如项目的技术栈、目录结构、代码风格、命名规范，这些在项目生命周期内基本不变。第二类是动态状态，比如当前正在开发哪个功能、上次对话中做了什么决策、有哪些待办事项，这些会随着开发进度变化。第三类是历史决策记录，比如为什么选了这个方案而不是那个、踩过哪些坑、有哪些已知问题，这些是项目演进过程中积累的隐性知识。

传统做法是把这些信息塞进每次请求的 prompt 里，但这样做有几个致命问题。一是 token 成本随信息量线性增长，二是上下文窗口有硬上限，三是信息多了之后模型反而抓不住重点，容易“迷失在中间”。所以 Memory 工程的核心挑战不是“能不能存”，而是“怎么存、怎么取、怎么让模型在需要的时候恰好看到需要的信息”。

这就引出了声明式配置的思路。与其每次动态拼接上下文，不如把项目的核心约定写成一个结构化的配置文件，让 AI 在每次对话开始时自动加载。这个配置文件就是 AGENTS.md 这类方案的雏形。

1.3 声明式配置为什么比命令式拼接更适合 AI 编程

命令式拼接的思路是：每次请求前，用代码动态组装上下文，把相关的文件内容、历史记录、约定说明拼成一个长字符串塞给模型。这种方式灵活但脆弱，因为拼接逻辑本身需要维护，而且很难保证每次都能拼出正确的上下文。

声明式配置的思路是：把“AI 需要知道什么”写成一个静态文件，放在项目根目录，AI 工具在启动时自动读取。这个文件用自然语言描述项目的关键信息，不需要写代码来解析，模型自己就能理解。

打个比方，命令式拼接像是你每次出门前都要手动检查钱包、钥匙、手机带没带；声明式配置像是你在门口贴了一张清单，出门前看一眼就行。前者依赖你的记忆力和执行力，后者依赖清单本身的完整性。对于 AI 编程来说，清单的维护成本远低于每次手动拼接，而且不容易遗漏。

更重要的是，声明式配置让“项目知识”变成了一个可版本控制的文件。你可以把它提交到 Git 仓库，团队成员共享同一份配置，新人加入时 AI 也能立刻获得项目上下文。这就把原本散落在各人脑子里的隐性知识，变成了团队共有的显性资产。

2. AGENTS.md 的核心设计：一份文件如何承载项目记忆

2.1 AGENTS.md 应该包含哪些内容

AGENTS.md 不是随便写写就行的，它的内容质量直接决定了 AI 对项目的理解程度。根据我的实践经验，一份有效的 AGENTS.md 至少应该覆盖以下几个维度。

项目概览是必须放在最前面的。用三五句话说明这个项目是做什么的、面向什么用户、核心功能有哪些。这部分不需要太详细，目的是让 AI 建立一个大致的认知框架，知道自己在什么语境下工作。

技术栈与工具链要列清楚。用什么语言、什么框架、什么构建工具、什么测试框架、什么包管理器。这些信息看起来基础，但 AI 如果不知道，就会按自己的默认习惯来。比如你不说用的是 pnpm，它可能给你生成 npm 的命令；你不说用的是 Vitest，它可能给你写 Jest 的测试。

目录结构说明是很多人容易忽略但极其重要的一部分。不需要列出每个文件，但要说明主要目录的职责。比如src/components放通用组件、src/features放业务模块、src/lib放工具函数。这样 AI 在新建文件时就知道该放哪里，而不是随便找个地方塞进去。

代码规范与约定要写得具体。不要只说“遵循 ESLint 规则”，而要说明关键约定，比如“组件文件用 PascalCase 命名”、“工具函数用 camelCase”、“常量用 UPPER_SNAKE_CASE”、“每个导出函数必须有 JSDoc 注释”。越具体，AI 越不容易跑偏。

常用命令要列出来。开发服务器怎么启动、测试怎么跑、构建怎么执行、代码检查怎么做。这些命令 AI 在需要验证自己的改动时会用到，提前告诉它能省很多来回。

已知问题与注意事项是加分项。比如“这个模块依赖一个尚未稳定的第三方库，升级时需谨慎”、“这个目录下的文件不要手动修改，由代码生成”、“测试环境需要先启动本地数据库”。这些信息能帮 AI 避开很多坑。

2.2 怎么写才能让 AI 真正读懂

写 AGENTS.md 最大的误区是把它写成给人看的文档。人看文档可以跳读、可以脑补、可以根据经验填补空白，但 AI 不行。AI 会逐字逐句地理解你写的内容，你写得模糊，它就理解得模糊。

第一个原则是具体优于抽象。不要写“代码要整洁”，要写“函数不超过 50 行，参数不超过 4 个，嵌套层级不超过 3 层”。不要写“遵循项目风格”，要写“参考src/utils/format.ts中的写法”。具体的规则 AI 能执行，抽象的规则 AI 只能猜。

第二个原则是正面描述优于负面禁止。尽量告诉 AI“应该怎么做”，而不是“不要怎么做”。因为负面指令需要 AI 先理解什么是不该做的，再推导出该做什么，多了一步推理，容易出错。比如与其说“不要用 any 类型”，不如说“所有变量和函数返回值必须有明确的类型标注”。

第三个原则是结构化优于流水账。用标题分层、用列表罗列、用代码块展示示例。AI 对结构化信息的解析能力远强于大段散文。一份好的 AGENTS.md 应该像一份精心组织的 checklist，而不是一篇随笔。

第四个原则是控制篇幅。AGENTS.md 不是越长越好。太长了会占用宝贵的上下文窗口，而且模型在长文本中容易丢失重点。我的经验是控制在 2000 字以内，把最关键的信息写进去，次要信息可以放在单独的文档里按需引用。

2.3 一个可参考的 AGENTS.md 模板结构

下面是我在实际项目中反复打磨出来的一个模板结构，你可以直接拿去改。

# 项目名称 ## 项目概览 一句话说明项目定位，两三句话补充核心功能和目标用户。 ## 技术栈 - 语言：TypeScript 5.x - 框架：React 18 + Vite - 状态管理：Zustand - 样式：Tailwind CSS - 测试：Vitest + Testing Library - 包管理：pnpm ## 目录结构 - `src/components/`：通用 UI 组件，每个组件一个目录 - `src/features/`：业务功能模块，按领域划分 - `src/lib/`：工具函数和第三方库封装 - `src/hooks/`：自定义 React Hooks - `src/types/`：全局类型定义 ## 代码规范 - 组件文件用 PascalCase，工具文件用 camelCase - 每个导出函数必须有 JSDoc 注释 - 优先使用函数式组件和 Hooks - 样式统一用 Tailwind 类名，不写独立 CSS 文件 - 所有异步操作必须有错误处理 ## 常用命令 - 开发：`pnpm dev` - 测试：`pnpm test` - 构建：`pnpm build` - 检查：`pnpm lint` ## 注意事项 - `src/generated/` 下的文件由代码生成，不要手动修改 - 新增依赖前先确认是否已有替代方案 - 提交前必须通过 lint 和测试

这个模板的好处是信息密度高、结构清晰、AI 容易解析。你可以根据项目实际情况增删条目，但建议保持这个骨架。

3. 实操落地：从零搭建一套 Memory 工程工作流

3.1 环境准备与工具选型

要落地这套方案，你需要一个支持读取项目配置文件的 AI 编程工具。目前主流的选择有几类：一类是 IDE 插件形态的，比如在 VS Code 里运行的 AI 助手；一类是命令行形态的，比如在终端里交互的 AI 工具；还有一类是独立编辑器形态的，比如专门为 AI 编程设计的编辑器。

选型的核心考量是是否支持自动读取项目根目录的配置文件。如果不支持，你就得每次手动把配置内容粘贴到对话里，那就失去了声明式配置的意义。我建议优先选择那些明确支持 AGENTS.md 或类似机制的方案，这样配置一次就能长期生效。

除了 AI 工具本身，你还需要一个版本控制工具来管理 AGENTS.md 的变更。Git 是标配，没什么好说的。建议把 AGENTS.md 放在项目根目录，和 README.md 平级，这样既显眼又符合惯例。

另外建议准备一个docs/目录，用来存放更详细的文档。AGENTS.md 只放最核心的约定，详细的架构说明、API 文档、部署流程可以放在docs/下，在 AGENTS.md 里用链接引用。这样既保持了 AGENTS.md 的精简，又不会丢失重要信息。

3.2 第一步：梳理项目现状并提取关键约定

在写 AGENTS.md 之前，先花半小时把项目现状梳理一遍。这一步很多人会跳过，直接开始写，结果写出来的东西要么遗漏关键信息，要么包含大量无关内容。

梳理的方法是：打开项目根目录，从入口文件开始，沿着目录树走一遍。每看到一个目录，问自己三个问题：这个目录是干什么的？AI 在什么情况下会往这里加文件？加文件时有什么约定？把答案记下来。

然后看配置文件。package.json里的 scripts 和 dependencies、tsconfig.json里的编译选项、.eslintrc里的规则、vite.config.ts里的构建配置。这些文件里的信息很多可以直接提炼到 AGENTS.md 里。

接着看代码风格。随便打开几个代表性文件，观察命名习惯、注释风格、错误处理方式、测试写法。把这些观察总结成几条明确的规则。

最后回忆一下过去踩过的坑。有没有因为 AI 不知道某个约定而写错代码的情况？有没有某个模块特别容易出问题？把这些经验也写进去。

3.3 第二步：编写并迭代 AGENTS.md

第一版 AGENTS.md 不需要追求完美，先把能想到的都写进去，然后在实际使用中迭代。我的经验是，第一版写完后，用 AI 做几个真实任务，观察它在哪些地方理解错了、哪些地方需要你额外解释。每次纠正后，把对应的约定补充到 AGENTS.md 里。

迭代的频率建议是：项目初期每周更新一次，稳定后每月更新一次。每次更新不需要大改，补充几条规则、修正几处表述就行。关键是保持这个习惯，让 AGENTS.md 始终反映项目的最新状态。

有一个技巧是：当你发现自己在对话中反复向 AI 解释同一个东西时，就说明这个东西应该写进 AGENTS.md 了。比如你第三次告诉 AI“这个项目的 API 请求都要走src/lib/api.ts里的封装”，那就别再口头说了，写进配置文件。

另一个技巧是：让 AI 帮你写 AGENTS.md。你可以把项目结构贴给 AI，让它根据观察生成一份初稿，然后你再修改。这样能省不少力气，而且 AI 可能会发现一些你忽略的细节。

3.4 第三步：验证配置效果并建立反馈循环

写完 AGENTS.md 后，怎么知道它有没有效果？最直接的验证方法是：开一个新对话，让 AI 做一个需要项目上下文的任务，看它是否需要你额外解释。如果它能直接按你的约定来，说明配置生效了；如果还需要你补充说明，说明配置有遗漏。

我通常会做三个测试。第一个是新建文件测试：让 AI 在指定目录下创建一个新组件，看它是否用了正确的命名、是否放了正确的位置、是否遵循了代码规范。第二个是修改测试：让 AI 修改一个现有函数，看它是否保持了原有的风格、是否更新了相关测试。第三个是查询测试：问 AI 某个功能在哪里实现、某个约定是什么，看它能否从 AGENTS.md 中找到答案。

根据测试结果，把遗漏的约定补进去，把表述不清的地方改清楚。这个过程重复两三轮，AGENTS.md 就基本稳定了。

反馈循环的建立也很重要。建议在团队中指定一个人负责维护 AGENTS.md，其他人发现 AI 理解偏差时，向这个人反馈。或者更简单的方式是：谁发现遗漏谁就补，把 AGENTS.md 当成代码一样对待，发现问题就提 PR 修改。

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

4.1 AGENTS.md 写了但 AI 不遵守怎么办

这是最常见的问题。你明明写了“组件文件用 PascalCase”，AI 还是给你生成了 camelCase 的文件名。遇到这种情况，先别急着怀疑方案本身，按下面的顺序排查。

首先检查文件位置。AGENTS.md 必须放在项目根目录，有些工具只认根目录下的文件，放在子目录里不生效。其次检查文件名。不同工具对配置文件的命名要求不同，有的认 AGENTS.md，有的认 .ai-config，有的认其他名字。确认你用的工具支持哪种命名。

然后检查内容表述。如果规则写得太模糊，AI 可能理解不了。比如“遵循项目风格”这种表述，AI 根本不知道项目风格是什么。改成具体的规则，比如“组件文件用 PascalCase 命名，如UserProfile.tsx”。

还有一个可能是规则之间有冲突。比如你在一处写了“所有文件用 camelCase”，在另一处写了“组件文件用 PascalCase”，AI 就不知道该听哪个。检查一遍有没有互相矛盾的规则，有的话统一掉。

如果以上都没问题，那可能是工具本身对 AGENTS.md 的支持不够好。有些工具只是把文件内容当作普通上下文，不会特别强调。这种情况下，你可以在对话开始时手动提醒一句“请参考 AGENTS.md 中的约定”，效果会好很多。

4.2 项目太大导致 AGENTS.md 写不下怎么办

大型项目的约定确实很多，一份 AGENTS.md 可能装不下。这时候需要分层处理。

核心约定放在根目录的 AGENTS.md 里，比如技术栈、目录结构、代码规范这些全局性的信息。模块特定的约定放在各模块目录下的子配置文件中，比如src/features/payment/AGENTS.md里写支付模块特有的约定。AI 工具在读取时，会先读根目录的，再读当前工作目录的，形成层级化的上下文。

另一种做法是用引用。根目录的 AGENTS.md 只写概览和索引，详细内容放在docs/下的各个文件里，用链接引用。AI 在需要时可以通过读取链接指向的文件来获取详细信息。不过这种方式依赖工具是否支持读取引用文件，不是所有工具都支持。

还有一种做法是精简。很多约定其实可以合并或省略。比如“函数不超过 50 行”和“嵌套不超过 3 层”可以合并成“保持函数简洁，避免过深嵌套”。虽然精确度降低了，但 AI 仍然能理解大意，而且节省了篇幅。

4.3 多人协作时 AGENTS.md 冲突怎么处理

团队协作中，每个人对项目的理解不同，写出来的 AGENTS.md 可能有冲突。处理这个问题的关键是建立明确的维护流程。

建议指定一个“配置负责人”，由他来审核所有对 AGENTS.md 的修改。其他人发现需要补充的约定时，向负责人提建议，由负责人统一写入。这样可以避免多人同时修改导致的冲突和风格不一致。

如果团队规模较大，可以采用“提案-讨论-合并”的流程。任何人想修改 AGENTS.md，先提一个提案说明改什么、为什么改，团队讨论达成一致后再合并。这个流程看起来繁琐，但能保证配置的质量和一致性。

另一个实用技巧是：把 AGENTS.md 的修改和代码修改绑定。当你提交一个 PR 时，如果这个 PR 引入了新的约定或改变了现有约定，就必须同时更新 AGENTS.md。这样配置和代码始终保持同步，不会出现配置滞后于代码的情况。

4.4 常见问题速查表

4.5 几个我踩过的坑

第一个坑是把 AGENTS.md 写成了 README。一开始我写了很多项目背景、业务介绍、用户画像，结果 AI 对这些不感兴趣，它需要的是技术约定。后来我把业务介绍压缩到三句话，把省下来的篇幅用来写代码规范，效果立刻好了很多。

第二个坑是规则写得太细。我曾经把 ESLint 的规则逐条抄进 AGENTS.md，写了上百条。结果 AI 根本记不住，反而把重要的几条也忽略了。后来我只保留最关键的十几条，其他的让 AI 参考 ESLint 配置就行。

第三个坑是忘了更新。项目从 React 17 升级到 18 后，我忘了更新 AGENTS.md 里的版本号，结果 AI 一直按 17 的写法生成代码。后来我养成了习惯，每次升级依赖时顺手检查一遍 AGENTS.md。

第四个坑是过度依赖 AGENTS.md。有一段时间我觉得只要写好了配置，AI 就能完全自主工作。实际上配置只能解决“知道什么”的问题，不能解决“判断什么”的问题。复杂的架构决策、业务逻辑取舍，还是需要人来把关。AGENTS.md 是辅助工具，不是替代品。

5. 进阶玩法：让 Memory 工程真正产生复利

5.1 把 AGENTS.md 和任务管理系统打通

AGENTS.md 解决的是“AI 知道什么”的问题，但“AI 该做什么”是另一个问题。如果你用任务管理工具（比如看板、issue 跟踪器），可以把任务信息和 AGENTS.md 结合起来。

具体做法是：在 AGENTS.md 里说明任务管理工具的用法，比如“当前迭代的任务在tasks/current.md中”、“每个任务的详细描述在tasks/目录下”。然后 AI 在处理任务时，会先读 AGENTS.md 了解项目约定，再读任务文件了解具体要求，最后动手写代码。

这样做的效果是，你只需要告诉 AI“做任务 #123”，它就能自己找到任务描述、理解项目约定、完成代码编写。整个过程不需要你反复解释上下文，效率提升非常明显。

5.2 用 AGENTS.md 驱动代码审查

AGENTS.md 里的约定不仅可以用来指导 AI 写代码，还可以用来审查代码。你可以让 AI 对照 AGENTS.md 检查一段代码是否符合规范，它会逐条核对，指出不符合的地方。

这个用法在代码审查时特别有用。人工审查容易遗漏细节，而且不同审查者的标准不一致。用 AI 对照 AGENTS.md 审查，标准统一、覆盖全面，而且速度很快。当然，AI 审查不能完全替代人工审查，复杂的逻辑问题、架构问题还是需要人来判断。但基础的规范检查交给 AI，能省下不少时间。

5.3 建立项目知识的持续积累机制

AGENTS.md 不是一次性的工作，而是持续积累的过程。每次项目有新的约定、新的决策、新的踩坑经验，都应该及时补充进去。时间长了，AGENTS.md 就成了项目的知识库，新人加入时读一遍就能快速上手。

我建议在团队中建立这样的习惯：每次解决一个棘手问题后，花五分钟想想“这个经验要不要写进 AGENTS.md”。如果是通用的、可复用的经验，就写进去；如果是一次性的、特定场景的，就放在 issue 或文档里。

另一个技巧是定期回顾。每个月花半小时翻一遍 AGENTS.md，看看有没有过时的内容、有没有可以合并的条目、有没有需要补充的新约定。这个习惯能让配置始终保持活力，不会变成一堆无人维护的死文档。

5.4 从 AGENTS.md 到更广泛的 Memory 体系

AGENTS.md 只是 Memory 工程的一个起点。随着实践深入，你可以扩展出更完整的体系。

比如会话记忆：把每次重要对话的结论记录下来，放在memory/sessions/目录下，AI 在需要时可以回溯之前的决策。决策日志：记录每个重要技术决策的背景、选项、理由，放在memory/decisions/下，避免重复讨论已经决定过的事情。知识图谱：把项目中的概念、模块、依赖关系整理成结构化的数据，AI 在回答问题时可以查询这个图谱。

这些扩展不是必须的，取决于项目的复杂度和团队的需求。但方向是明确的：让 AI 对项目的理解越来越深、越来越准，最终达到“像团队老成员一样熟悉项目”的程度。

我在实际使用中体会最深的一点是：Memory 工程的价值不在于技术多复杂，而在于坚持。写一份 AGENTS.md 不难，难的是持续维护、持续迭代。那些真正从这套方案中获益的团队，都是把它当成项目基础设施来对待的，而不是当成一次性的任务。你投入的每一分钟，都会在后续的开发中通过减少重复解释、减少返工、减少沟通成本而加倍回报。