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

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

1.1 为什么传统 AI 编程模式正在失效

过去两年，大多数人用 AI 写代码的方式还停留在“对话式问答”：打开一个聊天窗口，把需求描述一遍，AI 吐出一段代码，复制粘贴，运行报错，再贴回去让它改。这个流程在写一个几十行的工具函数时确实好用，但一旦项目规模超过三五个文件、涉及多轮迭代和多人协作，问题就会集中爆发。

最核心的矛盾在于：大语言模型本身是无状态的。每一次新的对话，对它来说都是“第一次见面”。它不记得你上周定的目录结构，不记得你们团队约定用pnpm而不是npm，不记得数据库字段命名必须用下划线风格。你每次都得重新交代一遍背景，交代不全它就自由发挥，发挥出来的东西和现有代码风格打架，最后你花在“纠正 AI”上的时间，可能比你自己写还多。

我踩过最典型的一个坑：在一个中型前端项目里，我让 AI 帮忙加一个表单校验逻辑。它默认用了某个流行的校验库，写法很现代，但项目里早就统一用了另一套方案。结果它生成的代码引入了一个新依赖，构建体积涨了 40KB，CI 还因为依赖锁文件冲突挂了。这不是 AI 笨，是我没给它“记忆”。

所以范式转换的第一个驱动力，就是把“每次重新交代”变成“一次声明、长期生效”。这本质上是从命令式、临时性的交互，转向声明式、持久化的配置。

1.2 声明式配置到底解决了什么问题

声明式这个词听起来有点玄，其实生活里到处都是。你去餐厅点菜，“来一份宫保鸡丁”是声明式——你只描述结果，怎么做是厨房的事；而“先切鸡丁，再热油，放花生米……”是命令式。AI 编程里的声明式配置，就是你用一份文件告诉 AI：“这个项目长这样，规则是这样，你按这个来。”

它解决的核心问题有三个：

• 一致性：无论谁来问、什么时候问，AI 拿到的项目上下文都是同一份，输出风格稳定。
• 可维护性：项目规则变了，改一个文件即可，不用去翻几十条历史对话。
• 可传承性：新人加入，看这份配置文件就能快速理解项目约定，AI 也一样。

这里要引出一个关键概念——Memory 工程。很多人以为 Memory 就是“让 AI 记住聊天记录”，这是误解。真正的 Memory 工程，是系统性地设计“什么信息该被持久化、以什么结构存储、在什么时机注入到模型上下文里”。它更像数据库设计，而不是聊天记录备份。

1.3 AGENTS.md 为什么成为一个关键抓手

在各种声明式方案里，AGENTS.md这类约定文件之所以流行，是因为它足够简单、足够通用。它就是一个放在项目根目录的 Markdown 文件，用自然语言写清楚：项目是干什么的、目录怎么组织、代码规范是什么、常用命令有哪些、有哪些坑不能踩。

它的优势在于：

Markdown 格式的好处是人和机器都能读。人读起来像项目说明书，机器读起来就是结构化的上下文。你不需要学什么新语法，写清楚就行。这一点非常重要——降低采用门槛，是任何工程范式能落地的前提。

2. Memory 工程的核心设计：让 AI 真正“记住”项目

2.1 Memory 的分层：短期、长期与项目级

做 Memory 工程，第一步是分清记忆的层次。我把它分成三层，这个分法参考了操作系统里的缓存层级思路：

• 短期记忆（会话级）：当前这次对话的上下文窗口。它容量有限，对话一关就没了。适合放临时需求、当前正在改的文件内容。
• 长期记忆（用户级）：跨会话保留的偏好，比如“我习惯用函数式写法”“注释用中文”。它跟着人走，不跟着项目走。
• 项目级记忆（仓库级）：跟着代码仓库走的规则，比如技术栈、目录约定、构建命令。AGENTS.md就属于这一层。

很多人把这三层混在一起，结果就是：项目规则写进了个人偏好里，换个项目就失效；临时需求又写进了项目文件里，污染了长期配置。分层不清，是 Memory 工程最常见的失败原因。

