无状态模型让AI每次失忆？用AGENTS.md声明式配置项目规则

无状态模型折腾了我半年然后把规则写进 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 长期记忆层向量检索与结构化存储长期记忆解决的是“跨会话的知识沉淀”。常见方案有方案适合场景维护成本典型工具方向向量库 RAG超大代码库、多文档知识库高要维护索引和检索质量各类 embedding 向量数据库结构化存储需要精确查询的元数据中要设计 schema数据库、配置存储文件系统项目级约定、小而稳定的规则极低写文件就行AGENTS.md、各类规则文件向量库那套方案在超大代码库里确实有效但小项目上它经常是杀鸡用牛刀。你为一个三五个人的项目搭一套 embedding 管线索引要更新、检索质量要调到头来 AI 该记错的还是记错。而且 RAG 检索来的大概率是“相关文档片段”它不能保证这些片段里正好有“构建命令是什么、字段命名规范是什么”这类全局约束。对大多数项目来说最划算的长期记忆不是向量库而是文件系统——把规则写进一个文件让 AI 每次开工前自动读一遍。这也是 AGENTS.md 这类声明的底层思路。2.4 被低估的工作记忆层AGENTS.md 为什么重要AGENTS.md 本质上是“工作记忆的持久化”。它把项目里最核心、最稳定的约束写成一个文件放在仓库根目录AI 工具启动时自动加载相当于给每次调用的模型设置了一份“项目默认值”。和“每次对话贴 prompt”相比它的优势一目了然对比维度每次对话贴规则AGENTS.md 声明式配置规则维护改一次要重新复制粘贴改文件提交即可版本控制无法追溯随仓库走可 diff、可回滚跨工具复用只对当前会话有效多个工具可读取同一份上下文负担每次都全文带上由工具管理加载时机和规则可审查性谁贴了啥没法查规则是显式文件可做 code review这正好回应了标题里的“范式转换”从把记忆交给“每次对话时的临时输入”转变成把记忆交付给“项目基础设施”。前者是每次靠人肉搬运后者是项目自带记忆体。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.11FastAPI - 前端Vue 3 TypeScript Vite - 数据库PostgreSQLORM 使用 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 没法判断只会消耗注意力。要写“代码必须通过 eslintpnpm 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 条硬约束按上面的骨架整理成文件放到项目根目录提交。然后做了三件事验证新开会话直接问 AI“这个项目用什么数据库字段命名规范是什么构建命令是什么” 如果它答对了说明 AGENTS.md 被读取了。让它执行一个会触碰到规则的任务比如“在用户模型里加一个 createdAt 字段”看它是否自动用了 snake_case、是否主动提了迁移脚本的事。故意制造一个模糊场景“帮我写一段导出 CSV 的代码”看它是否主动遵守“编码 UTF-8、字段用 snake_case”这两条。我最初第一次验证就发现 AGENTS.md 没生效——排查后才发现工具找的是根目录文件而我把内容放到了子目录。改回根目录后立刻正常。4.4 第三步效果对比改造后我观察了两周最直观的变化是“每轮对话前不用再粘贴那 20 行规则了”。更具体的对比如下指标改造前改造后每轮任务开始前的人工交代每次都要粘贴 20 行规则无需交代数据库字段命名错误率约 30%经常发生基本为 0路由写错位置的次数平均每 3 次任务出现 1 次连续 20 次任务未出现“测试命令是什么”这类提问经常发生几乎消失一次任务平均返工轮次3-4 轮1-2 轮这个提升不是玄学。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 反复解释项目规则不妨今晚就把根目录那个文件建出来先写三行技术栈、常用命令、最容易踩的坑。剩下的等踩过坑再慢慢补。