从无状态到有状态：AGENTS.md 与 Memory 工程实践指南

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

1.1 为什么“无状态模型”正在成为瓶颈

过去两年，大多数人用 AI 写代码的方式其实非常原始：打开一个对话框，把需求敲进去，模型吐出一段代码，复制粘贴，结束。下一次再问，它完全不记得你上次说过什么。这种方式我称之为“无状态调用”——模型本身不携带任何跨会话的记忆，每次交互都是白纸一张。

这种模式在写小函数、查语法、生成正则表达式时确实够用。但一旦进入真实项目，问题就暴露了。你告诉它“我们项目用 pnpm 不用 npm”“组件统一放在 src/components 下”“所有 API 请求必须走统一的 request 封装”，结果下一个会话它照样给你写npm install，照样把组件丢到根目录，照样直接fetch。你不得不每次重复交代同样的背景信息，像在跟一个每天失忆的同事协作。

这不是模型能力的问题，而是范式的问题。无状态调用把“项目上下文”这个最关键的变量完全交给了人类去手动维护，而人类恰恰是最不擅长重复记忆的。真正的工程化协作，需要模型能够“记住”项目的约定、规范、结构，并且在新会话中自动加载这些信息。

1.2 从 Prompt 工程到 Memory 工程的跃迁

于是就有了“Memory 工程”这个概念。它和 Prompt 工程的区别在于：Prompt 工程关注的是“这一次怎么问”，Memory 工程关注的是“怎么让模型持续知道它该知道的事”。

打个比方。Prompt 工程像是你每次打电话给客服都要重新报一遍订单号；Memory 工程则是你登录账号后，客服系统自动调出你的历史记录。前者靠嘴皮子，后者靠系统设计。

Memory 工程要解决的核心问题有三个：

• 持久化：项目约定、代码规范、目录结构这些信息，需要以某种形式固化下来，而不是散落在聊天记录里。
• 自动加载：新会话启动时，模型应该自动读取这些信息，不需要人类手动粘贴。
• 可维护：当项目规范变化时，只需要改一个地方，所有会话都能同步更新。

这三个问题听起来简单，但落地时会牵扯到文件组织、加载时机、优先级冲突、上下文长度控制等一系列细节。这也是为什么“AGENTS.md”这类声明式配置文件开始流行——它试图用最朴素的方式（一个 Markdown 文件）来解决最核心的问题（让模型知道项目规则）。

1.3 AGENTS.md 为什么是声明式配置的典型代表

AGENTS.md 的思路非常直接：在项目根目录放一个 Markdown 文件，里面写清楚这个项目的技术栈、目录约定、编码规范、常用命令、禁止事项。AI 工具在启动时自动读取这个文件，把它作为系统提示的一部分注入到对话上下文中。

它之所以叫“声明式”，是因为你只需要描述“这个项目是什么样”，而不需要写任何加载逻辑、解析代码、注入脚本。工具负责读取，模型负责理解，你负责写清楚规则。这种分工非常符合工程直觉：配置和逻辑分离。

对比一下“命令式”的做法：你写一个脚本，在每次调用模型前读取配置文件、拼接 prompt、调用 API。这种方式灵活但脆弱，换个工具就要重写一遍。而 AGENTS.md 是工具无关的——只要工具支持读取这个文件，你的配置就能复用。

我实测下来，AGENTS.md 最大的价值不是技术上的创新，而是约定上的统一。它让“项目记忆”这件事有了一个标准载体，就像.gitignore之于版本控制、Dockerfile之于容器构建。标准载体一旦形成，生态就会围绕它生长。

2. AGENTS.md 的核心结构与编写要点

2.1 一个可用的 AGENTS.md 应该包含哪些区块

我翻过不少项目的 AGENTS.md，也自己写过十几版，总结下来，一个真正能被模型有效利用的文件，通常包含以下几个区块。注意，不是每个项目都需要全部，但缺了关键区块，模型就会开始“自由发挥”。

项目概览：一句话说清楚这个项目是干什么的，用什么语言，跑在什么环境。比如“这是一个基于 TypeScript 的 CLI 工具，运行在 Node 20+，使用 pnpm 管理依赖”。这句话看似简单，但它决定了模型后续所有代码建议的基本盘。

目录结构：列出核心目录和它们的职责。不需要列出每一个文件，但要让模型知道“组件放哪”“工具函数放哪”“测试放哪”。我见过最有效的写法是用一个代码块画出树形结构，旁边用注释说明职责。

