不跟你绕圈子这篇文章的出发点是我这段时间反复踩到的一个问题我把同一个项目背景跟AI编程工具讲了不下十遍每次新建会话它都像第一天上班一样对我的代码库一无所知。模型的对话窗口装得下上下文但它记住的东西在你关掉窗口那一刻就清零了——这就是无状态模型最别扭的地方。后来我试着把项目的关键约定、命令、架构边界写进一个叫 AGENTS.md 的文件放进仓库根目录让工具在每次会话开始时自动读取效果是立竿见影的。现在我把这套思路完整梳理一遍从无状态模型的底层逻辑讲到 Memory 工程的实现路线再落到 AGENTS.md 的实际写法希望能帮到那些还在靠复制粘贴提示词撑场面的同学。1. 无状态模型的工作方式每次对话都是从零开始1.1 上下文窗口与令牌模型的瞬时记忆要理解 AI 编程里的记忆问题先得说清楚大模型的工作机制。你每次跟模型说的话会被切成若干个令牌一块一块喂进模型里。模型只在这一轮交互中看着这些令牌做出预测下一轮重新开始——严格来说你的上一句话并不存在于模型的脑子里它只是被临时拼接到了当前对话窗口里让它看起来像是记得。你可以把大模型想象成一个记忆力极差但理解力极强的新同事你跟他说完需求转身就走他听懂了你说的每句话但走出会议室就把重要细节全忘了。这个机制带来的直接后果就是对话窗口里的内容决定了模型能想起什么。命令是pnpm build还是npm run build、测试框架用的是 Vitest 还是 Jest、目录里哪个文件夹才是核心业务代码——这些信息如果不出现在当前窗口里模型就永远猜不到。它只能靠猜和泛化。猜对有运气成分猜错就浪费时间。很多人在用 AI 编程工具时觉得它智商忽高忽低其实多半不是模型变笨了而是它在缺少关键上下文的情况下做了太多假设。1.2 项目场景下的记忆缺失为什么同一个 Bug 要解释两遍我在某个模拟项目X后来被我用来做 AGENTS.md 验证的目标项目上就遇到了非常典型的情况。这个项目的测试要用pnpm test --filter core单测涉及 mock 数据库连接集成测试又依赖本地 Docker 容器。我前面已经跟某个 AI 编程工具解释过三遍每次它听完都能给出不错的建议但下一次会话我再让它总结一下测试策略它就开始用通用答案糊弄让我npm test还让我检查环境变量对不对就是不知道这项目真正的测试链路长什么样。这种重复解释的浪费看起来好像只是多打了几段字实际成本很高。你每开一个新会话都得花时间把项目背景、技术栈、目录结构、常用命令、当前要解决的问题重新叙述一遍。而且人描述一个复杂系统时是很容易遗漏细节的你忘了说这个项目里配置文件的优先级是 env 覆盖 yaml模型就会给你一个在特定环境根本跑不通的临时方案。久而久之你会开始下意识怀疑AI 编程是不是只适合那些结构简单、文档齐全的模板项目答案当然是否定的。问题不在AI 能不能记住而在谁来负责记住。既然模型天然无状态那我们要做的就是把记忆从模型脑子里挪到文件系统里——用一个模型每次都能自动读到、而人类也能方便维护的地方。这就引出了 Memory 工程的核心思路。2. Memory 工程的两种路线检索增强与声明式配置2.1 检索增强路线建知识库让模型主动查资料Memory 工程这几年发展出两条主流路线。一条是检索增强也就是我们常说的 RAG。它的做法比较重把项目文档、代码注释、历史 Issue 信息全部抽取出来做向量化处理存进向量数据库。模型每次回答问题之前先用相似度检索把相关性最高的片段捞出来拼进当前的上下文里。RAG 的优势在于扩容性好你给它塞再多的历史文档它都能检索得动而且适合处理非结构化的零散信息比如某个老模块的内部设计文档、某个用户反馈里的历史问题描述。但缺点也很明显整个链路里牵扯的东西太多你得维护向量库、选择嵌入模型、设计检索策略还要处理检索结果不准确带来的误召回。对一个中小型项目来说这一套基建的运维成本可能比项目本身的复杂度还高。我并不是否定 RAG 的价值只是觉得项目级记忆的大部分需求其实不需要这么重的方法。2.2 声明式配置路线把项目上下文写进仓库另一条路线是声明式配置思路和 RAG 完全相反。它不搞向量化不依赖语义检索而是直接写一份结构化的项目说明文件放进仓库里让 AI 工具在每次进入项目时自动读取。这份文件不长通常一个上百行的 Markdown 就能覆盖项目最核心的约定。工具的加载机制一般是启动会话时扫描项目根目录如果找到类似 AGENTS.md 这类约定文件名就把它注入到当前上下文窗口里模型从第一句话开始就知道了项目背景。这个做法的底层逻辑很有意思。你想想给项目写说明书这件事传统团队里一点都不陌生——README 就是干这个的。但 AGENTS.md 和 README 的最大区别在于它服务对象不是人而是 AI。这意味着它的语言基调、信息组织方式、层次结构都要以机器读懂、人好维护为最高优先级而不是像 README 那样讲究叙事流畅和界面友好。2.3 两种路线的对比与适用场景我用一个表格把两种路线放在一起看会更清楚维度检索增强RAG声明式配置AGENTS.md信息载体外部向量库、非结构化文档仓库内的 Markdown 文件加载时机每轮按需检索每次会话开始时自动注入维护成本需要维护检索基建直接编辑 Markdown适用规模文档量极大、信息分散的场景中小型项目、团队约定型项目实现歧义可能出现误召回写什么就是什么上下文占用按当前问题动态拼装固定占用一定窗口从实际体验来说RAG 更适合解决外部知识怎么找声明式配置更适合解决项目内部约定怎么同步。而 AI 编程场景里模型面对的绝大多数问题恰恰是项目内部的问题目录结构是什么、构建命令是什么、哪些文件不能动、测试环境怎么起。这些信息是有限、明确、结构化的写进一个文件里反而比丢进向量库里更直接、更可靠。AGENTS.md 的价值就在于此它让项目本身的姿势变成可检索、可版本管理、可评审的资产。3. AGENTS.md 的设计哲学写给AI看的项目说明书3.1 文件位置与加载机制为什么放根目录AGENTS.md 这个名字虽然是近期才流行的但它背后的思路在 AI 编程圈里已经发展了很久。约定是把这份文件放在项目根目录上游的编程工具在启动一个项目会话时会主动去查找并读取它。根目录这个位置选得非常巧妙——不会弄丢不会混淆是任何开发者进入项目时必然经过的地方。工具加载时采用了一种聪明的机制在窗口顶端注入这份文件让它成为模型最先看到的项目背景板。这就像给新入职的同事一份入职手册他不熟悉你们公司的茶水间在哪、打卡规则是什么、项目代码仓库怎么拉取但只要在第一天把这些写清楚之后所有的协作都会顺畅很多。AGENTS.md 的作用就是这份入职手册。而且因为它在仓库里任何修订都走正常的代码评审流程不会出现你口头跟 AI 说过的规矩转身就忘了的情况。3.2 字段拆解一份可复用的 AGENTS.md 模板下面是我实际在用的一份模板结构你可以直接拿来做底子再根据自己的项目增删# AGENTS.md ## 项目定位 一句话说明项目是做什么的目标用户是谁核心业务场景是什么。 ## 技术栈速览 - 主要语言与框架 - 关键的运行时依赖可选 - 项目脚手架/初始化方式可选 ## 目录结构速览 按顶层目录分组说明 - src/业务代码主目录应用层逻辑都在这里面 - packages/core/核心模块别乱动依赖关系很复杂 ## 常用命令 - 安装依赖: pnpm install - 本地开发: pnpm dev - 单元测试: pnpm test --filter core - 构建打包: pnpm build ## 代码风格约定 - 禁止在业务代码里出现 console.log - 组件 API 全部用 TypeScript 类型声明 - 提交信息遵循 conventional commits 规范 ## 架构边界说明 - 数据访问层必须走 repository 封装禁止直接拼 SQL - 领域服务内不要直接调用第三方 HTTP 客户端通过接口注入可选 ## 已知陷阱 - 配置文件优先级env yaml改配置前先确认环境变量是否存在 - 内置的 API 网关在某些环境需要额外配置 CORS 头这份模板的核心点在于每个字段都是事实描述不是操作指令。比如数据访问层必须走 repository 封装——这是在告诉模型项目的架构边界长什么样而不是叫它现在就去重构某段代码。模型在后续提出建议、生成代码时会自然地遵守这些边界规则。3.3 为什么用 Markdown 而不是 YAML 或 JSON有些人可能会问既然是给 AI 看的配置那用 YAML 或者 JSON 不是更结构化吗我的看法刚好相反——AGENTS.md 最好是 Markdown。第一AI 模型对自然语言的理解能力远强于对键值对结构的理解能力。自然语言里可以描述哪些情况要避免什么时候不要做 X这种模糊但重要的规则代码注释里常见的场景化提醒用 Markdown 表述起来比 YAML 稀松自然得多。第二Markdown 对人类友好。AGENTS.md 不是写完之后就永远封存的机器配置它是要长期维护的文档。团队里的新成员要读、架构师要评审、普通开发者也可能顺手改一句。你总不能让所有人为了改一行配置去学 YAML 语法。第三Markdown 的 diff 结果是可读的。用 Git 管理 AGENTS.md 时每次修订的差异会清晰地显示出来哪一行规则变了、谁改的备注也一目了然。YAML 文件虽然也能 diff但缩进和列表嵌套经常让 diff 变得乱糟糟不利于 review。4. 从零散提示词到 AGENTS.md 的实战改造记录4.1 改造前的痛点我为什么受够了提示词模板在给模拟项目X写 AGENTS.md 之前我用的是另一套土办法维护一个超长的规则提示词文档每次要用 AI 帮我改代码的时候先把那段几百字的内容粘贴进对话里再继续问问题。这个办法初期有效但越用越难受。首先那段提示词写得太长每次占用的上下文窗口都不小。模型一进来先读你粘贴的 1500 字项目背景再回答你的问题回复质量反而被稀释了。其次提示词是一次性的记忆——它不在项目仓库里脱离了当前对话就毫无价值。我换了台机器、换了台电脑提示词不在手边一切从头再来。更关键的是提示词没有版本维护我说改了规则但旧规则在复制粘贴时往往没删干净模型经常被前后矛盾的指示搞糊涂。4.2 改造步骤盘点、归纳、写入、验证整个改造流程我总结为四步非常朴素但在模拟项目X上验证效果极好。第一步盘点项目知识。我先把项目里只有老人才知道的信息列出来启动命令、测试范围、核心模块边界、哪些代码路径禁止绕过既有封装、容易踩坑的环境配置。列的时候有个判断标准——凡是需要跟新人解释两遍以上的内容都应该进 AGENTS.md。例如这个项目的核心计算模块在packages/engine/src里其他模块不要直接 import 它的内部模块必须走公开 API——这种内容你要是只靠口头说新来的开发者十有八九会漏。第二步归纳分类。盘点出来的信息有十几条不能平铺直叙堆在一个文件里。我按照项目定位、技术栈、目录结构、命令、风格约定、架构边界、已知陷阱分了七块每块只写核心的、不会频繁变动的规则。像依赖安装用 pnpm这种写一次就好像某个 API 的响应字段现在改了名字这种临时信息就不放进 AGENTS.md直接在工作对话里说明。第三步写入仓库。根目录创建一个AGENTS.md把整理好的内容填进去。这里我通常会刻意控制篇幅控制在 120 行以内。因为 AGENTS.md 会被注入到模型上下文的开头太长了会挤占后续任务指令的空间反而降低整体回复质量。如果一个项目的信息量实在太大我建议按目录拆分多份而不是硬塞进一个超大文件下一节会讲这个。第四步验证迭代。写好之后我在两个场景里做了验证。第一个场景是新建会话让 AI帮我列出这个项目的所有可用测试命令——它准确回答出了pnpm test --filter core和相关的集成测试脚本这个结果要是之前靠猜几乎不可能。第二个场景是让它基于存在的 repository 封装风格的代码习惯为某个新模块写一段数据访问代码结果生成出来的代码确实主动使用了Repository接口没有直接操作数据库连接。这说明 AGENTS.md 里的架构边界确实被模型读取并遵守了这比我预想的效果还要好。4.3 踩过的坑AGENTS.md 写作的常见失误写 AGENTS.md 和写文档一样也会踩坑。我把自己的经验教训总结几条坑一写成了操作手册而不是事实描述。我第一版里写请先运行pnpm install结果模型真的每次都先执行安装——它把这句话理解为必须执行的步骤。把表述改掉改成安装依赖使用pnpm install语气中性它才会把它当作一条可用知识而不是一个前置行动指令。AGENTS.md 的核心语法不是做 X而是项目里存在 X。坑二混入一次性信息。当时我把某个临时调试环境变量也写了进去结果后续会话里模型反复提这个变量反而干扰了正常开发。临时性的、跟当前任务绑定的信息留在对话里说就行别污染项目级的记忆文件。坑三和 README 重复。AGENTS.md 不是 README 的复制品。README 面向人类讲项目是什么、怎么部署、怎么参与贡献AGENTS.md 面向模型讲的是你在这个项目里帮忙时要遵守的规矩。两者重复的部分可以保留但立场一定要分开——我会在 README 里写项目简介在 AGENTS.md 里写模型在这个项目里需要注意哪些边界。5. AGENTS.md 的边界与未来记住项目的下一步5.1 多文件与分层配置当单文件装不下的时候AGENTS.md 放在根目录覆盖的是整个项目的全局约定。但实际项目往往比这复杂某个子包有自己特殊的构建流程、某个目录有独立的技术栈、某些 Legacy 代码有外人不知道的历史包袱。让根目录的 AGENTS.md 强行描述所有这些细节文件会迅速膨胀模型上下文里的噪声也会越来越大。我的做法是分层配置根目录放精简版 AGENTS.md只描述全局约束然后在需要额外说明的子目录里比如packages/core/、server/、scripts/分别放自己的局部说明文件让模型在专注子模块时能读取到更精准的信息。不同编程工具对这种局部文件的命名约定可能略有差异但思路是通用的。每一层文件都是项目状态的事实描述叠加起来就是一套完整的项目知识图谱。5.2 与执行工具的联动记忆不只是读取AGENTS.md 解决的是模型读得懂项目但 AI 编程工具真正完成一段代码改动还需要执行命令、读写文件、检查测试结果。这一系列动作如果能在会话里被自动记录和回溯就构成了更强的记忆闭环。现在有些工具已经开始把会话内的执行历史、命令记录、文件变更作为可回溯上下文注入到后续会话中AGENTS.md 则可以理解为这种行为的静态初始值。我不太看好让 AGENTS.md 承担实时状态存续的责任——它是声明式文件是项目背景版的快照不是当前进度的日志。如果你希望模型在中断之后还能接着上一次的任务干正确做法是让工具记录会话摘要或者在下一次对话里主动提供一个简短的状态描述而不是反复往 AGENTS.md 里塞现在正在做 XX这类临时信息。5.3 团队协作中的维护体验让记忆成为团队资产AGENTS.md 最让我满意的地方是它把个人记忆变成了团队资产。以前每个人对项目的理解都藏在自己脑子里带着各自的偏差。现在项目根目录就有一份公开的、给 AI 看的项目白皮书。新人入职时直接读一遍 AGENTS.md带教成本能低一截。产品迭代时如果改了架构约定顺手更新 AGENTS.md代码评审时大家也能看到这个变化整个团队对项目的理解始终保持一致。当然它的维护也需要配套习惯。我的经验是任何代码评审都顺手看一下 AGENTS.md 是否需要同步更新。如果某个约定改了但你忘了更新AI 又开始猜规则AGENTS.md 就成了一座断桥——看起来在实际已经失效。这个文件的价值与它的准确性直接挂钩维护不好比不写还难受。我在实际使用中最深的体会就是AI 编程的下一个阶段拼的不只是模型的聪明程度更是开发者对项目记忆的工程化管理能力。从无状态模型到 AGENTS.md 声明式配置本质上是把让 AI 懂我这件事从一次性的提示词对话变成了一套可版本管理、可团队共享、可持续演化的仓库资产。如果你现在还被每次重新解释项目折磨我建议你今天就动手花半小时给自己的主力项目建一份 AGENTS.md。先别追求完美从最常用的命令和最容易踩的坑开始写。另一个实用的启动技巧是找个 AI 编程工具让它根据你的仓库现状自动生成一份初稿你在此基础上削减和修正——这个过程本身就是一次项目知识的复盘做完之后你对项目的理解比之前又深了一层。