无状态AI编程的Memory工程：AGENTS.md声明式配置实战指南

1. 从每次重新解释到一次声明AI编程范式的真实转折点如果你最近半年深度用过任何一款AI编程助手大概率经历过这种循环新开一个会话窗口把项目结构、技术栈、代码规范、命名习惯、测试框架、甚至不要用var要用const这种细节重新交代一遍。运气好的话AI能记住前几轮对话的上下文运气不好聊到第十轮它就开始失忆把你三小时前强调过的架构约束忘得一干二净。这不是模型不够聪明而是**无状态stateless**这个底层特性决定的。绝大多数AI编程工具的本质是你给它一段上下文它给你一段补全。会话结束一切归零。下次再来它对你一无所知。我最初也以为这只是上下文窗口不够大的问题后来发现完全不是。就算把窗口扩到几十万token你依然要面对一个更根本的矛盾项目的长期知识是稳定的而每次对话的上下文是易失的。把稳定知识塞进易失容器里本身就是设计错配。于是就有了AGENTS.md这类声明式配置文件的出现。它的思路很朴素既然AI每次都是失忆的那就把项目里那些不该被遗忘的东西——架构约定、目录职责、编码规范、常用命令、禁区清单——写成一个AI每次都会读取的声明文件。模型依然无状态但它的工作环境变成了有状态的。这个转变的意义比表面看起来大得多。它标志着AI编程从对话式提示走向工程化配置从我教AI做事走向我定义AI的工作环境。前者依赖人的记忆和耐心后者依赖一份可版本控制、可团队共享、可迭代演进的配置文件。这篇文章想聊的就是这件事为什么无状态模型需要Memory工程AGENTS.md这类声明式配置到底解决了什么问题以及怎么从零搭出一套真正好用的配置体系。不管你是刚接触AI编程的新手还是已经踩过一堆坑的老手下面这些内容应该都能帮你少走点弯路。2. 无状态模型的三个硬伤以及为什么多聊几句救不了2.1 硬伤一上下文是消耗品不是资产很多人对AI编程有个误解觉得只要我提示词写得够详细AI就能一直靠谱。实测下来这个假设在单次任务里勉强成立一旦跨任务就崩。原因在于上下文窗口里的内容是有优先级衰减的。你开头写的架构说明随着对话推进会被后续的代码片段、报错信息、调试记录不断挤压。模型对早期内容的注意力会下降这不是bug是注意力机制的固有特性。我做过一个粗糙的测试让AI在一个会话里连续完成五个小功能每个功能都涉及所有API调用必须走统一的request封装这条约束。第一个功能它老老实实遵守第三个功能开始偶尔绕过封装直接fetch第五个功能基本忘光了。全程我一个字都没改过约束它自己忘的。这说明什么上下文里的信息不等于模型的行为约束。你写进去了不代表它会一直执行。而无状态模型每次重启连这点临时记忆都没了。2.2 硬伤二知识无法沉淀团队无法共享第二个问题更隐蔽但对团队协作的伤害更大。假设你花了两小时终于把AI调教得能按你们团队的规范写代码了。这套调教成果存在哪存在你那个会话窗口里。关掉就没了。同事想用对不起他得自己再调教一遍。新人入职他连从哪开始都不知道。这就是无状态模型的第二个硬伤它让如何与AI协作这件事变成了个人经验而不是团队资产。每个人都在重复造轮子每个人踩的坑都不一样但没人把这些坑固化下来。对比一下传统工程实践代码规范写成ESLint配置构建流程写成CI脚本部署步骤写成Dockerfile。这些都是声明式的写一次所有人受益还能进版本控制。而AI协作呢大部分团队还停留在口口相传的阶段。2.3 硬伤三提示词越写越长维护成本指数上升第三个硬伤是前两个的必然结果。既然上下文会衰减、知识无法沉淀那人的本能反应就是那我写长一点、写全一点。于是你看到很多人的提示词模板越来越夸张开头五百字项目背景中间八百字编码规范结尾三百字禁区清单。每次新会话都要粘贴一遍改一个细节要同步改五个地方不同人手里的版本还各不相同。这套东西维护起来有多痛苦用过的人都懂。更讽刺的是你写得越长模型对每一段的注意力反而越分散效果未必更好。用堆砌对抗遗忘是典型的用战术勤奋掩盖战略懒惰。三个硬伤指向同一个结论无状态模型缺的不是更多上下文而是一个独立于会话、可持久化、可声明、可共享的配置层。这就是Memory工程要解决的问题也是AGENTS.md这类文件存在的理由。3. AGENTS.md到底声明了什么一份配置文件的解剖3.1 它不是提示词是工作环境说明书先纠正一个常见误解很多人把AGENTS.md当成更长的系统提示词。这个理解偏了。提示词是任务级的针对某一次具体请求AGENTS.md是项目级的描述的是这个项目长期不变的约定。打个比方提示词像是你给外包同事发的这次帮我改个登录页的需求AGENTS.md像是你给他的我们公司代码库的入职手册。前者每次不同后者基本稳定。这个定位差异决定了写法差异。提示词可以很口语、很具体、很临时AGENTS.md必须结构化、稳定、可长期维护。它回答的不是这次做什么而是在这个项目里事情一般怎么做。3.2 一份合格的AGENTS.md通常包含哪几块我翻过不少团队的实际配置也自己迭代过好几版总结下来一份好用的AGENTS.md基本逃不出这几块内容模块作用典型内容项目概览让AI快速建立全局认知技术栈、目录结构、核心模块职责编码规范约束代码风格与写法命名约定、导入顺序、错误处理模式命令清单告诉AI怎么跑项目安装、启动、测试、构建、lint命令禁区清单明确不能碰的地方禁止修改的文件、禁止引入的依赖协作约定定义AI的工作方式改动前先说明、大改先给方案、提交信息格式注意最后一块协作约定这是很多人会忽略但极其重要的一环。它约束的不是代码而是AI的行为模式。比如任何涉及三个以上文件的改动先输出方案再动手这一条能帮你省下大量返工时间。3.3 为什么是Markdown为什么是声明式有人会问为什么不用JSON、YAML这种更结构化的格式因为AGENTS.md的读者是语言模型不是程序。Markdown的层级、列表、加粗这些视觉信号恰好是模型理解哪些是重点、哪些是分类的天然线索。用YAML写规范模型也能读但可读性和可维护性对人都差很多。至于声明式核心在于描述状态而非过程。你不要写第一步打开文件第二步找到函数第三步修改而要写所有网络请求必须经过request模块。前者是命令式后者是声明式。声明式的好处是不管AI用什么方式实现只要结果符合声明就行给了模型更大的发挥空间也减少了你的维护负担。4. 从零搭一套Memory体系我的分层配置实践4.1 分层思路全局、项目、任务三层各管各的一上来就把所有东西塞进一个AGENTS.md很快就会变成一锅粥。我踩过这个坑后来改成三层结构清爽很多。全局层放那些跨项目通用的约定比如回答用中文代码注释用英文不确定时先问不要猜。这层内容基本不变可以放在用户级配置里。项目层就是AGENTS.md的主战场放这个项目特有的技术栈、目录结构、命令、规范。这层随项目走进版本控制。任务层是临时的针对当前这次具体工作比如这次只改登录模块别动其他文件。这层可以放在会话开头的提示里用完即弃。三层各司其职改哪层改哪层不会互相污染。关键是不要把任务级的东西写进项目级否则AGENTS.md会越来越臃肿最后没人愿意维护。4.2 项目层AGENTS.md的实操模板下面这份是我目前用得比较顺的模板你可以直接抄去改# 项目协作说明 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 状态管理Zustand - 测试Vitest Testing Library ## 目录职责 - src/components纯展示组件不含业务逻辑 - src/features按功能域组织的业务模块 - src/lib与框架无关的工具函数 - src/api所有网络请求封装禁止在组件里直接fetch ## 编码规范 - 组件用函数式禁止class组件 - 变量命名用camelCase常量用UPPER_SNAKE_CASE - 所有异步操作必须处理错误分支 - 导入顺序外部依赖 → 内部模块 → 类型 ## 常用命令 - 安装pnpm install - 开发pnpm dev - 测试pnpm test - 构建pnpm build ## 禁区 - 不要修改 src/lib/legacy 下的任何文件 - 不要引入新的状态管理库 - 不要改动 vite.config.ts 的别名配置 ## 协作约定 - 涉及三个以上文件的改动先给方案再动手 - 每次改动后说明改了哪些文件、为什么 - 不确定的地方先问不要自行假设这份模板大概一百多行覆盖了日常八成场景。注意禁区和协作约定这两块是真正能帮你省时间的地方。4.3 一个容易被忽略的细节命令要写可复制的我见过不少AGENTS.md把命令写成运行测试套件这种描述性文字。这其实浪费了声明式配置的价值。正确做法是把命令写成可以直接复制执行的形式比如pnpm test --watch。这样AI在需要验证改动时能直接调用不用猜你们项目到底用npm还是pnpm、用test还是vitest。命令写得越具体AI的自主性越强你被打断的次数越少。同理路径也要写全。别写配置文件写src/config/app.config.ts。模型不需要你省字它需要的是精确。5. 声明式配置踩过的坑五个真实教训5.1 坑一写得太满反而没人看我第一版AGENTS.md写了四百多行恨不得把团队三年的规范全塞进去。结果呢模型开始选择性忽略我自己也懒得维护改一处忘一处。后来我做了个减法只保留那些不写就会出错的条目。比如不要用var这种其实ESLint已经管了没必要写。真正要写的是那些工具管不了、只有人知道的约定比如这个模块的历史包袱很重改动要格外小心。判断标准很简单如果这条约定违反了会不会导致返工或线上问题会就写不会就删。5.2 坑二把建议和强制混在一起早期我写规范时不分轻重结果模型分不清哪些是硬约束、哪些是软偏好。比如我写了尽量用函数式组件它有时候用有时候不用我还怪它不听话。后来我学乖了用词上做区分强制项用必须禁止建议项用优先尽量。模型对这类程度词的敏感度比想象中高。更狠一点的做法是把强制项单独列一个硬约束小节视觉上就区分开。5.3 坑三忘了写怎么验证这是最容易被忽略的一条。你告诉AI改完要测试但没告诉它怎么测试算通过。结果它跑了个测试命令看到没报错就以为完事了其实测试根本没覆盖到改动的地方。解决办法是在AGENTS.md里明确验证标准。比如改动API层后必须运行pnpm test:api且所有用例通过。把验证动作和验证标准都写清楚AI才知道什么叫做完了。5.4 坑四配置和代码不同步AGENTS.md最大的敌人是过期。项目重构了目录结构变了配置还写着老路径依赖升级了命令变了配置还是旧的。模型照着过期配置干活出的错比没有配置还离谱。我的做法是把AGENTS.md纳入代码评审。任何涉及目录结构、命令、依赖的改动PR里必须同步更新AGENTS.md。这听起来麻烦但比事后排查为什么AI老是找错文件要省事得多。5.5 坑五以为写了就万事大吉最后一个坑最隐蔽把AGENTS.md当成一劳永逸的银弹。它不是。模型依然会犯错依然会偶尔忽略配置。声明式配置的作用是大幅降低出错概率不是消除出错。你还是要在关键节点做检查尤其是涉及数据、权限、线上配置的改动。我的经验是配置负责让AI大概率做对人负责在关键处兜底。两者不是替代关系是配合关系。6. 范式转换的深层逻辑从教AI到定义环境6.1 为什么说这是范式转换不是工具升级表面看AGENTS.md只是多了个配置文件。但往深了想它改变的是人和AI的协作关系。在对话式提示范式里人是老师AI是学生。每次协作都是一次教学教完就忘下次重来。人的精力大量消耗在重复解释上。在声明式配置范式里人是环境设计者AI是环境里的执行者。你不再教它每一步怎么做而是定义好它工作的边界、资源和规则让它自己在里面跑。人的精力从重复解释转移到设计环境和关键决策上。这个转变和软件工程从手写汇编到高级语言编译器的演进本质上是同一类事情把重复的、易错的、可固化的部分抽象出来让人专注于真正需要判断力的部分。6.2 Memory工程的边界什么该记什么不该记既然是Memory工程就得回答记什么。我的判断标准是三条第一记稳定不记易变。技术栈、目录结构、编码规范这些半年不变的东西值得记。今天要改哪个bug、明天要加哪个功能不值得记。第二记隐性不记显性。ESLint能管的不用记只有老员工才知道的这个模块别乱动必须记。Memory的价值在于承载那些工具无法表达的团队知识。第三记高频不记低频。天天用到的约定优先记一年用一次的边缘情况可以放放。配置的维护成本是有限的要用在刀刃上。6.3 一个反直觉的结论配置越少效果越好最后分享一个我踩了很多坑才悟出来的结论AGENTS.md不是越全越好而是越精越好。我见过效果最好的配置往往只有五六十行但每一条都是血泪教训换来的。相反那些动辄几百行的大而全配置模型读起来费劲人维护起来更费劲最后沦为摆设。这背后的逻辑是声明式配置的价值不在于覆盖多少而在于命中多少。十条精准的约束比一百条泛泛的规范有用得多。与其追求全面不如追求精准——每写一条都问自己这条真的会改变AI的行为吗答不上来就删掉。7. 落地建议从今天开始能做的三件事如果你读到这里想动手试试我给三个从易到难的建议。第一件先写一份最小可用的AGENTS.md。不用追求完美把技术栈、目录结构、常用命令这三块写清楚就行。这三块是AI最常需要、也最容易搞错的信息。写完放进项目根目录下次开新会话时让它先读一遍你会立刻感受到差别。第二件把禁区清单单独拎出来。这是投入产出比最高的一块。列出那些改了会出事的文件和目录明确告诉AI别碰。这一条能帮你避免大部分低级事故。第三件建立配置的更新机制。把AGENTS.md纳入代码评审任何结构性改动同步更新。这一步不做前面两步的收益会随时间快速衰减。至于更进阶的分层配置、多环境配置、配置的自动化校验可以等基础跑顺了再逐步加。Memory工程是个长期活别指望一次到位。我在实际使用中最大的体会是AI编程的上限不取决于模型多强而取决于你给它搭的环境多好。同样一个模型在裸奔状态下和在有良好配置的环境里表现差距可能是数量级的。与其抱怨AI不够聪明不如先检查一下你有没有给它一个值得聪明的环境。