技术栈与依赖：明确框架、库、版本约束。比如“使用 React 18 + Vite + Zustand，禁止引入 Redux”。这里的关键是写清楚禁止项，因为模型默认会推荐它训练数据里最常见的方案，而不是你项目实际用的方案。

编码规范：命名约定、导入顺序、错误处理方式、注释要求。这部分越具体越好。比如“所有异步函数必须用 try-catch 包裹，错误统一走 logger.error”“组件文件用 PascalCase，工具函数用 camelCase”。

常用命令：开发、构建、测试、 lint 的命令。模型在建议你运行什么之前，应该先知道项目实际用什么命令。否则它会默认让你跑npm test，而你项目用的是pnpm test:unit。

禁止事项：这是最容易被忽略但最重要的区块。明确写出“不要做什么”，比如“不要修改 package.json 中的 scripts”“不要引入新的全局状态库”“不要用 any 类型”。模型对禁止项的遵守程度，直接决定了你 review 代码时的心情。

2.2 怎么写才能让模型真正“读懂”

写 AGENTS.md 最大的坑是：你以为你写清楚了，但模型读完之后还是按自己的习惯来。问题通常出在表达方式上。

第一，用肯定句，少用否定句。模型对“使用 pnpm”的遵守程度，远高于“不要使用 npm”。否定句需要模型先理解“npm 是什么”，再抑制这个行为，而肯定句直接给出目标行为。所以尽量把“不要用 X”改写成“用 Y”。

第二，给例子，不给抽象描述。与其写“遵循良好的命名规范”，不如写“组件用 PascalCase，如UserProfile.tsx；工具函数用 camelCase，如formatDate.ts”。模型对具体例子的模仿能力远强于对抽象规则的理解能力。

第三，控制长度，突出优先级。AGENTS.md 不是越长越好。我试过写一个 800 行的配置文件，结果模型反而抓不住重点。后来压缩到 150 行以内，只保留最关键的规则，遵守率明显提升。如果规则很多，用“必须”“应该”“可以”来分级，让模型知道哪些是硬约束。

第四，把最容易被违反的规则放在最前面。模型的注意力是有限的，文件开头的规则被遵守的概率最高。所以把你最在意的三条规则放在前 20 行。

2.3 一个真实项目的 AGENTS.md 拆解

下面是我在一个模拟项目中实际使用的 AGENTS.md 片段，做了脱敏处理，但结构保留完整。

# 项目约定 ## 概览 - TypeScript CLI 工具，Node 20+，pnpm 管理依赖 - 入口：src/index.ts，命令定义在 src/commands/ ## 目录职责 - src/commands/：每个命令一个文件，文件名即命令名 - src/utils/：纯函数工具，禁止引入外部状态 - src/services/：外部 API 调用，统一走 request.ts 封装 - tests/：与 src 目录结构镜像 ## 技术约束 - 使用 commander 定义命令，zod 做参数校验 - 禁止引入 lodash，工具函数自己写 - 所有异步操作必须返回 Promise，禁止回调风格 ## 编码规范 - 导出用 named export，禁止 default export - 错误处理：抛出 Error 子类，由顶层统一捕获 - 日志：使用 src/utils/logger.ts，禁止 console.log ## 常用命令 - 开发：pnpm dev - 构建：pnpm build - 测试：pnpm test - 类型检查：pnpm typecheck ## 禁止事项 - 不要修改 package.json 的 scripts 字段 - 不要新增全局依赖，需要时先讨论 - 不要用 any，用 unknown 加类型守卫

这个文件不到 60 行，但覆盖了模型最容易犯错的几个点。实测下来，新会话中模型建议npm install的概率从 80% 降到了接近 0，建议console.log的概率也大幅下降。

注意：AGENTS.md 的效力取决于工具是否支持自动读取。目前主流 AI 编程工具对这个文件的支持程度不一，有的自动读取，有的需要手动配置路径。写之前先确认你的工具链是否支持。

3. Memory 工程的落地实操与工具链适配

3.1 不同工具对 AGENTS.md 的读取机制

AGENTS.md 不是某个工具的专属格式，而是一个约定。不同工具对它的处理方式差异很大，这直接影响了你的配置策略。