我的建议是：项目级记忆用文件（AGENTS.md），用户级记忆用工具自带的全局配置，短期记忆就让它留在对话里，别硬存。各归其位，才不会互相打架。

2.2 AGENTS.md 应该写什么、不该写什么

这是实操中最容易走偏的地方。我见过有人把AGENTS.md写成几千行的“项目百科”，结果 AI 读取时反而抓不住重点。也见过有人只写一句“这是一个 React 项目”，等于没写。

我的经验是，一份好的AGENTS.md应该覆盖以下模块，但每个模块都要克制：

1. 项目一句话定位：让 AI 知道自己在什么场景下工作。
2. 技术栈清单：语言、框架、关键库及版本。
3. 目录结构说明：哪些目录放什么，新文件该放哪。
4. 代码规范：命名、缩进、注释、导入顺序等硬性约定。
5. 常用命令：安装、启动、测试、构建、格式化。
6. 禁区与注意事项：不能改的文件、不能引入的依赖、已知的坑。

不该写的东西同样重要：

• 不要写大段业务逻辑说明，那是代码注释的活。
• 不要写会频繁变动的信息，比如某个接口的临时字段。
• 不要写和代码无关的团队八卦或流程文档。

提示：AGENTS.md的黄金标准是“一个新人读完能在 10 分钟内上手改代码”。如果达不到这个标准，说明要么太简略，要么太啰嗦。

2.3 上下文注入的时机与策略

写好了文件，还得让它“在正确的时机被读到”。这里涉及上下文注入策略，我总结了几种常见做法：

• 全量注入：每次请求都把AGENTS.md完整塞进上下文。简单粗暴，适合小文件，但会占用 token。
• 按需注入：根据当前任务类型，只注入相关章节。比如改前端就注入前端规范，改构建就注入命令部分。省 token，但需要额外逻辑。
• 摘要注入：把长文件压缩成摘要再注入。适合超大项目，但可能丢细节。

实测下来，对于大多数中小项目，全量注入 + 控制文件在 500 行以内是最省心的方案。token 成本可控，实现也简单。只有当项目特别大、规范特别多时，才值得上按需注入。

这里有个容易忽略的点：注入顺序会影响模型注意力。把最重要的规则放在文件开头和结尾，中间放次要内容，这是符合模型注意力分布规律的。我试过把“禁止引入新依赖”这条放在文件最末尾，遵守率明显比放在中间高。

3. 实操落地：从零搭建一套声明式 AI 编程环境

3.1 环境准备与工具选型

先说清楚，这套方案不绑定任何特定工具。无论你用的是哪类 AI 编程助手，只要它支持读取项目文件作为上下文，就能用。选型时关注三个能力：

• 能否自动读取项目根目录的约定文件。
• 能否在每次请求时稳定注入该文件内容。
• 能否区分项目级和用户级配置。

如果工具支持自定义上下文文件路径，那就更灵活了。我一般会把主文件命名为AGENTS.md，然后在工具配置里指向它。这样即使换工具，文件本身不用动，迁移成本极低。

准备工作清单：

1. 确认你的 AI 编程工具支持项目级上下文文件。
2. 在项目根目录创建AGENTS.md。
3. 把该文件纳入版本控制（这点很重要，团队共享靠它）。
4. 在工具里配置读取路径。

3.2 编写第一版 AGENTS.md 的完整步骤

下面是我实际用的一套模板结构，你可以直接抄，然后按项目改。

第一步，写项目定位。用两三句话讲清楚：这是什么项目、给谁用、核心功能是什么。别写“这是一个基于 XX 的系统”这种废话，要写人话。

第二步，列技术栈。用表格最清晰：

第三步，画目录结构。用代码块画树状图，每个目录后加一句说明。

第四步，定代码规范。这部分要具体到可执行，比如“组件文件名用大驼峰”“工具函数用小驼峰”“常量全大写下划线分隔”。

第五步，写命令清单。把dev、build、test、lint、format都列上，注明什么时候用。

