最近两个月我前后重写了同一个模块三次。不是需求变了是AI编程助手每次都在同一个地方翻车它总是记不住我们项目里约好的错误码规范。明明上一次对话里才告诉过它新开一个会话它又忘得干干净净继续按它自己的默认习惯生成代码。我把这个现象在团队里说了一遍大家的反应出奇一致——原来你们也这样。这不是个例而是当前大语言模型参与编程时最根本的矛盾模型本身是无状态的而一个真实的软件项目是高度有状态的。这个词说起来有点抽象但落到日常就是AI每次跟你对话都是第一次见面。它没有长期记忆不知道你的项目背景、目录结构、编码规范、构建流程每次只能靠当前对话里的上下文猜测。于是我们一边抱怨AI不靠谱一边不停地重复粘贴同样的背景资料。直到我开始认真研究Memory工程尤其是把项目规则沉淀成AGENTS.md这种声明式配置之后情况才真正改观。这篇文章就把我这段实践完整摊开来讲清楚无状态模型的局限、Memory工程的三种形态以及AGENTS.md从设计到落地的每一个细节。适合被AI反复失忆折磨的开发者也适合想系统梳理AI编程工作流的人。1. 无状态模型的本质局限AI为什么记性这么差要理解AGENTS.md为什么有价值得先理解大语言模型在编程场景下记不住这件事到底是怎么发生的。这不是产品缺陷而是架构特性。搞清楚这一点你就不会再用错误的方式去治它。1.1 AI编程的Session失忆症现象大语言模型的处理方式是典型的无状态推理你发一段输入进去它根据这些输入生成一段输出然后这次交互就结束了。下一次你再发一段输入它面对的仍然只有你这次给的内容之前聊过的所有东西都不会主动保留。模型内部当然有训练时学到的海量知识但那是通用世界知识不是你这个项目的知识。这在编程场景里就特别别扭。因为写代码这件事极度依赖上下文约束这个项目的目录约定是什么、接口命名走什么风格、数据库字段用下划线还是驼峰、测试命令是npm test还是make check、哪些历史包袱不能碰……这些信息通常分散在代码、文档、团队讨论里AI看不到或者说每次都要你重新告诉它。我后来做过一个统计在同一个项目里连续使用AI编程助手两周大概有六成以上的对话开头都在重复解释项目背景。我们的后端是某个框架、错误码规则在这个文件里、不要动那个旧模块——这些话我复制粘贴了无数遍。更糟糕的是AI偶尔还会在你没重复到的细节上自由发挥生成一套和项目风格完全不一致的代码。你review的时候还得逐行解释反而比手写更累。这就是Session失忆症会话一关记忆清零。你上一次教它的一切都随token烟消云散。1.2 为什么多塞上下文不是解决之道很多人第一反应是既然AI只认当前上下文那我每次多塞一点背景材料进去不就行了理论上没错实操上会有三个问题。第一个是上下文窗口的上限。当前主流模型的上下文虽然越来越大从几万到几十万token都有但你的工程资料是无限的。把整个仓库塞进去不现实连塞几十个关键文档都会很快逼近窗口上限而且这些文档还挤占了真正用于生成代码的空间。第二个是注意力稀释。模型在长上下文里的表现并不均匀你塞了50个文件进去它很可能只注意到其中比较靠前的几个或者被中间某个看起来相关、其实过时的信息带偏。上下文越长信噪比越低AI反而更容易看漏关键约束。这不是玄学而是Transformer注意力机制的特点信息太多的时候关注度会被摊薄。第三个是成本与效率。每次对话都携带全量背景意味着每次请求的输入token都在数千甚至数万量级费用和延迟同步上涨。我实测过同样的任务带完整背景的对话比带精简背景的对话单次成本能高出好几倍而产出质量并没有同比例提升。所以多塞上下文是个治标不治本的办法它建立在每次重新投喂这个错误前提上。真正合理的思路是把知识前置让AI在开始干活之前就自动获得一份经过整理的、结构化的项目规则。这正是Memory工程要解决的问题。2. Memory工程的三种形态与配合逻辑Memory工程这个概念说白了就是用工程手段给无状态的模型补上有状态的记忆。它不是一个单一技术而是根据记忆的时效和存储位置分成三种形态。我建议你把它们理解成人类记忆的三个层次工作记忆、长期记忆、外部SOP手册。2.1 会话内短期记忆系统提示词与上下文管理第一种形态是会话内的短期记忆靠的是系统提示词和对话上下文。你在对话开头写一大段你是本项目的编程助手请遵循以下规则或者在每次提问时附带当前文件、相关代码片段都属于这一层。这一层的优点是实现简单、零额外基础设施几乎所有AI编程工具都支持。缺点是前面说的那三个问题窗口有限、注意力稀释、成本高。而且它完全依赖使用者主动维护——你忘了写AI就不知道没有任何兜底机制。我见过不少团队把短期记忆用到了极致写一个非常长的系统提示词模板把项目背景、编码规范、输出格式全塞进去每次新会话就粘贴一次。效果确实比裸奔好但维护这套提示词本身变成了一个新负担而且一旦项目规则更新你得同步改提示词还得分发到每个团队成员手里。长期看这不可持续。2.2 跨会话长期记忆RAG与Embedding的边界与局限第二种形态是跨会话的长期记忆典型实现是RAG——把项目文档、历史代码片段向量化存入向量数据库在对话时检索出相关内容注入上下文。它比短期记忆进了一步AI可以回想起之前存进去的信息不用你每次都手动塞。我在一个中等规模项目上试过RAG方案把技术文档、旧接口定义、架构说明全部embedding后建了索引效果确实有一截提升AI对旧代码的理解更准确了。但用下来也发现几个问题。一是检索质量直接决定效果。向量检索吃的是相关性不是精确性它经常把看起来相关但其实过时的文档捞出来AI采信之后就翻车。你需要在检索逻辑、分段策略、重排序上做不少调优这个工程量不小。二是初始化成本高先把所有文档清洗、切分、向量化一遍还要维护更新管线代码每次变更之后文档和向量库都要跟着变。三是很难覆盖项目里没人写下来但在场的人都清楚的隐形知识比如某个目录不能动是因为历史原因——这种共识没人会专门写成文档RAG再有本事也检索不到。RAG适合的是知识密集型场景比如大型遗留代码库的资料查询。但对于一个规则驱动的项目协作场景它的精度和实时性都不够。你需要的不是AI能查到资料而是AI必须遵守规则。2.3 项目级声明式记忆把规则写进仓库第三种形态就是本文的主角项目级声明式记忆落地形态是AGENTS.md。它把项目的关键约定、命令、规范以Markdown文件的形式直接放在仓库里AI编程工具在启动时会自动读取作为工作时的规则依据。它的核心思想是配置优于上下文你不需要在每次对话里重新解释规则规则本身就躺在仓库里AI一进来就能看到。它不仅是记忆而是把记忆变成了项目资产跟着代码库走谁打开这个仓库谁就继承这份记忆。三种形态不是互斥的而是配合使用。我的建议是AGENTS.md承担项目级、长期、稳定的规则RAG承担大量文档资料的按需检索短期上下文承担当前任务相关的临时信息。三者的配合关系可以这么理解AGENTS.md是入职手册RAG是公司资料库对话上下文是你手头的便利贴。一个合格的AI编程工作流三者缺一不可但大多数团队连第一步入职手册都没写。3. AGENTS.md的设计哲学把隐性背景转为显式配置AGENTS.md听起来像是一个新东西但设计哲学其实很朴素把软件项目里那些重要但没人写下来的知识用一份显式文件沉淀下来。它解决的问题和过去敏捷开发里的团队章程、开源社区的贡献者指南是同一类问题只不过服务对象从人类新成员换成了AI代理。3.1 AGENTS.md本质上是什么你可以把AGENTS.md理解成一份给AI编程助手的岗位说明书。它回答三个问题你在这个项目里是干什么的这个项目有什么规矩遇到问题找什么资料当AI代理进入项目时它不是空着脑子开始工作而是先读这份文件建立对项目的基本认知。我这里说的AI代理指的是能够自主完成多步编程操作的助手。它不是简单的一问一答而是会自己读文件、改代码、跑测试、检查结果的完整流程。这类代理比普通聊天的AI更需要规则约束因为它会在你没有逐句监督的情况下做一整串操作如果没有明确约束它大概率会按自己训练数据里的平均值来做选择而不是按你项目的真实情况来做。这也是为什么AGENTS.md在代码生成之外特别重要它不只是防止AI写错代码更是防止AI在无人紧盯的自主操作中逐步偏离项目方向。有了它相当于给代理套上了缰绳。3.2 为什么偏偏是Markdown文件你可能想问项目规则为什么不放在数据库里、配置文件里、或者代码注释里为什么选Markdown首先是人类可读。Markdown是文档格式任何开发者都能直接在编辑器里浏览、理解、修改。项目规则不是只给AI看的团队里的人类新成员同样需要一份纯文本的、人类友好的文件天然具备双重适用性。其次是AI可解析。Markdown的结构化程度恰到好处标题、列表、代码块既能让AI轻松识别语义边界又不会像JSON、YAML那样有严格的格式约束。你写错了语法JSON解析直接失败但Markdown即使写得不太规整AI依然能读个大概。这一点对工程实践特别重要因为维护文档的耐心总是有限的格式越宽松文档活了越久。还有一点是版本控制友好。Markdown文件是纯文本天然适配Git的diff机制规则的每一次变更都有记录哪次改了什么、由谁改的一目了然。比起塞在数据库里的知识库这份记忆拥有了完整的变更历史和回滚能力。3.3 与README、CONTRIBUTING的分工区别项目里其实已经有类似文档了为什么还要AGENTS.md这是我被问得最多的问题。答案在于服务对象和颗粒度的不同。README.md服务的是使用者讲的是这是什么项目、怎么跑起来、有哪些功能。它面向人类用户描述的是项目的外部视角。CONTRIBUTING.md服务的是贡献者讲的是怎么提交代码、怎么走流程、什么行为不能做。它面向人类开发者规范的是协作流程。而AGENTS.md服务的是编程代理讲的是项目代码结构是什么、构建命令是什么、编码约束有哪些、哪些坑不能踩。它面向AI约束的是自动化工作行为。一个直观的分工原则是README告诉你怎么用CONTRIBUTING告诉你怎么参与AGENTS.md告诉AI怎么写代码不出错。当然三者会有内容重叠比如构建命令在README和AGENTS.md里都会出现这没问题关键是AGENTS.md必须承担那些README和CONTRIBUTING里没有的、面向执行细节的指令。3.4 工具如何读取AGENTS.md注入时机与优先级了解工具的读取机制能帮你想明白该怎么设计文件内容。现在主流的AI编程工具普遍支持对AGENTS.md的自动发现当AI代理开始处理当前工作区时会从项目根目录向上查找AGENTS.md文件把里面的内容注入到系统上下文中。这意味着AI在第一次生成代码之前就已经读过这份规则了不需要你手动贴给它的环节。层级上还有一个设计细节值得注意AGENTS.md不是只能放在根目录子目录里也可以放独立的AGENTS.md而且子目录的规则优先级更高。这是个很实用的机制。比如你的项目整体用一个根目录AGENTS.md描述公共规范而某个子模块有特殊约定就在那个子目录里再写一份AI进入该目录时会被附加的规则影响。这种局部覆盖的能力让规则既能全局统一又不牺牲局部灵活性。了解这个机制之后你会发现AGENTS.md的设计关键就变成内容组织是否足够清晰让AI在有限上下文里快速提取出它当下最需要的那部分约束。这也是下一节要展开的实操重点。4. AGENTS.md 落地从目录规划到规则撰写原理讲再多落到仓库里才是真功夫。我把自己在几个项目里反复迭代后的AGENTS.md写法完整梳理了一遍包括文件放哪、写什么、怎么写、怎么验证、怎么维护。这部分是全篇最值得直接抄作业的。4.1 文件放哪里根目录是第一选择首先明确文件位置。AGENTS.md的默认发现机制是向上查找所以最常见的放法是放在仓库根目录和README.md平级。这个位置对工具的自动发现最友好AI从任何子目录开始工作向上查找时都能找到它。如果你的项目是个巨大的monorepo多个子项目各自独立可以考虑在每个子项目根目录放一个AGENTS.md描述该子项目的局部规则。这样工具在某个子项目里工作时读到的是更精准的上下文。还要注意命名。目前社区和工具链普遍约定的是AGENTS.md这个准确文件名不要改成AGENT.md、AI_RULES.md之类的变体否则工具箱不会被识别。文档和工具的生态还在快速演进跟着约定走踩坑最少。4.2 内容模板与字段设计参考AGENTS.md的内容组织我建议按模块分块写不要写成散文。AI解析结构化信息的能力比解析长段落强得多而且分块之后人类维护也方便。下面是我现在使用的参考模板你可以直接改改字段拿走用# AGENTS.md ## 项目概述 一段话说明项目定位、核心业务逻辑、目标用户。让AI快速判断这是什么。 不需要太长3-5句话足够。 ## 技术栈 - 语言使用某个语言及其版本 - 框架核心框架及版本 - 关键依赖列出不能随便改版本的库 - 包管理使用哪个工具命令 ## 常用命令 - 安装依赖npm install - 本地启动npm run dev - 构建npm run build - 测试npm test - 代码检查npm run lint - 生成迁移npm run migration:generate ## 项目结构 - src/源码主目录按业务模块划分 - packages/shared/公共工具禁止业务代码 - docs/技术文档 - 说明哪些目录可以改、哪些目录不要动 ## 编码规范 - 错误码格式ERR_模块名_数字编号例如 ERR_AUTH_001 - 变量命名变量用camelCase常量用UPPER_SNAKE_CASE - 组件命名大驼峰文件放在同名目录下 - API返回结构统一 { code, data, message } - 禁止在工具函数里写业务逻辑 ## 关键约定与历史背景 - 数据库迁移脚本必须前后兼容禁止直接修改已执行过的迁移 - 旧的 auth 模块有兼容逻辑重构时不得直接移除相关代码 - 性能敏感路径禁止引入 lodash 等重依赖 - 已知问题xxx 接口在边界条件下可能超时需保留重试机制 ## 变更流程 - 修改前先检查是否在现有约定范围内 - 提交前必须跑全部测试不允许只跑局部用例 - 涉及接口变更时先更新文档再改代码模板的核心逻辑是高频优先、约束优先。AI在生成每段代码时随时需要的是命令、结构、规范、历史陷阱这些都靠前放。项目概述虽然重要但放最后也行——AI用得少而且一句话就能掌握。4.3 编写语言的技巧指令要具体禁止抽象AGENTS.md的读者虽然是人维护但使用对象是AI。同样一句话写法和写法之间效果差很远。我吃过很多亏之后总结出几条经验第一条能用祈使句绝不用叙述句。写错误码格式为ERR_模块名_编号就比项目里有一套错误码规则维护的时候要注意有效得多。AI对祈使句的执行倾向比对陈述句的推理倾向高得多这是实测结论。凡是希望AI执行的一律用做什么不要做什么的句式。第二条给出具体例证。规则不要只停留在抽象描述配一个例子AI的理解准确率会大幅提升。比如变量用camelCase写成变量用camelCase例如userId、accessToken、totalCount模型会之前立即把格式映射到具体模式上。对错误码规范这类格式要求甚至可以提供一对正反例。第三条重要信息前置一条规则一句话。长段落里容易把核心约束淹没AI抓取时可能漏掉后面的部分。把每一条规则写短、写独立、写明确就算AI只读到前几条也是最重要的前几条。第四条不要滥用歧义词。合理尽量有时候这类模糊词在规则里出现得越少AI越不会自由发挥。规则文件需要的是确定性不是弹性。4.4 验证AGENTS.md是否生效的方法写完了怎么看有没有用我有一套很土但很有效的验证方法——向AI提问。开一个新会话不粘贴任何上下文直接问几个覆盖核心规则的考察题看它能不能答上。比如我会问这个项目的错误码格式是什么测试命令是什么哪些目录不应该改如果AI能准确回答说明AGENTS.md起作用了。如果回答得模棱两可说明规则写得不够清晰或者没被正确读取需要调整文件结构。还有一个更狠的验证方式——观察实际产出。故意给它一个容易违反某个旧有约定的任务比如给某个旧模块加一个功能然后看它会不会在文件里动不该动的地方。我试过在加了AGENTS.md之后AI至少会先停下来问这个模块有历史约定确定要动吗而不是像以前直接开干。这就是规则起作用了不是你运气好。4.5 维护节奏让规则文件保持新鲜AGENTS.md不是写完就一劳永逸的。项目在演进规则在变化文档如果不更新会比没有文档更危险——AI会拿着过期规则一本正经地犯错误。我的维护节奏是两条一是每次有显著约束变更时立刻更新。比如换了构建工具、改了目录结构、定了新的错误码规范这类影响全盘的变化必须当天同步到AGENTS.md。二是每隔一两个迭代周期做一次收尾清理把已经不成立的旧约定标记删除把新踩的坑补进去。最常见的维护坑是过度承诺。有人会希望一份AGENTS.md解决所有问题于是越写越长最后变成一份两千行的文档。结果AI每次都要处理大量的上下文反而拖慢了效率。真正有用的AGENTS.md一般控制在一页到两页只保留核心约束其余细节让AI自己从代码里发现。配置文件的价值不在大而在准。5. 范式转换从人写代码到人定规则当我们开始认真使用AGENTS.md这类声明式配置之后我明显感觉到自己的角色在变。之前我是在AI旁边当监工盯着它一行一行写、一遍一遍纠正现在更像是在给AI做入职培训把项目里那些不成文的规矩一条条显性化然后让它自己干活、自己遵守。这种工作流的迁移比想象中深刻。5.1 工作流的变化从逐行监督到例外管理过去用AI编程我的状态是高度警惕的甲方面对面审查。AI生成什么我审什么一边审一边改人的时间和AI的时间几乎一对一消耗。有了项目规则和AGENTS.md之后最明显的变化是常规任务的介入频率下降了。AI按照规则生成代码我先跑测试和计划再把精力集中在规则没有覆盖到的地方。规则没写的AI自由发挥了那才是需要我关注的地方。换句话说我把期望AI遵守的所有默认行为前置到了配置里之后的工作重点就从检查常规行为变成了处理边缘情况。这其实是软件工程里非常熟悉的思路把确定性的部分自动化把不确定性留给人类判断。AI编程的范式转换本质上就是把AI生成的每行代码都当例外变成符合规则的代码是常态违反规则的代码是例外。5.2 团队协作的新模式规则共建与版本化AGENTS.md另一个让我意外的价值是团队协作。以前项目里有些心照不宣的约定只存在于老员工脑子里新同事来了全靠缘分——运气好点问几句运气不好自己踩坑。而AGENTS.md把这些隐性知识变成了仓库里的文件AI和人类新人可以共享同一份入职手册。我们团队现在的模式是每个开发者在遇到AI理解不了但对我们来说是常识的约定时不是当场纠正AI就完事而是顺手回仓库里补一条规则。这样下次AI会遵守下次别的同事也会受益。规则文件从我个人的配置变成了团队的公共资产变更走代码评审历史进Git版本库谁改的、为什么改全都有迹可循。这个过程就像是在给队伍的经验库持续注资。单个经验的边际成本不高但半年积累下来整个项目能被AI正确理解的程度和服务体系建设完全不在一个量级。5.3 适合什么项目不适合什么说句公道话AGENTS.md不是所有项目都值得上。我自己的判断标准是看项目里可书写的规则密度高不高。如果你写的是探索性脚本、一次性工具、原型验证代码项目上下文很少今天写明天弃那给AI写规则文档就是浪费。反正每个文件都是独立的AI自由发挥的余地很大风险也不大。这类项目用裸的AI对话问几句够用了。但如果项目生命周期超过几个月团队多于一个人代码有清晰结构和风格约束那AGENTS.md的投入产出比就非常可观。尤其是那些有历史包袱、有性能瓶颈、有特殊规范的项目一份好的规则文件能让AI少踩无数坑。还有一类项目和特殊价值的是别人接手的项目。比如你毕业或离职交接原本只有你懂的背景知识终于有了一个承载的载体。AI和下一任开发者都能读到你的经验这才是真正意义上的知识传承。5.4 一次范式转换的实际账本最后算一笔账。以我最近在一个中型业务系统上的实践为例建AGENTS.md花了一个晚上大概3个小时把项目背景、命令、结构、常见坑整理成了文件。之后两周的使用结果对比很明显对话里重复解释背景的次数减少约八成AI生成的代码符合项目格式规范的比例明显提升因为违反约定返工的比例有所下降我自己的Review时间大约省下三成一个最惊讶的AI主动在改动旧模块时提醒该目录有历史约束请确认这在以前从未发生过代价是每次项目有重大变化时需要花十几分钟维护规则文件。这点维护成本和它节省下来的双向沟通成本相比可以说是微薄之力但收益实实在在。我在修了几次AGENTS.md之后最大的体会是写这份文件的重点不是教AI怎么写代码而是逼着自己把项目的隐性知识显性化。AI只是第一个受益者真正受益的是整个项目的可理解性。很多时候你以为AI不够聪明其实是你的项目本身混乱到连人都得猜更别提模型了。AGENTS.md某种程度上倒逼了项目的自我梳理。如果你正在用AI写代码且总觉得它不够懂你不要急着换更大更新的模型。先在仓库里写下一份AGENTS.md把你最希望AI记住的那几条规则告诉它。我打赌仅这一件事就能让AI的表现再上一个台阶。