有的工具在启动时会自动扫描项目根目录，发现 AGENTS.md 就读取并注入系统提示。这种最省心，你只需要写好文件就行。有的工具需要你在配置文件里显式指定路径，比如在.ai/config.json里写"memoryFile": "AGENTS.md"。还有的工具支持多级加载，会同时读取项目根目录和用户主目录下的 AGENTS.md，后者作为全局默认，前者作为项目覆盖。

我建议你在项目里同时维护两个文件：根目录的AGENTS.md写项目专属规则，用户主目录的AGENTS.md写个人通用偏好（比如“回答用中文”“代码注释用英文”）。这样换项目时，个人偏好自动生效，项目规则按项目加载。

如果工具不支持自动读取，退而求其次的方案是在会话开始时手动粘贴 AGENTS.md 内容。虽然麻烦，但比每次重复交代强。更好的做法是写一个简单的脚本，把 AGENTS.md 内容复制到剪贴板，一键粘贴。

3.2 多级 Memory 的优先级设计

当项目变大，或者你同时维护多个项目时，单一 AGENTS.md 就不够用了。这时候需要设计多级 Memory 的优先级。

我的做法是分三层：

• 全局层：放在用户主目录，写个人通用偏好，比如语言、注释风格、回答详细程度。这一层对所有项目生效。
• 项目层：放在项目根目录，写技术栈、目录约定、编码规范。这一层覆盖全局层。
• 模块层：放在子目录，写该模块的特殊规则。比如src/services/AGENTS.md写“所有外部调用必须加超时和重试”。这一层覆盖项目层。

优先级从下往上：模块层 > 项目层 > 全局层。当规则冲突时，更具体的层胜出。这个设计和 CSS 的优先级逻辑类似，模型理解起来也不费力。

关键是要在文件里写清楚“本文件覆盖上层规则”还是“本文件补充上层规则”。我通常用一句话开头：“以下规则覆盖项目根目录 AGENTS.md 中的对应条目”，避免模型在冲突时犹豫。

3.3 把 Memory 工程接入日常开发流

写好了 AGENTS.md，下一步是让它真正融入日常开发，而不是写完就忘。

第一，把 AGENTS.md 纳入代码评审。每次项目规范变化时，同步更新 AGENTS.md，并在 PR 里 review。我见过太多项目，规范改了但 AGENTS.md 没改，结果模型还在按旧规则生成代码，反而添乱。

第二，用 AGENTS.md 做新人 onboarding。新成员加入时，让他先读 AGENTS.md，比读一堆散落的文档高效得多。因为这个文件本身就是“项目规则的精炼版”。

第三，定期清理过时规则。项目演进过程中，有些规则会失效。比如早期禁止用某个库，后来引入了。这些过时规则如果不清理，会误导模型。我一般每个月过一遍 AGENTS.md，删掉不再适用的条目。

第四，把 AGENTS.md 和 lint 规则对齐。如果 AGENTS.md 说“禁止 default export”，那 ESLint 里也应该有对应规则。两者一致时，模型生成的代码更容易通过检查；不一致时，模型会困惑到底听谁的。

实操心得：我习惯在 AGENTS.md 末尾加一个“最近更新”区块，记录每次修改的日期和原因。这样回溯时能快速知道某条规则是什么时候加的、为什么加。

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

4.1 模型不遵守 AGENTS.md 怎么办

这是最常见的问题。你写了一大堆规则，模型该怎样还怎样。排查思路如下：

先确认工具是否真的读取了文件。有的工具虽然支持 AGENTS.md，但需要重启会话才生效。有的工具只在特定模式下读取。先看工具的日志或文档，确认读取路径和时机。

再检查文件格式。Markdown 的标题层级、代码块、列表符号，都可能影响解析。我遇到过因为用了####四级标题导致工具只读到二级就停了的情况。尽量用##和###，避免过深层级。

然后看规则是否具体。前面说过，抽象规则容易被忽略。把“遵循良好实践”改成“函数不超过 50 行，参数不超过 4 个”，遵守率会明显提升。

最后考虑长度。如果文件超过 300 行，模型可能只读了前一部分。把最重要的规则前置，或者拆分成多个文件按需加载。

4.2 规则冲突与上下文超限的处理

当多级 Memory 同时加载时，规则冲突几乎不可避免。比如全局层说“注释用中文”，项目层说“注释用英文”。模型遇到这种冲突时，行为不确定。

解决办法是在项目层显式声明覆盖关系。我通常在每个 AGENTS.md 开头写一句：“本文件中的规则优先于上层文件中的同名规则。”这样模型就知道该听谁的。