第六步，写禁区。比如“不要修改config/下的文件”“不要引入未在技术栈中列出的依赖”“不要用any类型”。

写完这六步，一份可用的AGENTS.md就成型了。整个过程熟练后 20 分钟能搞定。

3.3 参数计算与配置细节

有人会问：文件写多长合适？我的经验公式是：基础规则 200 行以内，加上项目特有规则，总数控制在 500 行以内。超过这个数，模型对后半部分的遵守率会下降。

token 成本也要算一笔账。假设AGENTS.md有 400 行，约 3000 个 token。如果每次请求都注入，一天 100 次请求就是 30 万 token 的额外消耗。按主流价格算，成本其实很低，但如果你用的是按量计费且请求量巨大，就值得考虑按需注入。

另一个细节是文件更新频率。项目规则不是一成不变的，我建议每两周回顾一次AGENTS.md，把过时的删掉，把新踩的坑补上。这个回顾动作本身，就是团队知识沉淀的过程。

注意：AGENTS.md改动后，最好在提交信息里写清楚改了什么、为什么改。这样回溯时能看懂规则演变的历史。

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

4.1 AI 不遵守 AGENTS.md 怎么办

这是最高频的问题。排查思路按顺序来：

• 确认文件真的被读取了。有些工具需要显式开启“读取项目文件”选项，默认是关的。先验证这一点。
• 检查文件位置。必须在项目根目录，或者工具配置指定的路径。放错地方等于没放。
• 看规则是否可执行。“代码要优雅”这种规则 AI 没法遵守，“函数不超过 50 行”才能执行。把模糊规则改成量化规则。
• 看规则是否冲突。文件里前面说“用分号”，后面说“不用分号”，AI 会随机选一个。自己先通读一遍。
• 看规则是否太多。500 行是上限，超了就精简。

我遇到过一次，规则写得都对，但 AI 就是不遵守。最后发现是文件编码问题，工具读取时乱码了。改成 UTF-8 后立刻正常。这种坑不踩一次根本想不到。

4.2 上下文太长导致响应变慢或截断

当AGENTS.md加上当前代码文件后超出模型上下文窗口，就会出现响应变慢、答非所问、甚至直接截断。解决办法：

我的做法是：一次只让 AI 关注一个模块。改前端就只注入前端相关文件和规范，别把整个项目都塞进去。这样既快又准。

4.3 多人协作时的 Memory 冲突

团队里每个人对“项目规范”的理解可能不同，写进AGENTS.md时就会打架。解决靠流程：

1. AGENTS.md的修改必须走代码评审，和改代码一样。
2. 有争议的规则，先在团队里讨论达成一致再写。
3. 定期（比如每月）开一次短会，专门过一遍AGENTS.md。

我见过一个团队，因为两个人分别往AGENTS.md里加了矛盾的命名规则，导致 AI 生成的代码一会儿一个风格，code review 时吵得不可开交。后来定了评审流程，问题就没了。Memory 工程不只是技术问题，更是协作问题。

4.4 独家避坑技巧汇总

最后分享几条我踩坑换来的经验：

• 先写禁区，再写规范。禁区是“不能做什么”，优先级最高，先写能避免大错。
• 用例子代替描述。与其写“导入顺序要规范”，不如直接贴一段正确的导入示例。
• 给规则编号。方便在对话里引用，比如“请遵守第 3.2 条”。
• 保留一个“变更日志”章节。记录每次改了什么，方便回溯。
• 别把密钥、内网地址写进去。AGENTS.md会进版本库，敏感信息一律不放。

这套东西我从去年开始在自己的几个项目里用，最大的感受是：前期花两小时写文件，后期每天省半小时纠正 AI。这笔账怎么算都划算。而且随着文件越来越完善，AI 输出的代码越来越像“自己人写的”，那种顺畅感是对话式编程给不了的。

后续如果项目继续变大，我会考虑把AGENTS.md拆成多个文件，按模块组织，再写一个主文件做索引。这样既能控制单文件长度，又能保持结构清晰。这个方向等我实践一段时间再来分享。