这两年我团队里最大的变化不是换了多少工具而是 AI 辅助开发的范式整体转了一圈从把大模型当“一次性便签”到如今把 Memory 工程当成一等公民。我见过太多项目明明已经接入了 AI 编程助手却一直在原地打转——同一条业务规则上午刚让模型改完下午新会话又要从头讲一遍同一个模块的历史决策换个对话窗口就全部失效。问题本质就一句话无状态模型本身不是错错在没人替它做记忆工程。所谓的“范式转换”核心就是从“无状态模型”走向“有上下文的编码代理”而 AGENTS.md 这种声明式配置文件正是当前最容易落地、性价比最高的一层记忆载体。它把项目应该被模型知道的信息固化成仓库根目录下的规格文件让 AI 在每次新会话里都能稳定看到同一张“图纸”而不是靠开发者反复讲、模型反复猜。这篇文章我会先从无状态模型的痛点讲起再拆 Memory 工程的具体形态最后用一整份可直接抄走的 AGENTS.md 结构收尾适合正在做 AI 编码工具落地的开发者、技术负责人也适合想搞清楚“AI 怎么才能记住我项目”的独立开发者。1. 为什么“无状态”成了 AI 编码路上的隐形天花板1.1 上下文窗口只是一次性缓存不是业务记忆几乎所有主流大模型在设计上都基于无状态推理每一次生成请求都是独立的模型只能依靠当前输入和上下文窗口里的内容来给出回答。上下文窗口看起来很大动辄几万甚至几十万 token但它本质上是一块“用完即弃”的便利贴板。会话一关、窗口一换前面发生过的一切就跟没发生过一样。这就带来一个非常反直觉的现实AI 编码助手的能力上限不取决于模型本身有多强而取决于每次会话你愿意塞多少上下文给它。窗口塞得越多模型越容易被无关信息干扰窗口塞得越少它对项目的理解就越浅。早期我们用 AI 改小文件、写单点函数感觉特别爽是因为这些问题不需要太多项目背景。可一旦进入多文件重构、跨模块联调、老系统维护这类工作无状态模型的短板立刻暴露——它记不住你三天前拍板的架构方向也记不住上个月刚定下的技术选型。我常用一个类比给团队解释这就像你每天请一位新来的实习生帮忙这位实习生非常聪明但每天早上都要你把公司的规章制度、项目背景、代码规范从头讲一遍。你讲得越细他干得越像样你不讲他就按自己的通用常识瞎发挥。而 Memory 工程要解决的正是“让他自己去看那份永远存在着的员工手册”。1.2 我在迭代中反复踩到的三个具体场景场景一跨会话的决策漂移。A 同学在周一把某个模块从单体函数重构成策略模式跟 AI 助手讨论得很细当时模型完全理解了意图。周二新开一个会话让 AI 给这个模块加一个新分支它却基于自己的“通用最佳实践”提出要引入插件机制差点把周一的方案推翻。类似的问题不是一次两次而是每一轮大规模迭代都会出现。场景二同一段背景知识被重复解释。项目里用了一套自研的配置加载框架每次让 AI 改相关代码都得先把框架的加载顺序、权限模型、常见坑位写进提示词。同一个解释我可能在十个会话里写了十遍效率损耗极大。更糟的是不同会话里解释的详细程度还不一样今天少讲一个细节明天模型就会交出完全不同的实现。场景三大型代码库里的定位成本飙升。代码量一上来AI 在无状态模式下会频繁“迷路”。它不知道哪个文件是核心入口、哪些目录已经废弃、哪几条公共方法是被全局引用的。你让它“找到订单状态的流转逻辑”它可能从控制器翻到工具类最后给出一个看似合理但根本没被调用的修改点。不是模型笨是它真的不知道项目地图长什么样。这三个场景指向同一个结论AI 编码的下一个瓶颈不再是大模型的推理能力而是它对项目的持续理解能力。谁先把这段“长期记忆”建起来谁就能在 AI 辅助开发里拉开差距。2. Memory 工程的基本盘AI 到底要记住什么、怎么记2.1 记忆不是把聊天记录粗暴地塞进上下文一说要给 AI 加记忆很多人第一反应是“把历史对话保存下来下次继续传”。这个做法在小型个人项目里勉强能用工程上却问题重重历史对话里充斥着试错、废话和被否决的旧方案直接塞回上下文不但浪费 token还会把模型带偏。真正的 Memory 工程要做的是把“发生过的事情”提炼成“应该长期成立的约束”然后按需、分层地喂给模型。我的经验是先把记忆分成三类再分别设计存储与检索方式。否则很容易陷入“什么都想记最后跟没记一样”的窘境。2.2 三类记忆形态场景记忆、决策记忆、结构记忆这三类记忆各有各的载体和使用时机放一起对比如下记忆类型内容举例推荐载体注入时机场景记忆项目语言、框架版本、启动命令、测试命令、部署方式AGENTS.md、README 约定每次会话开始固定注入决策记忆技术选型原因、架构红线、禁止改动区域、已否决方案决策记录文档 向量索引遇到相关模块时检索注入结构记忆目录职责、关键文件职责、模块之间的依赖方向文件头注释 自动生成的索引涉及具体文件修改时局部注入我实际踩过的坑是很多人只做场景记忆觉得“只要 AI 知道怎么跑起来就够了”。但真正决定代码质量的其实是决策记忆和结构记忆。比如“为什么当时没有用消息队列”“库存扣减为什么不允许先更新再锁”这些隐藏知识一旦丢失模型就会按通用套路重新设计轻则风格不一致重则直接违反系统在极端场景下才暴露的约束。2.3 向量检索与语义检索海量上下文里的拾取器当项目文档超过一定体量把所有内容都塞进上下文窗口就不现实了。这时候需要引入向量检索把结构化文档、代码片段、历史决策记录切成小块做向量化后存入向量库新会话开始时把当前用户需求和代码变更信息也向量化通过相似度匹配只把最相关的几块记忆拉进上下文。听上去很玄但本质上就是一个“语义版 grep”。你问“订单状态机在哪里”它不会傻傻地匹配关键词“订单”而是能把“状态流转”“支付回调”“取消流程”这些语义相关的代码块都捞出来。配合上层的 AGENTS.md 这类强声明文件静态记忆负责“约定”向量检索负责“发现”两者互不冲突。这里要特别提醒向量检索召回的结果不是永远可信。它可能搜到一段已经废弃的旧实现也可能因为语义相近把两个不同模块的代码混在一起。所以在设计上静态的 AGENTS.md 规则优先级一定要高于动态检索结果冲突时以静态声明为准。没有这层仲裁机制检索式记忆反而会引入新噪声。3. AGENTS.md 的定位从“每次现问”到“宣告即事实”3.1 根目录下的声明式规格意味着什么AGENTS.md 这个名字是近几年在 AI 编程社区逐步标准化出来的约定在代码仓库根目录放一个名为 AGENTS.md 的纯文本格式文件AI 编程助手打开项目时会自动读取它并把它作为理解项目的最高优先级上下文。你可以把它理解为项目给 AI 看的“入职手册”。关键在“声明式”三个字。文件里写的不是“请帮我做某事”而是“这个项目是什么、有哪些必须遵守的规则”。AI 每次进入项目都先读这份文件相当于每次新会话都自动加载了同一个项目世界观。不管是碰过这个项目的开发者还是第一次接触仓库的 AI看到的都是同一套事实。这从根本上消解了我前面说的决策漂移问题——不是靠人记得去交代而是靠文件永远戳在那里。3.2 AGENTS.md 与普通文档、提示词文件的本质区别很多人问这不就是写个说明文档吗还真不是。普通 README 面向人类阅读强调叙事性和可读性AI 读起来反而不够“可执行”。而临时提示词文件面向某一次特定任务不具备持久效力。对比维度README 文档临时提示词文件AGENTS.md 声明式配置主要读者人类开发者AI 当前任务AI 代理人类也可读生命周期长期存在但不严格单次对话长期且自动加载内容密度介绍性、叙述性高密度任务指令高密度约束与事实被 AI 利用方式需要人主动提供当前会话有效每次进入项目自动读取优先遵循这里有个容易被忽略的技术细节AGENTS.md 之所以比普通文档管用除了内容设计之外还在于工具链会把它识别为“指令文件”在构建上下文时给予特殊权重。同样的内容放进一个随便叫 notes.txt 的文件里AI 不一定会把它当必须遵守的规则。所以文件名和文件位置本身就是一种协议不建议自作主张换成别的名字。3.3 设计原理声明式优于命令式命令式配置长这样“先打开 src/order 目录然后找到 Service 文件把第 80 行的逻辑改为异步再执行测试命令。”这套指令只对当下这次修改有效如果代码结构与描述不符模型就会卡死。而且这类指令本身就是一种“代码”需要随着项目变化频繁改维护成本极高。声明式配置则不关心完成路径只关心边界和事实。它写的是“订单模块的库存操作必须走库存服务视图层不允许直接改库存表。”至于模型具体怎么组织函数、拆几个类那是它自己的事。把“方法”放给模型把“约束”留给自己这才是 AGENTS.md 的正确使用姿势。4. 从零搭一块自己的 AGENTS.md结构与落盘细节4.1 目录位置与配套文件的摆放核心文件一定放在仓库根目录命名精确为 AGENTS.md。子目录里也可以放局部规则做法是对应模块目录下放 AGENTS.md只描述该子模块的约定。这种做法在处理大型 monorepo 时特别有效根文件描述全局命令和整体架构子目录文件描述各自领域细节二者形成树状记忆结构。我目前的推荐布局根目录 AGENTS.md全局命令、技术栈、编码红线、跨模块约束services/order/AGENTS.md订单领域专用规则、关键实体、不允许破坏的事务边界docs/decisions/每个重大技术决策一个文件作为决策记忆主载体scripts/build_index/负责生成代码结构索引供检索式记忆使用4.2 一份可直接改用的 AGENTS.md 核心模板下面是我在模拟项目 X 里实际用过的骨架字段不多但每一项都经过了实战检验# AGENTS.md ## 项目一句话目标 B2C 订单与库存管理系统核心目标是保证订单状态与库存扣减的一致性。 ## 运行环境与技术栈 - 后端Go 1.22 PostgreSQL 16 Redis 7 - 前端Vue 3 Vite - 基础设施单机 Docker Compose 起步禁止引入未评估的额外中间件 ## 常用命令 - 启动后端make dev - 运行全部测试make test - 数据库迁移make migrate-up - 代码检查make lint ## 目录结构与职责边界 - cmd/ 只放进程入口不允许放业务逻辑 - internal/order 订单领域支持库依赖只向内 - internal/infra 底层基础设施不允许反向依赖业务包 - pkg/ 对外可复用能力必须保持无业务语义 ## 编码红线违反即打回 1. 库存预占必须与订单创建在同一数据库事务内 2. 视图层/接口层禁止直接访问 Redis 与数据表 3. 所有对外消息必须走统一的消息封装禁止裸发 JSON 4. 已写入 docs/decisions 的架构决策修改前必须先讨论 ## 对外接缝 - 订单创建成功后发布 OrderCreated 事件由消息队列消费 - 库存回滚与订单取消必须可重入事件消费端要做幂等 ## 模型交互建议 - 涉及多文件改动时先 README AGENTS.md再打开具体文件 - 修改公共接口时先搜索调用方再动签名4.3 常见反模式与自检清单写法上的坑比很多人想的多。我至少踩过这几类第一种是写成了“代码生成器说明书”。比如“把 controller 拆分得更细”“多用设计模式”这种抽象要求只会让 AI 自由发挥产出风格极不稳定。正确做法是给可判断的标准“函数超过 60 行必须拆解”“禁止在 service 层暴露原始 DB 连接”。第二种是信息过时。AGENTS.md 里写的命令和目录结构一旦项目升级后没有同步更新模型就会拿着一份过期地图干活。我现在的做法是把“命令同步维护”列为代码审查的必检项改依赖、改目录时同步改 AGENTS.md。第三种是规则太多互相矛盾。几十条红线堆在一起模型要么顾此失彼要么干脆选择性失明。建议核心红线控制在 5 到 8 条之间能合并的语义尽量合并让每一条都是真正会被违反且代价高昂的约束。自检清单我一般用四条第一这份文件能否让完全不了解项目的人在 5 分钟内恢复大部分上下文第二是否每条规则都是可验证、可通过代码或现象观测的第三删除其中任意一条是否会对 AI 输出质量造成明显影响第四文件里的命令和目录结构当前是否都是真实存在的。5. 让记忆“活”起来静态配置文件之外的检索与索引5.1 静态文件覆盖不了 10 万行代码AGENTS.md 在中小型项目里是“主记忆”但到大型系统里再详细的声明式文件也没办法把每个业务模块的细节都写进去。这时候就需要引入第二层记忆——检索式记忆增强。把核心业务代码的头注释、关键函数说明、已归档的架构决策文档统一做向量化建立项目专属的知识库。我习惯把这一层叫“记忆的缓存层”。它不追求全量记忆只追求“模型遇到具体问题时能把最相关的记忆捞进来”。比如用户问“支付回调失败怎么处理”检索层返回的不只是文件路径而是那几个和支付状态流转相关的函数的注释与历史决策让模型在动手前先看到上下文。5.2 动态上下文注入与分层采样策略动态注入不是把所有检索结果一股脑塞给模型那样会撑爆窗口且引入大量噪声。我的采样策略是按四个优先级执行第一优先级AGENTS.md 根配置与对应子模块配置强制注入第二优先级用户本次会话里明确提及的文件和符号直接注入第三优先级向量检索召回的相似代码块与决策记录按 top-K 截断第四优先级通用框架知识、第三方库文档只在出错时补充这种分层设计的效果是静态记忆给出边界自动检索补充细节用户需求决定方向。三者合起来模型看到的上下文量不大但每一段都是“当前任务真正用得上”的。5.3 记忆一致性配置文件与检索结果的冲突仲裁动态检索最危险的场景是检索出来的旧代码和 AGENTS.md 里的新规则打架。比如 AGENTS.md 明确规定“订单模块不允许直接访问库存表”但向量库里还躺着一份旧代码注释写着“库存扣减可在订单服务内完成”模型万一采信了后者就会越界。我在实践里定了一条硬规则静态声明优先级永远高于检索结果。一旦出现冲突模型必须按 AGENTS.md 执行并在回复里明示“检查到检索结果与项目红线不一致已忽略检索信息”。同时检索索引要定期跟随代码变更重建最好在 CI 里增加一步索引更新检查确保向量库里不积累过期的“僵尸记忆”。6. 团队落地把 AGENTS.md 当代码资产管理6.1 让 AGENTS.md 参与代码评审与 CI 检查很多团队把 AGENTS.md 写完就丢在仓库里不管了这跟“配了代码规范但没人执行”没什么区别。更靠谱的做法是把它当成一份正式代码资产来治理。AGENTS.md 的任何改动都要走 MR/PR 评审评审重点不是语法而是“规则语义是否准确反映当前架构”。什么时候改依赖、改目录、改核心流程就要同步审视改不改 AGENTS.md。如果团队对规则一致性要求更高还可以在 CI 里加一份轻量校验脚本检查 AGENTS.md 中提及的路径是否真实存在、命令是否能被 make 识别、引用文档是否未失效。这套检查不需要多复杂一个几百行的脚本就能把“过期地图”的问题拦截在合入之前。6.2 从“个人习惯”到“团队约定”的推进顺序我在团队里推广 AGENTS.md 时没有一上来就号召所有人写文件而是分了三步走。第一步我自己在负责的模块里建好文件让模型的改动质量明显提升第二步拉着合作最密切的两三个人把约定暴露成“公开规则”提交信息里引用对应条目第三步在全组会里展示一组对比案例——同一需求有 AGENTS.md 的模块一次通过没配置的模块来回跑了四人轮。数据比任何宣讲都有说服力。推进过程中要特别警惕“为写而写”。如果团队的业务模块还不稳定、代码结构天天在变强行写一堆精细规则很容易天天维护。我的建议是先写稳定不变的底层事实架构红线等真正稳定后再沉淀激进地把临时结论写进 AGENTS.md 只会让配置本身成为一个新负担。6.3 我实测后的一些边界条件和经验心得聊点实操维度的心得。第一AGENTS.md 的密度要克制最好控制在 100 到 200 行之内的信息量太长之后模型对每条规则的注意力会明显衰减核心红线的“优先级权重”反而被稀释。第二子模块级 AGENTS.md 比根级配置更有惊喜因为业务规则越靠近源代码模型执行越准确。第三不要试图在 AGENTS.md 里写“禁止做某些事却不说替代方案”模型需要知道“不这样做那应该怎样”。另外一个容易被忽略的细节AGENTS.md 开头几句话非常关键。模型的注意力在加载文件时往往是线性扫描前面几条规则更容易被严格遵守。所以我会把最重要的红线放在前 20 行内让“仓库认知”最重的地基先进模型视野。我目前实测下来配合向量检索这批工程手段团队内的 AI 编码会话里重复解释项目的次数减少了大约七八成多文件改动被要求返工的比例也有了明显下降。说到底从无状态模型到 AGENTS.md 声明式配置本质上是在做同一件事把散落在人脑、聊天记录里的隐性项目知识转成机器可自动加载的显性结构。这份配置文件写得越精准AI 与项目的贴合度就越高而人类要做的只是守住那些真正值得固化的边界。