上下文超限是另一个坑。AGENTS.md 内容加上代码文件、对话历史，很容易撑爆模型的上下文窗口。这时候模型会开始“遗忘”前面的内容，包括你的规则。

我的应对策略是：把 AGENTS.md 控制在 200 行以内，只保留最高频、最关键的规则。次要规则放到单独的文档里，需要时手动引用。另外，定期清理对话历史，避免无关内容占用上下文。

4.3 排查速查表

4.4 几个我踩过的坑

第一个坑是把 AGENTS.md 写成技术文档。一开始我写得很详细，把架构设计、数据流、部署流程都塞进去。结果模型被大量无关信息干扰，反而忽略了核心规则。后来我把它定位为“给 AI 看的规则清单”，只写模型需要遵守的约束，不写背景介绍。

第二个坑是规则之间互相矛盾。比如一条说“所有函数必须写注释”，另一条说“简单函数不需要注释”。模型遇到这种矛盾时，会随机选一条执行。后来我加了一条元规则：“当规则冲突时，以更具体的规则为准。”并在每条规则旁标注适用范围。

第三个坑是忘记更新 AGENTS.md。项目从 JavaScript 迁移到 TypeScript 后，我忘了改 AGENTS.md，结果模型还在按 JS 的习惯生成代码，比如不写类型注解。后来我把 AGENTS.md 的更新纳入迁移 checklist，每次技术栈变更时同步修改。

第四个坑是过度依赖 AGENTS.md。有一段时间我什么规则都往里塞，导致文件膨胀到 500 多行。模型读不完，我也维护不过来。后来我学会分层：核心规则放 AGENTS.md，边缘规则放单独的docs/ai-rules/目录，需要时手动引用。

5. 从 AGENTS.md 延伸：Memory 工程的未来形态

5.1 动态 Memory 与静态配置的边界

AGENTS.md 是静态配置，写一次管一段时间。但项目是动态的，代码在变，依赖在变，规范也在变。静态配置迟早会过时。

我目前的做法是“静态为主，动态补充”。AGENTS.md 写那些稳定的、不常变的规则，比如目录结构、命名约定。而那些频繁变化的，比如“当前正在重构 auth 模块，暂时不要动 src/auth/”，则通过会话开头的临时提示来补充。

未来如果工具支持，动态 Memory 可能会成为标配。比如工具自动分析代码库，生成当前的项目结构摘要，注入到上下文中。或者根据 git diff 自动识别最近改动的模块，提醒模型注意。这些目前还需要手动做，但方向是清晰的。

5.2 团队协作中的 Memory 共享策略

个人用 AGENTS.md 很简单，团队用就复杂了。不同成员可能有不同的偏好，但项目规则必须统一。

我的建议是：项目级 AGENTS.md 由团队共同维护，个人偏好放全局层。项目级文件纳入版本控制，任何修改走 PR 评审。个人偏好放用户主目录，不纳入版本控制。这样既保证了项目规则的一致性，又保留了个人的灵活性。

另外，可以给 AGENTS.md 加一个“变更记录”区块，记录每次修改的日期、修改人、修改原因。这样当模型行为异常时，可以快速定位是不是某次规则变更导致的。

5.3 我个人的 Memory 工程实践清单

最后分享我日常使用的一套清单，供参考：

• 每个项目根目录必有 AGENTS.md，控制在 150 行以内
• 用户主目录有全局 AGENTS.md，写个人通用偏好
• 项目级文件纳入 git，全局文件不纳入
• 每月 review 一次，删除过时规则
• 技术栈变更时同步更新
• 规则用肯定句和具体例子
• 禁止事项单独成块，放在显眼位置
• 多级 Memory 显式声明优先级
• 会话开始时确认工具已加载 AGENTS.md
• 遇到模型不遵守时，先查文件格式和长度，再查规则具体性

这套做法我用了大半年，最大的感受是：Memory 工程的核心不是技术，而是纪律。写文件不难，难的是持续维护、及时更新、团队对齐。但一旦跑通，你会发现和 AI 协作的效率有质的提升——不再需要每次重复交代背景，不再需要反复纠正同样的错误，模型真正开始像一个“记得住事”的同事。

这个方向后续还可以扩展的地方很多，比如把 AGENTS.md 和 CI 打通，规则违反时自动提醒；或者根据项目类型生成模板，减少手写成本。但那是下一步的事了，先把眼前这个文件写好、用好，收益就已经很明显了。