1. 从“无状态”到“有记忆”AI 编程范式到底在转什么如果你最近半年一直在用 AI 辅助写代码大概率会有一种很割裂的体验模型本身越来越强但每次开新会话它就像失忆了一样你昨天刚跟它讲清楚的目录结构、命名规范、技术栈约束今天它又忘得一干二净。你不得不把同样的上下文反复粘贴像在给一个每天都会失忆的同事做入职培训。这个问题的本质是无状态模型和工程化协作之间的根本矛盾。大语言模型在单次推理时是无状态的它只认当前上下文窗口里的内容。你给它什么它就基于什么回答。这跟传统软件工程里“配置持久化、状态可继承”的思路完全相反。于是一个很自然的需求就冒出来了能不能把项目的“记忆”从每次对话里抽出来变成一份模型每次都能读到的声明式配置这就是AGENTS.md这类文件出现的背景。它本质上是一份放在项目根目录的约定文件用自然语言加结构化格式把“这个项目是什么、怎么构建、怎么测试、有哪些禁忌、代码风格如何”一次性写清楚。模型每次进入这个项目先读这份文件再干活。听起来很简单但它背后代表的是一次范式转换从“每次对话重新交代”转向“项目级记忆持久化”从“提示词技巧”转向“工程化配置”。我把它叫做Memory 工程。这个词不是官方术语是我自己在实际项目里摸索出来的一个说法。核心意思是把 AI 协作过程中需要反复传递的上下文抽象成可维护、可版本控制、可复用的工程资产而不是散落在聊天记录里的临时提示。AGENTS.md 只是其中一种载体但它足够典型足够说明问题。这篇文章适合谁看如果你已经在用 AI 写代码但还在靠“复制粘贴上下文”过日子那这篇就是写给你的。如果你是小团队里负责搭工程规范的人想搞清楚怎么让 AI 真正融入现有工作流那也值得一读。我不打算讲太多模型原理重点放在为什么这样设计、文件怎么写、踩过哪些坑、怎么排查问题。2. 为什么是声明式配置而不是继续堆提示词2.1 提示词工程的三个天花板我最早也是纯提示词派。每次开新会话先甩一段“你是一个资深工程师请遵循以下规范……”然后开始干活。短期看没问题但项目一复杂三个问题就暴露了。第一个是上下文漂移。对话轮次一多模型对早期提示的注意力会衰减。你开头说的“不要用 any 类型”到第十轮它可能就忘了。这不是模型故意是注意力机制本身的特性。第二个是重复劳动。同一个项目今天开一个会话明天开一个会话每次都要重新交代一遍。如果团队里三个人都在用 AI 辅助那就是三倍的重复。更麻烦的是每个人交代的版本还不一样导致 AI 产出的代码风格不统一。第三个是不可审计。提示词散在聊天记录里没法 review没法 diff没法回滚。你改了一版提示效果变差了想退回上一版只能靠记忆。这跟工程化的基本要求是背道而驰的。2.2 声明式配置解决了什么AGENTS.md 的思路是把这些“每次都要说”的东西变成“写一次放在那里模型自己读”。它有几个明显好处。可版本控制。文件在仓库里跟着代码一起提交。谁改了什么git log 一目了然。改坏了直接 revert。可复用。新来的同事 clone 仓库AI 工具自动读这份文件不需要口口相传。团队协作的一致性有了基础保障。可组合。根目录一份全局的子目录可以放更细粒度的。模型按路径逐层读取像读配置文件一样。降低提示词技巧依赖。你不需要成为提示词大师只需要把项目事实写清楚。模型读事实比读“请你扮演一个资深工程师”这种角色设定要稳得多。注意声明式配置不是要取代提示词而是把“稳定不变的项目事实”从提示词里抽出来。临时任务、一次性需求还是靠对话解决。两者是分层关系不是替代关系。2.3 一个生活化类比你可以把无状态模型想象成一个每天上班都会失忆的外包工程师。提示词工程就像每天早上在他工位上贴一张便利贴写“今天要做的事”。贴得多了工位贴满他反而看不清重点。AGENTS.md 则像是一本放在工位抽屉里的《项目手册》。他每天来了先翻手册知道这个项目是干什么的、代码放哪、怎么跑测试、哪些坑不能踩。便利贴只写“今天临时加个需求”。手册稳定便利贴灵活各司其职。这个类比不完美但能帮你快速理解分层逻辑。手册是 Memory便利贴是 Prompt。Memory 工程要解决的就是怎么把手册写好、维护好、让模型真的读进去。3. AGENTS.md 到底该写什么结构拆解与字段设计3.1 最小可用版本长什么样我见过很多人第一次写 AGENTS.md要么写得太空要么写得太满。太空的比如“请写高质量代码”等于没说。太满的比如把整个架构文档贴进去模型读半天抓不到重点。我的经验是先从一个最小可用版本开始包含五块内容项目定位、技术栈、目录结构、常用命令、硬性约束。这五块覆盖了模型干活最需要的信息。# AGENTS.md ## 项目定位 这是一个面向内部使用的数据处理服务负责接收上游事件、做清洗和聚合、写入下游存储。 ## 技术栈 - 语言TypeScript 5.x - 运行时Node.js 20 LTS - 框架Fastify - 数据库PostgreSQL 15 - 测试Vitest ## 目录结构 - src/handlers事件处理入口 - src/services业务逻辑 - src/repos数据访问层 - src/utils纯函数工具 - tests测试文件与 src 镜像对应 ## 常用命令 - 安装依赖npm ci - 本地开发npm run dev - 跑测试npm test - 类型检查npm run typecheck - 格式化npm run format ## 硬性约束 - 禁止使用 any必要时用 unknown 加类型守卫 - 所有对外函数必须有显式返回类型 - 数据库查询必须走 repos 层禁止在 handlers 里直接写 SQL - 新增依赖前必须先说明理由这份文件不到 60 行但信息密度很高。模型读完基本知道这个项目怎么跑、代码放哪、哪些线不能踩。3.2 字段设计的取舍逻辑为什么是这五块而不是别的我逐个说下取舍。项目定位放最前面是因为模型需要先建立“这个项目在干什么”的心智模型。没有这个它写出来的代码容易跑偏。比如一个数据处理服务它可能给你写成 Web 应用。技术栈要写具体版本。我踩过的坑只写“TypeScript”模型可能用旧语法写“TypeScript 5.x”它就知道可以用 satisfies 这类新特性。版本号是给模型的硬边界。目录结构不用写全写关键分层就行。目的是让模型知道“新代码该放哪”。如果目录很深可以只写顶层加一句“子目录按功能划分”。常用命令必须准确。模型有时候会自己编命令比如npm run test:unit但实际项目里没有这个脚本。写清楚它就不会瞎猜。硬性约束是最有价值的部分。这里放的是“模型默认行为可能不符合项目要求”的地方。比如模型默认喜欢用 any 图省事你就明确禁掉。默认喜欢在 handler 里写业务逻辑你就要求分层。3.3 进阶字段什么时候加加什么最小版本跑顺之后可以按需加字段。我列几个常见的以及我的建议。字段什么时候加注意点代码风格示例团队有非标准风格时给正反例别只给规则提交信息规范用 commitlint 时给模板别只给描述环境变量说明本地启动依赖 env 时只写 key 和用途别写真实值已知技术债有历史包袱时说明哪些地方别动为什么外部依赖约束有内部 SDK 时写清楚版本和调用方式加字段的原则是只加模型容易搞错、且反复需要的信息。如果某个信息模型默认就能做对不用写。写了反而增加阅读负担。提示AGENTS.md 不是越全越好。我见过一份 500 行的模型读完之后反而抓不住重点。控制在 100 行以内超过就拆到子目录的 AGENTS.md 里。4. 实操从零搭一套 Memory 工程工作流4.1 第一步盘点现有项目的“隐性知识”别急着写文件。先花半小时把项目里“老员工知道但新人不知道”的东西列出来。我通常用这几个问题引导新人入职第一天你会跟他讲什么哪些错误是新人反复犯的哪些命令是必须用但文档里没写的哪些目录是禁区改了会出事代码 review 时你最常提的意见是什么把答案列成清单这就是 AGENTS.md 的素材。我试过一个中等项目通常能列出 20 到 30 条。然后按重要性排序取前 15 条写进去。4.2 第二步分层放置而不是一坨单根目录一份 AGENTS.md 适合小项目。项目一大就要分层。我的做法是根目录全局约束、技术栈、顶层命令前端目录前端特有规范、组件约定后端目录后端分层、数据库约定测试目录测试写法、mock 约定模型读取时会按当前编辑文件的路径逐层向上找最近的 AGENTS.md。这样它在前端目录干活时读的是前端那份不会被后端规范干扰。这里有个细节子目录的 AGENTS.md 要显式声明“继承根目录约束”否则模型可能只读子目录那份漏掉全局规则。我一般会在子文件开头写一句“本文件补充根目录 AGENTS.md冲突时以根目录为准”。4.3 第三步把命令跑通别写想当然的这一步最容易被忽略。很多人写 AGENTS.md 时凭记忆写命令结果模型照着跑报错。我踩过这个坑写了个npm run lint:fix实际项目里脚本叫npm run fix。模型跑不通就开始自己猜猜出来的命令更离谱。所以写完命令部分一定要逐条在干净环境里跑一遍。跑不通的要么改命令要么改脚本。别让 AGENTS.md 里出现“理论上应该能跑”的命令。4.4 第四步验证模型是否真的读进去了写完不是结束要验证。我的验证方法是开一个新会话不给任何额外提示直接让模型做一个需要遵守约束的任务。比如在 src/services 下新增一个函数读取用户配置并返回。然后看它的产出。如果它用了 any说明约束没读进去如果它把逻辑写在了 handler 里说明分层没读进去如果它自己编了个不存在的命令说明命令部分有问题。根据产出反推 AGENTS.md 哪里没写清楚迭代。我一般迭代三到五轮才能让模型稳定遵守。4.5 第五步纳入版本控制和 review 流程AGENTS.md 要跟代码一样对待。改它要提 PR要 review。我建议在 PR 模板里加一条“如果本次改动涉及工程规范变化请同步更新 AGENTS.md”。另外每次模型产出不符合预期时先别急着改提示词先看 AGENTS.md 是不是漏了这条。如果是补进去。这样 AGENTS.md 会随着项目使用越来越准形成正循环。5. 常见问题与排查技巧实录5.1 模型不读 AGENTS.md 怎么办这是最高频的问题。可能原因有三个。文件位置不对。不同工具对 AGENTS.md 的读取路径约定不一样。有的只读根目录有的支持子目录。先确认你用的工具支持哪种。如果不确定先放根目录确保能被读到。文件名不对。有的工具认 AGENTS.md有的认 AGENT.md有的认 .agents.md。这个没有统一标准查你所用工具的文档。我一般会同时放 AGENTS.md 和 AGENT.md内容一样兼容不同工具。文件太长被截断。上下文窗口有限文件太长可能只读了一部分。控制在 100 行以内超过就拆。排查方法在文件开头写一句显眼的标记比如“本项目使用 Fastify 框架”然后问模型“这个项目用什么框架”。如果答不上来就是没读到。5.2 模型读了但不遵守怎么办读了不遵守通常是约束写得太模糊。比如“请写高质量代码”模型不知道什么叫高质量。改成“所有函数必须有显式返回类型禁止使用 any”就具体了。另一个原因是约束太多互相冲突。比如同时要求“代码简洁”和“每个函数都要写详细注释”模型就懵了。约束要精简优先级要明确。还有个技巧把最重要的约束放在文件开头和结尾。中间部分模型容易忽略首尾注意力更高。我一般把“硬性约束”放最后因为那是必须遵守的。5.3 多工具共存时怎么维护团队里有人用工具 A有人用工具 B读取约定不一样。我的做法是维护一份源文件其他格式用脚本生成。比如源文件叫 AGENTS.md然后写个脚本把它软链接或复制成工具 B 认的文件名。改的时候只改源文件跑一下脚本同步。这样避免多份文件内容不一致。如果工具支持自定义读取路径那就更简单直接指向同一份文件。5.4 常见问题速查表现象可能原因排查动作模型完全无视约束文件没被读取检查路径、文件名、长度模型读了但偶尔违反约束模糊或冲突具体化约束明确优先级模型自己编命令命令部分不准逐条跑通修正子目录规范不生效未声明继承根目录子文件开头加继承说明改了文件没效果缓存或未重载重启会话确认工具重读多工具行为不一致读取约定不同统一源文件脚本同步5.5 几个我踩过的坑坑一把 AGENTS.md 写成架构文档。我最早写了一份 300 行的把整个系统架构、数据流、部署流程都塞进去。结果模型读完之后反而不知道重点在哪产出质量下降。后来砍到 80 行只留模型干活需要的效果立刻好转。坑二约束写得太绝对。比如“禁止使用 class”结果模型遇到必须用 class 的场景硬生生绕开写出更烂的代码。约束要留例外空间比如“优先使用函数式确需封装状态时可用 class”。坑三忘了更新。项目从 JavaScript 迁到 TypeScriptAGENTS.md 里还写着 JavaScript。模型按旧信息干活产出全是 js 文件。所以 AGENTS.md 要纳入迁移 checklist。坑四命令里写了本地路径。比如npm run dev -- --config /Users/xxx/config别人 clone 下来跑不通。命令要写相对路径或环境变量。6. Memory 工程的边界与后续演进6.1 它解决不了什么Memory 工程不是银弹。它解决的是“稳定项目事实的持久化传递”解决不了“模型能力本身不足”。如果模型对某个领域知识就是欠缺写再多 AGENTS.md 也没用。它也解决不了“需求本身模糊”的问题。如果任务描述不清楚模型读再多项目记忆也做不对。Memory 管的是“项目上下文”不是“任务上下文”。还有它依赖工具支持。如果所用工具根本不读 AGENTS.md那这套方法就落不了地。选工具时要把这个作为考量项。6.2 从单文件到记忆分层AGENTS.md 只是起点。往深了走可以做记忆分层项目级记忆AGENTS.md稳定版本控制模块级记忆子目录 AGENTS.md按需加载会话级记忆当前对话的临时上下文任务级记忆单次任务的详细描述这四层各司其职模型按需读取。项目级和模块级是持久化的会话级和任务级是临时的。分层的好处是持久记忆保持精简临时记忆保持灵活。6.3 一个我常用的扩展技巧在 AGENTS.md 里加一个“常见错误”小节记录模型在这个项目里反复犯的错。比如## 常见错误 - 不要在 handler 里直接调用数据库必须走 service 层 - 不要用 moment.js项目统一用 date-fns - 不要自己实现深拷贝用项目里的 cloneDeep 工具这个清单会随着使用越来越长但价值极高。它相当于把“代码 review 时最常提的意见”固化下来模型每次读一遍就能避开这些坑。我实测下来加了这一节之后模型产出的返工率明显下降。6.4 后续可以怎么扩展如果你已经把 AGENTS.md 跑顺了可以往几个方向扩展。自动化校验。写个脚本检查 AGENTS.md 里提到的命令是否真实存在、目录是否存在。避免文件跟项目脱节。多项目模板。把 AGENTS.md 抽象成模板新项目初始化时自动生成一份再按项目特点微调。省去从零写的时间。与 CI 集成。在 CI 里加一步检查 AGENTS.md 是否被修改但未同步更新相关脚本。保证一致性。记忆版本化。给 AGENTS.md 加版本号记录每次重大变更的原因。方便回溯“为什么当初定了这条约束”。我个人在实际操作中的体会是Memory 工程的价值不在于文件本身而在于它强迫你把“隐性知识显性化”。写 AGENTS.md 的过程其实就是一次项目规范的梳理。很多团队写着写着发现原来自己项目里有这么多没写下来的约定。把这些约定固化下来不管用不用 AI对团队协作都是好事。最后再分享一个小技巧如果你不确定某条约束该不该写进 AGENTS.md就问自己一句——“新人入职我会不会专门跟他强调这条”如果会就写如果不会就别写。这个标准帮我砍掉了很多冗余内容让文件保持精简。