最近很多人都在聊 AI 编程绕不开两个词范式转换、Memory 工程。我在实际项目里折腾了几个月最大的感触是AI 编程的瓶颈早就不是模型本身而是我们怎么把项目记忆交给模型。你今天打开一个 AI 编程助手跟它说“帮我看看这个模块怎么重构”如果它连项目结构、技术栈、编码规范、历史决策都不知道效果大概率会稀烂。而解决这个问题最实用、也最近的路子就是从无状态模型走向 AGENTS.md 声明式配置。这篇内容我会把这套思路完整拆开为什么无状态是 AI 编程的最大障碍Memory 工程到底在“工程”什么AGENTS.md 怎么写才真正生效以及落地中会遇到哪些坑。如果你平时用 AI 写代码、带团队做 AI 辅助开发或者正在研究怎么让 AI 稳定输出而不是每次开盲盒这篇应该能帮上忙。1. 范式转换从“有问必答”到“项目协作者”1.1 无状态模型的死穴它每次都是“新人”传统的模型调用是无状态的我发一段 prompt它回一段结果我再发一段 prompt上一段聊了什么它根本不记得。聊天窗口里看起来“有记忆”其实是工具把历史消息重新拼起来再发给模型本质上是一种伪记忆只是把上下文塞回了输入端。放到项目开发场景里这个问题的杀伤力非常大。你让 AI 帮你改一个模块必须先给它讲一遍项目背景、目录结构、依赖关系、编码习惯。你上一次会话里叮嘱过的事情这次它全忘了。它帮你改了 A 文件改 B 文件时完全忘了 A 那边定下的约定于是一个文件一种风格改完比不改还乱。我经常跟人打比方无状态模型就像一个每次上岗都失忆的临时工。你每次喊它干活都得从自我介绍开始重新讲一遍公司制度它还未必听得进去。这种模式做一次性任务没问题翻译一句话、写段正则、解释个报错效果很好但碰到跨文件、跨模块、需要长期维护的项目它就成了项目里最不稳定的变量。AI 编程范式转换的核心就是要把这个临时工变成“读过入职手册、知道项目规矩”的协作者。注意我们不指望它记忆而是通过工程手段替它记忆让记忆成为项目资产的一部分而不是每次靠人肉重新喂。1.2 三个阶段看清范式转换的路径我梳理了一下 AI 编程的演进大致是三个阶段。第一阶段是 Prompt 工程时代。所有项目背景都塞进提示词里每次会话开头先粘贴一长段“角色 背景 规范 示例”希望模型在理解上下文后干活。这个阶段的问题很明显每次重复劳动、提示词越来越长、上下文越撑越满、规范还容易不一致。改一句规范所有会话里的提示词都要跟着改根本维护不动。第二阶段是 RAG 和工具增强。通过外部检索把相关知识拉进上下文或者通过工具调用读文件、查文档。相比纯 Prompt 工程这确实进化了一步AI 至少能“查资料”了。但它没有解决长期记忆的组织问题检索回来的东西不一定对、不一定是最新的高层架构决策这种抽象知识也很难被向量化检索稳定命中。第三阶段就是现在正在发生的声明式项目记忆。你提前把项目最重要的约定写进文件例如根目录下的 AGENTS.mdAI 工具启动时自动读取。配置本身是持久化资产可以进 Git、可以走 review、可以按目录层级逐级覆盖。这正是“AI 编程范式转换”的关键变化从“让模型花力气记住”变成“让工程替模型记住”。这个范式转换的本质是把记忆从模型的输入饲料变成项目的一部分。AI 不再是一个拿着空白脑袋进项目的过客而是一上岗就带着入职手册的成员。你的项目代码、文档、规范、坑位记录共同组成 AI 干活时的那套“脑外记忆”。2. Memory 工程AI 的记忆到底是怎么建起来的2.1 不是玄学是三层记忆结构Memory 工程这个词听起来唬人但落到工程上无非是三层记忆。第一层是工作记忆对应单次会话。模型在当前对话里能看到的上下文包括系统提示、历史消息、工具返回结果都算工作记忆。它的特点是实时、易失、有窗口上限。单次任务里能不能稳住取决于工作记忆够不够用。第二层是项目记忆对应跨会话、跨任务的持久化知识。项目用什么技术栈、架构边界在哪、哪些代码不允许动、之前踩过什么坑这些必须稳定存在不能因为会话结束就消失。项目记忆最适合的载体就是 AGENTS.md 这类声明式配置以及代码库本身的结构信息。第三层是全局记忆对应个人或团队的通用偏好。比如提交信息必须以动词开头、UI 文案不要中英混排、接口文档优先用中文写这些跨项目都适用的规则可以放在全局配置文件里让每个项目自动继承。从工程角度讲Memory 工程关注的是四件事什么时候写入记忆存在哪里怎么检索什么时机注入给模型。模型不是天然有状态的所以工程要替它补状态。很多团队一上来就搞向量库、做知识库其实大多数时候是把简单问题复杂化了。2.2 记忆载体的选型别一上来就上向量库我见过不少团队一听 Memory 工程就觉得要搭 RAG、要上向量数据库最后搞了半个月效果还不如直接在仓库里写个文件。这里我用自己的选型经验给个参考。文件型配置AGENTS.md、项目规范文档成本趋近于零可版本控制、可 diff、语义稳定、可人工维护。适合存放“必须严格遵守的少量规则”。代码索引 / 语义检索覆盖面广能快速找到“某段逻辑在哪”但你把架构决策写成代码注释以外的知识它是检索不到好结果的而且召回质量不稳定。向量数据库 / RAG适合处理大量非结构化知识比如文档库、历史工单、技术论文但重、贵、有延迟对“必须严格执行的规范类知识”往往还不如一条明文规则可靠。我现在的原则很粗暴规范性知识放文件长尾知识才考虑检索。一个项目 80% 的记忆需求不过是几十条核心约束。这些约束的价值在于“必须稳定执行”而不是“可能相关”文件型配置天然匹配。向量库适合的是知识库很大的场景而不是一个仓库几个模块的日常开发。2.3 写入、存储、检索、注入Memory 工程的四个环节Memory 工程不是只写一个文件就完了它有完整的链路。写入环节把散落在 README、代码注释、架构文档、团队口口相传里的规范抽出来变成显式的规则。很多人项目里有一堆“潜规则”新人问十遍才知道这些都应该被写进记忆。存储环节尽量用纯文本 Markdown 做真源因为它是人能读懂、机器能解析、Git 能对比的。检索环节工具启动时自动加载根目录和当前目录层级下的配置文件按路径匹配规则而不是全局一把梭。注入环节要控制加载量别把一份几万字的配置整包塞进去上下文会被吃干净。这四件事里面注入时机的把握最容易被忽视。我见过有人把 AGENTS.md 写成了五千字的项目说明书结果模型上下文被占掉一大截真正干活的空间反而缩水了。记太多和记不住是 Memory 工程的两个极端后面我会专门讲上下文预算怎么算。3. AGENTS.md 声明式配置实战把项目的“魂”写进文件3.1 为什么是 AGENTS.md而不是又长又臭的 PromptAGENTS.md 之所以流行核心原因是它符合“声明式配置”的思路。命令式 Prompt 是手术刀式地指挥模型你先读 A 文件再做 B 操作然后调用 C 函数而声明式配置只告诉模型项目是什么、边界在哪、什么绝对不能做、什么风格必须遵守。具体怎么做模型自己根据任务去规划。打个比方命令式 Prompt 是给 AI 一个步步紧逼的剧本声明式配置是给 AI 一个职场手册。剧本只能覆盖一条流程手册能覆盖一类任务。项目是活的任务千变万化只有把规则沉淀成手册AI 才能在不同任务里保持稳定输出。AGENTS.md 还有几个天然优势。它是纯文本可以进 Git可以走 code review可以在历史里追溯“这条规则为什么被加进来”。它可以做目录级分层仓库根目录放全局约束子目录里放局部规则深度越深约束越具体这正好契合真实项目的模块边界。而且社区已经有共识多数 AI 编程助手都认这个文件名跨工具通用性比单一工具的自定义配置文件好很多。我自己的习惯是AGENTS.md 放根目录docs/AGENTS.md 放更细的模块约束比根目录文件优先级高遇到局部规则和全局规则冲突时局部规则优先。3.2 一个可以直接抄走的 AGENTS.md 模板这里给出一个我目前用得比较顺手的模板结构大家可以直接改着用。# AGENTS.md ## 项目一句话定位 一句话说清项目是什么、服务谁、解决什么问题。 ## 核心技术栈 - 语言 / 框架 / 关键库 - 不堆全部依赖只写 AI 做改动时最需要知道的边界 ## 架构边界 - 模块划分各自职责 - 禁止跨层调用数据流方向 - 公共 API 变更需要额外小心 ## 编码规范 - 命名风格、文件组织方式 - 新增依赖前需要确认 - 测试要求什么改动必须补测试 ## 常用命令 - 安装 / 构建 / 测试 / lint / 格式化 - 给出真实的命令AI 才能自行验证 ## 历史决策与坑位 - 为什么不用某个库 - 之前踩过的坑以后不要重蹈覆辙 - 改动此处时容易犯的错误每一节下我建议只写“约束密度高的内容”而不是把所有细节都灌进去。比如“技术栈”一节写“前端用某框架组件放 src/components页面放 src/pages后端只提供 HTTP API禁止在后端代码里直接拼 SQL 模板”比写一大堆依赖清单有用得多。依赖清单会变架构边界才是稳定的。3.3 三条操作性原则少而准、可执行、能更新写 AGENTS.md 有一堆教训我总结成三条。第一条每条规则都要能被检查。你写“代码要优雅”AI 没法判断优雅你写“组件超过 200 行必须拆分并将拆分方案写在 PR 描述里”AI 就能照着执行。规则能被检查AI 才会真正遵守规则太抽象等于没写。第二条把“为什么”写进去但别写成论文。AI 面对一条孤零零的规则很难判断它是不是个玩笑如果规则后面补一句“因为之前出现过跨层调用导致循环依赖的事故”AI 就明白这条规则的分量了。但“为什么”控制在一两句话以内写太多配置会膨胀。第三条建立配置的“迭代仪式”。 AGENTS.md 不是写完就完事它应该跟着项目一起成长。每次你发现 AI 又踩了之前的坑或者你做出了一个新的架构决策都应该顺手更新配置。我在团队里的做法是谁往配置里加规则必须同时说明这条规则来自哪次事故不然 review 不过。4. 从无状态到有状态一个项目级记忆的最小闭环4.1 最小闭环的六个步骤这套方法不需要任何复杂基建按六步走就能让 AI 从“失忆外包”变成“懂项目的老员工”。盘点记忆源把 README、架构文档、代码里的 TODO/XXX、你脑子里但没写下来的项目规矩全部列出来。提炼约束从中挑出真正影响 AI 行为的规则控制在三十条以内按优先级排序。写入 AGENTS.md放到仓库根目录保证能被工具启动时自动读取。做一次复述验证新建会话让 AI 总结项目架构看它说的是不是你写的内容。在真实任务里校验跑两三个典型任务观察 AI 是否真的遵守了规则。任务后回填把新踩的坑、新定的规矩更新进配置闭环继续。这套闭环的本质是把记忆从“人的脑子里”搬到“项目的文件里”再从“文件”转成 AI 的行动准则。它不是一次性动作而是一个持续迭代的循环。4.2 实操记录模拟项目 X 的配置全过程我拿手头一个模拟项目 X 举例。它是一个跨平台系统前端有桌面和移动端后端有两组服务中间靠一层共享协议包通信。团队分散仓库里之前没有任何 AI 配置。第一轮我先让 AI 总结项目架构。结果输出非常空甚至编出了一个仓库里根本不存在的目录。原因很直观项目太大模型看不完所有代码又没有项目地图只能靠编。我给这个阶段起了个名字叫“盲人摸象模式”。第二轮我写了一个精简版 AGENTS.md内容包括项目定位、四个核心模块的职责、共享协议包的边界、禁止后端直接改前端状态、新增依赖必须走审批、所有接口变更必须同步更新协议文档。写完以后新建会话复述验证AI 这次能准确说出模块划分、数据流方向和关键边界没有再出现幻觉目录。第三轮做了一个真实重构任务把某模块的命名从 Handler 改成 Processor。无配置时AI 改到一半停住还顺手改了不该动的公共 API有配置后AI 先定位边界文件输出完整修改清单并明确标注哪些文件已经出了模块边界、需要人工确认。这个反差让我确定AGENTS.md 不是摆设它是能直接改变 AI 输出质量的。配置前后的行为差别我整理成了下面这张表无配置回答依赖猜测容易举出不存在目录跨文件改动频繁越界风格随模型心情波动有配置先复述项目地图再动手改动范围自觉限定在模块内风格、命名、测试要求统一4.3 上下文预算一次注入多少合适AGENTS.md 不是越长越好。模型上下文窗口是有限的配置占用了空间留给代码分析和对话史的空间就会缩小。最常见的估算口径中英文混排时1K 个字符大约对应 300-600 个 token纯英文接近 250-300 token。假设你的模型上下文是 100K tokenAGENTS.md 建议控制在 2K-8K token 之间约合 4000-8000 字符这已经足够覆盖绝大多数项目的核心约束了。如果超过这个量项目配置基本就该拆层了。我实际分配上下文预算的经验比例大概是系统层指令 工具定义2% - 5%AGENTS.md 项目记忆5% - 10%会话历史与用户输入20% - 40%代码文件/检索结果40% - 60%预留余量至少 10%在预算有限的前提下写配置要用词精准去掉所有废话。“不要使用全局可变状态”就比“请尽可能避免在应用中使用会影响系统稳定性并且难以追踪和调试的全局状态这种模式在某些情况下可能会引起不可预见的副作用”有效一万倍。配置是给模型读的约束不是给老板看的美文。5. 常见问题与排查技巧实录5.1 高频问题速查表我在多个项目里帮人调过 AGENTS.md高频问题基本就这几类先给个速查表现象可能原因排查与解决AI 完全无视配置里的规则规则太笼统或与代码现状矛盾用新会话做复述验证看配置有没有被读入把规则改成可检查的具体行为配置太大上下文不够用模板堆砌、信息密度低精简到核心约束根目录只放全局规则局部规则下沉到子目录换了工具配置不生效不同工具读取路径不一致把 AGENTS.md 放根目录同时复制关键配置到工具指定路径始终维护一条真源更新配置后 AI 行为没变会话缓存或上下文未重建新建会话、重启工具确认加载的是新配置团队没人维护配置没有纳入协作流程把 AGENTS.md 变更纳入 PR checklist把每条新规则关联到具体事故规则和实际代码冲突配置写的是理想态代码是现实态优先修正配置让配置描述当前真实约束而不是未来愿景5.2 几条值得记住的避坑经验第一条别把 AGENTS.md 写成 README 2.0。README 是给人看的完整说明AGENTS.md 是给 AI 看的浓缩决策。有人把项目背景、产品愿景、市场分析写了一大段AI 看完等于没看。背景知识要写但只写“会影响代码决策”的那部分。第二条小心对话内指令覆盖声明式配置。你在会话里说一句“这次先别管规范”AI 很可能就把配置里的规则全部当背景噪音了。这种例外处理很危险一旦形成习惯声明式配置就形同虚设。最好明确告诉 AI配置里的硬性规则除非明确要求修改文件否则不得忽略。第三条配置里不要放频繁变化的信息。具体版本号、临时 TODO、某个依赖的最新版本这类内容放进去很快就会过期过期之后 AI 不知道该信配置还是该信代码最后只能猜。第四条善用“记忆回填”。每次让 AI 完成一个大型任务后多问一句这次任务里有没有应该沉淀到 AGENTS.md 的规则如果有让 AI 直接输出规则变更草案人工确认后合入。这比我每次手动回想高效得多也是让 Memory 工程持续有效的关键习惯。第五条用“AI 面试法”测试配置质量。新建一个会话问三个问题这个项目是做什么的关键架构边界是什么有哪些绝对不能做的事如果 AI 回答得精准、一致说明配置质量高如果它含糊、自由发挥那就是配置写得还不到位。6. 什么时候别上重型 Memory 方案很多人一聊 Memory 工程就想着上向量库、建知识库、搭检索服务。我的观点很直接配置先行检索兜底别为了工程而工程。什么情况下只靠 AGENTS.md 就够项目是中小规模、代码路径清晰、团队几个人、AI 主要做日常增删改查或者项目还在快速迭代架构天天变写太多东西进向量库只会更快过期。什么情况下才值得上重型方案项目知识库庞大、文档散落、新人上手成本极高或者任务依赖大量历史资料才能决策比如复杂系统的跨模块重构、历史遗留代码的梳理。这种情况下也可以用 AGENTS.md 管理“结构性规则”用检索管理“长尾知识”两者不是二选一的关系。我的建议是先轻后重。第一步根目录一个 AGENTS.md配合必要的子目录规则第二步观察 AI 在真实任务中的表现如果它频繁需要“查找某段历史决策但找不到”再考虑加索引第三步只有确认常规检索无法满足需求时才上向量库。每一步都比前一步更贵也更复杂但没有第一步后面全是空中楼阁。我在实际项目里踩过最大的坑就是一开始把 AGENTS.md 写成了一篇“项目说明书”事无巨细结果 AI 该遵守的没遵守不该过问的倒是记得很牢。后来我把口径统一成一句话这是给 AI 的入职手册只说必须遵守和必须知道的事。另一个我一直保持的习惯是每次任务收尾时问一句这次有没有哪条规则应该沉淀进配置有就立刻更新。这套东西不会有“写完”的一天它会跟着项目一起长大但恰恰是这种持续维护才让 AI 真正从无状态模型变成一个懂项目的老员工。
