作为一个从 AI 编程助手刚出现就开始用、到现在几乎每天离不开的人我最近半年最明显的感受是AI 编程的重心正在从怎么把一句话问得更好转向怎么把项目的记忆交给 AI。这两者听起来差别不大但实际开发体验完全是两个世界。围绕 AI 编程范式转换和 Memory 工程业界讨论越来越热而我更关心的是落地怎么让一个无状态的模型真正记住我的项目。最早的时候我打开一个 AI 编程工具相当于请了一个记忆力只有几分钟的临时工。他每次听完需求、动手改完代码你把对话关掉再开一个新会话他就什么都不记得了。项目结构、依赖关系、编码规范、测试命令——所有这些都要重新讲一遍。讲得烦了我就想凭什么这些东西不能写成一份文件让 AI 自己去看这个念头其实就是 Memory 工程的起点。而 AGENTS.md 这类声明式配置文件则是这个思路目前最成熟的落地形态。这篇文章不打算讲虚的就讲我自己从无状态模型的坑里爬出来到逐步建立一套项目记忆体系的过程以及踩过的坑和总结出的实操方法。如果你每天也在和一问三不知的 AI 编程助手较劲这篇文章应该能帮你省下不少重复劳动。1. 无状态模型的困局每次对话都是初次见面1.1 无状态到底是什么意思先把我理解的无状态这个词讲透。一个无状态的对话模型在处理你的每次请求时它看到的只是你发给它的那一段文本——包括系统提示、历史消息、你的新问题以及其他附加上下文。它没有一个持续存在的大脑来记住上次对话的结论。所谓记住本质上只是把过去的文本重新塞进当前这次请求的上下文里。这就带来一个很反直觉的现象你以为 AI 在学习你的项目实际上它只是在你当前这轮对话的可见范围内临时阅读。对话一关、上下文一清它对你项目的理解就归零。我最早踩这个坑的时候很崩溃——上午刚跟工具确认过项目的目录结构和启动方式下午开一个新会话让它写个新功能它又开始瞎猜甚至连我用的是哪个包管理器都能搞错。这个问题的根子在于大语言模型本身没有项目记忆这个组件。它的知识是训练时固化下来的通用知识而你的项目是训练数据里不存在的私有信息。要让 AI 用得顺唯一的办法就是把这些私有信息在每次请求时以可读的形式喂给它。谁喂得全、喂得准谁用起来就顺。1.2 上下文窗口看着很大实际很挤有人可能会说现在模型上下文窗口不是很大吗动辄几十万 token把整个项目塞进去不就行了想法没错但现实很骨感。上下文窗口是物理上限不是推荐用量。我实测过的经验是当喂给模型的上下文越长模型对中间信息的注意力就越容易被稀释回答质量明显下降。这不是玄学注意力机制就是这样的——长文本里模型更容易盯着开头和结尾看中间夹着的关键约束经常被忽略。于是你陷入一个矛盾想让 AI 懂项目就得给它塞大量项目背景但塞太多了它反而抓不住重点。我自己的体会是无脑把 README、全部文档、几十个模块文件全塞进去效果往往不如一份精心写好的、几百行的项目说明文件。这就是为什么记忆的工程化越来越重要——我们要的不是喂得多而是喂得巧。这里有一个常被忽视的细节上下文里的信息不是平等对待的。开头和结尾的信息被模型记住的概率远远大于中间段落。这意味着如果你把项目背景放在一大段杂乱文本的正中间它大概率被淹没。反过来如果项目约定能每次都出现在对话的最前端那它被模型真正采纳的概率会高很多。后面讲的 AGENTS.md之所以有效和这个机制密切相关。1.3 重复沟通的隐性成本无状态还有一个很现实的成本问题时间。我自己统计过早期在项目里用 AI 编程助手平均每次新开会话至少要花 5 到 10 分钟去热身——讲清项目是做什么的、技术栈是什么、目录怎么组织、有哪些约定。一天开十次会话一小时就没了。这还是顺利的情况如果不顺利它给了个完全不符合项目规范的答案你还要花时间纠正成本直接翻倍。更麻烦的是不一致性。同一个项目上午的会话里你告诉它这里的错误处理统一走自定义异常下午的新会话没这个信息它可能就给你写了个裸抛异常。代码风格漂移、架构约定被破坏这些都是无状态带来的隐性债务。等到项目大了这些不统一的地方就是一个一个的雷。我把这段时期的体验总结成一张表方便你对照自己现在的情况无状态协作的典型表现带来的直接后果我当时的解决尝试每次新会话都要重新介绍项目每天浪费大量时间在重复沟通上把项目描述存在备忘录里开新会话时手动粘贴AI 给出的代码风格和项目不一致代码风格漂移审查成本上升反复在对话里强调规范效果不稳定AI 使用错误的构建或测试命令本地环境报错、CI 意外失败把命令写在提示词里但经常被忽略项目架构约定被 AI 无意破坏事后返工需要人工检查边界靠代码审查兜底但效率很低这些问题的本质都指向同一个结论无状态不是模型的 bug而是这个范式的天然属性。我们不可能要求模型自己记住项目但我们可以改变喂给它的方式。这个改变就是 Memory 工程要干的事。2. Memory 工程从临场指挥到制度治理的范式切换2.1 从 Prompt 工程到 Memory 工程前些年大家爱聊 Prompt 工程教你怎么写提示词才能让模型给出好答案。但用久了你会发现单条提示词再精妙它也是一次性的——这条提示词只能服务当前这个任务换一个任务又要重新写。Prompt 工程解决的是单次对话里的表达效率而 AI 编程真正吃掉的成本恰恰发生在多次对话之间的信息衔接上。Memory 工程不一样。它的核心思路是把那些跨任务、跨会话、长期有效的项目信息从对话里临时说变成文件里固定写。写一次长期复用。AI 每次开始工作前先读这些文件相当于入职第一天先看公司制度手册而不是每次干活都要老板口述一遍规矩。打个比方Prompt 工程是每次点菜时跟厨师说清楚口味偏好Memory 工程是把口味偏好做成一张常客档案卡厨师一看档案就知道怎么炒。后者省的不只是一次沟通而是每一次沟通。这也是我为什么认为 Memory 工程会逐渐取代 Prompt 工程成为 AI 编程领域更核心的实操技能——因为它解决的是更根本的效率问题。2.2 记忆分层全局、项目、会话我后来把 AI 编程的记忆体系分成三层这样理解起来非常清晰。第一层是全局记忆。这是关于你个人的、跨项目的偏好比如你习惯用的代码风格、常用的提交信息格式、偏好哪种测试方式。这类信息适合放在全局配置里让所有项目共享一次配置处处生效。第二层是项目记忆。这是针对某个具体项目的约定包括项目结构、架构决策、构建命令、代码规范、常见坑位。这类信息必须跟着项目走换一个项目就不适用了。AGENTS.md 就是这一层的典型载体也是整个记忆体系里最需要花心思治理的部分。第三层是会话记忆。这是当前这次任务里临时产生的信息比如正在改哪个文件、下一步做什么。这层本来就由对话上下文承载不需要持久化但它的作用同样重要——它是前两层记忆的工作台AI 把项目记忆里的规则拿到这里来执行。这三层各有各的存储和读取方式。很多人只盯着会话那一层折腾比如不断把旧对话复制到新对话里反而忽略了最该工程化的全局层和项目层。我的经验是把 80% 的精力放在项目记忆上收益最大——因为项目记忆最具体、最独特、也是最容易一劳永逸的部分。2.3 声明式与指令式一页纸说清两种范式Memory 工程里还有一对关键概念声明式和指令式。这两个词看着学术其实很好懂。指令式是告诉 AI 每一步怎么做。比如你写先读 README然后看 src 目录找到入口文件再检查依赖最后回答我的问题。这种方式很直接但有两个毛病一是啰嗦每条指令都要从头写二是脆弱AI 一旦漏执行某一步后面的结果就飘了。声明式是告诉 AI 项目当前的状态是什么样的。比如你写本项目是 Python 3.11 生态入口在 app 目录测试走统一命令代码风格遵循项目现有约定。AI 读到这些事实自己就知道该怎么行动。它不需要你一步步指挥因为足够多的事实会自动约束它的行为。这两种范式的差别我常常用一个表格来讲维度指令式声明式核心内容做什么、按什么顺序做项目是什么、有哪些约束典型例子先读文档再改代码然后跑测试测试命令是 make test改动必须配套测试复用性一条指令只针对一个任务一份声明覆盖所有相关任务容错性漏执行一步就出错事实够了AI 自己推导路径维护成本每次会话都要重新写写一次长期更新打个更生活化的比方指令式是给导航软件说左转、右转、直行声明式是告诉它目的地是哪里、走高速还是走小路。显然后者更省心也更接近 AI 编程工具应该有的使用方式。AGENTS.md 就是声明式范式的典型落地。3. AGENTS.md把项目的宪法写进仓库根目录3.1 AGENTS.md 是什么以及它凭什么有效AGENTS.md 说白了就是放在项目根目录下的一个 Markdown 文件内容是用自然语言写清楚这个项目的关键信息供 AI 编程工具在开始工作时读取。它不依赖某个特定工具你完全可以把它当成项目里的一份AI 使用手册来维护。它为什么会有效两个原因。第一它的位置固定——放在根目录任何工具、任何会话只要想了解项目第一个去翻的就是根目录这个文件天然容易被发现。第二它的格式是 Markdown——模型的训练语料里 Markdown 占很大比重解析起来毫无障碍即使没有任何特殊工具支持你直接把文件内容贴给模型它也能理解。我在实际项目中验证过同样的任务有 AGENTS.md 的项目AI 给出可用代码的概率明显更高没有的项目经常要来回纠正三四轮。这让我彻底相信这个文件不是花架子而是真正能改变 AI 工作质量的基础设施。每个接到 AI 编程任务的开发者都应该先问一句我的项目根目录里有没有这样一份给 AI 看的说明书3.2 工具读取它的典型流程为了说清楚它怎么生效我描述一下我观察到的典型流程。当你让 AI 编程工具开始处理一个新任务时工具通常会做这几件事第一步扫描项目根目录寻找 AGENTS.md 这类约定文件。找到后把它作为系统级别的上下文注入到本次对话的最前端。这一步是整个流程的关键——项目约定不是在对话中途被提到而是从第一条消息开始就端端正正地摆在模型面前。第二步如果有其他配套的说明文件比如文档索引、架构文档、README工具可能会按 AGENTS.md 里的引用提示进一步加载相关材料。这一步让配置文件的辐射范围可以延伸到整个文档体系。第三步你的具体任务指令进来后模型看到的是项目约定 文档引用 你的问题三段信息的组合。它先理解项目约定再回答你的问题。这个过程里最妙的一点是项目约定永远出现在对话的前端。还记得前面说的注意力机制吧前端信息是模型最容易关注的区域。把项目宪法放在最前面就等于强制让 AI先看制度再干活这比任何提示词技巧都管用。我后来甚至习惯在 AGENTS.md 开头就写上一句在回答任何问题之前先阅读本文件并遵守其中所有约定效果非常稳。3.3 一个可以拿来就用的 AGENTS.md 模板我不喜欢空谈概念直接上一个我在实际项目里沉淀出来的模板。这份模板覆盖了 AI 干活最常踩的几类坑项目定位、技术栈、目录结构、命令、代码约定。我把模板按项目实际情况删改核心骨架如下# 项目指南 ## 项目定位 本项目是一个 [一句话说清项目做什么] 的工具/服务。 核心目标用户是 [谁在用]核心业务价值是 [解决什么问题]。 ## 技术栈 - 语言/运行时[如 Python 3.11] - 核心框架[如项目使用的 Web 框架] - 数据库/缓存[如关系型数据库 缓存服务] - 包管理器[如项目实际使用的包管理器] ## 目录结构 - src/app业务逻辑入口所有新功能优先放在这里 - src/core与业务无关的通用能力日志、配置、异常 - tests测试目录与 src 保持镜像结构 - docs架构决策记录修改核心逻辑前先查看 ## 常用命令 - 安装依赖make install - 本地开发make dev - 运行测试make test - 代码检查make lint ## 架构约定 - 所有业务错误必须使用自定义异常禁止裸抛通用异常 - 数据访问统一走仓库层业务层禁止直接操作数据库 - 新增对外接口必须附带文档注释 ## 风格要求 - 代码遵循项目现有风格优先模仿相邻文件的写法 - 函数命名用动词开头变量命名用名词 - 注释说明为什么不解释是什么注意这份模板的关键不是字段多而是每一条都有信息量。我曾经见过有人把 AGENTS.md 写成两千字的散文AI 读完依然抓不住重点。好的声明式配置要像 API 文档一样精炼每一句都是可验证的事实而不是可读可不读的废话。4. 实战拆解从零搭建一份项目声明式记忆4.1 先梳理不变事实写配置前的准备动手写 AGENTS.md 之前我建议你先做一件事把项目里那些三个月内不会变的事实列出来。这些事实就是声明的素材。我一般会按这几个问题来梳理第一这个项目到底在做什么不要写一个电商系统这种空话要写面向中小商户的库存管理服务核心是提供实时的库存对账能力。AI 只有知道项目在做什么才能在你让它改功能时做出合理判断——它不会把支付模块的逻辑顺手套到库存模块上。第二技术选型是什么语言、框架、包管理器、数据库这些是对编写代码影响最大的硬约束。我见过 AI 在一个用 Python 的项目里给你生成其他语言的依赖安装指令就是因为缺少这一条声明。第三有哪些规矩错误处理方式、目录职责、数据访问边界、测试要求、代码风格。这些是项目长期演化形成的行为准则新成员包括 AI最需要的就是这类信息。把这个清单整理出来你就完成了 80% 的配置工作。剩下的只是把它组织成 AGENTS.md 的格式。这个过程本身也有价值——你会发现很多你以为团队心里都清楚的约定一旦要写出来才发现根本没达成过共识。这份文件顺便成了团队对齐的工具。4.2 把常用命令写成契约项目里的常用命令是最容易被忽略、但其实价值极高的配置项。原因很简单AI 要跑测试、要起服务、要装依赖如果它不知道正确命令就会自己脑补一个然后在你的环境里跑出一堆莫名其妙的错误。我习惯在 AGENTS.md 里用一个命令契约区块把关键操作和它对应的命令一一写清。比如安装依赖make install注意不要直接调包管理器安装会动锁定文件运行测试make test单元测试make test-e2e端到端测试启动开发服务make dev构建产物make build每个命令后面我会顺手写一句为什么是这个命令。比如不要直接调包管理器安装这句备注看着多余实际非常关键。AI 看到这个约束就不会擅自换命令你的 CI 也不会因为依赖锁定文件被改动而无辜挂掉。顺带说一句命令契约要定期核对。项目升级、脚手架换掉命令也会变。我见过有人 AGENTS.md 里写着上古时期的启动命令项目早换成新框架了AI 照着旧命令跑自然各种报错。配置文件不维护比没有配置文件更误事——因为你会盲目信任它直到被它坑了才反应过来。4.3 架构约定要写边界不要写代码写架构约定这块很多人容易跑偏把 AGENTS.md 写成了代码规范大全什么变量命名、缩进几格、用单引号还是双引号都写上。我倒觉得这类纯风格问题可以交给格式化工具去管AI 编程工具基本都会遵守现成的格式配置。真正需要写进声明文件的是边界——哪些模块可以碰什么什么绝对不能碰。举个例子我负责过一个数据迁移项目最核心的边界是禁止在业务代码里直接更新生产数据。我在 AGENTS.md 里把这个写成一条铁律并说明原因迁移逻辑必须经过审批脚本直接操作会导致数据不一致且无法回溯。加了这个声明之后AI 生成代码时明显收敛了很多再也没有出现过顺手写个更新语句的情况。再比如有的项目里所有对外接口都必须走统一鉴权有的项目里配置项禁止硬编码必须走配置中心。这些边界AI 在代码里是看不出来的只有显式写出来它才知道。声明式配置真正的价值就是把这些看不见的规矩变成 AI 可见的约束。写边界还有一层好处它逼着你自己想清楚项目的底线在哪里这本身就是一次很好的架构复盘。4.4 让配置文件跟着项目一起演进AGENTS.md 不是一次写完之后就永久不变的静态文件它应该和你项目的架构决策一样持续演进。我自己的习惯是每次遇到AI 因为不知道某个信息而犯错的情况就把这个信息补进去每次架构发生变动就同步更新相关条目。举个例子。有次我让 AI 重构一个模块的错误处理逻辑它自作主张引入了一个第三方库理由是可以简化代码。问题是我们的项目对第三方依赖引入有严格审查流程它不知道这个规矩就踩线了。那次之后我立刻在 AGENTS.md 里加了一条引入新的第三方依赖前先向用户确认并获得批准。从那以后再也没犯过同样的错。所以我把 AGENTS.md 当成一个活的文档AI 犯错就是文档内容有缺口文档有缺口就补上。项目在变这个文件也要跟着变。它不是摆设是你和 AI 协作的契约文本。我甚至会把每次补丁的日期和原因写成注释Markdown 里可以写在末尾这样过几个月回头看还能知道当年为什么定下某条规矩。5. 从单文件到记忆体系拆分文档、分级治理、团队同步5.1 单文件什么时候该拆AGENTS.md 做得再精炼也有体积上限。当项目复杂度上来比如有十几个模块、数百个文件时把所有信息塞进一个文件会让文件变得臃肿AI 读取时反而不容易抓住重点。这时候我建议做拆分。核心思路是根目录的 AGENTS.md 只保留全局不变的规则和指向详细文档的索引具体的技术细节放到各自的文档里通过相对路径引用。我常用的拆分方式是这样的根目录的 AGENTS.md项目定位、技术栈、核心边界、命令契约、文档索引docs/architecture.md架构决策、模块边界、关键流程docs/testing.md测试策略、测试数据说明、覆盖率要求docs/operations.md部署方式、环境变量、运维注意事项AGENTS.md 里的索引可以这么写## 文档索引 - 架构说明docs/architecture.md修改模块边界前必读 - 测试策略docs/testing.md新增测试前必读 - 运维说明docs/operations.md涉及部署配置时必读这样的好处是AI 不会一上来就淹没在几十页文档里但它知道去哪里找什么。真遇到相关任务时它会按索引去加载对应文档。这就像给 AI 配了一份项目版的知识地图比起一次性把全部知识灌输给它效果更好。我实测的感受是拆完之后 AI 在具体任务上的命中率明显提升因为它不再被无关信息干扰。5.2 全局记忆与项目记忆怎么协同前面提到记忆分层这里展开说说全局记忆和项目记忆怎么配合。全局记忆适合放那些你在任何项目里都坚持的做法。比如我自己固定的偏好是提交信息用统一的约定式风格生成代码时优先写类型注解注释必须解释为什么而不是复述代码。这些偏好放全局配置里所有项目自动生效。项目记忆放的是这个项目特有的约定优先级应该高于全局。比如你的项目本身不写类型注解那全局优先写类型注解的偏好就要服从项目的既有风格。我用一个简单的优先级原则项目级声明 全局声明 模型默认行为。实际配置时如果项目里有不同意见就写在项目级文件里项目里没提到的才轮得到全局偏好来兜底。这样层级清楚AI 的行为就可预期。如果你有两个记忆来源发生冲突AI 不知道该听谁的它就会随机应变——这恰恰是我们要避免的。5.3 团队协作里的记忆治理当 AGENTS.md 不只是你一个人的工具而是整个团队都在用时它就成了团队知识资产的一部分。这时候有两个新问题谁来维护变了怎么同步我的做法是把它纳入代码评审流程。任何修改 AGENTS.md 的变更必须有明确的理由——通常是AI 犯了某个错误补充某条声明可以避免。这样既防止有人随手乱改也让文件每次变更都有迹可循。还有一个细节AGENTS.md 的变更最好和它所描述的代码改动一起提交。如果架构变了你先合代码、后改文档中间这段时间 AI 拿到的还是旧约束就可能产出不符合新架构的代码。把文档变更和代码变更绑在一起能让记忆体系和代码库始终保持同步。团队协作还有一个好处不同成员的踩坑经验可以沉淀到同一个文件里。我负责某个模块某天发现 AI 总是不写事务边界补充一条声明同事负责另一个模块也可能发现别的坑再补一条。几个月下来这个文件就成了团队和 AI 协作的共同智慧库价值远超任何一个人的单打独斗。这也是我见过的最好的文档形态——它不是为了应付检查写的是真的有人在用、有人在更新。6. 踩坑记录声明式记忆的边界与我的三条铁律6.1 配置过度的反面教材声明式配置不是越多越好这一点我栽过跟头。有段时间我特别兴奋把能想到的约束全写进了 AGENTS.md。从代码风格、目录规范、接口命名、日志格式、异常码规则洋洋洒洒写了上千行。结果呢AI 反而变笨了——因为它要在处理任务前先消化一大堆约束注意力被分散真正重要的边界反而容易被淹没在长篇大论里。那次之后我做了个减法实验只保留 20% 最核心的约束把其余全删掉。效果立刻回升。我总结出的规律是AGENTS.md 应该像一部宪法的总纲而不是法条汇编。只写那些不写就会出大问题的规则其余细节交给格式化工具、模板代码和代码审查去解决。如果你不确定某条规则该不该写我建议用这个标准问自己假设 AI 不知道这条规则它犯错的概率有多大犯错造成的代价有多大两者都高才值得写。用这个标准过滤一遍你会发现能写进文件的东西其实比想象中少很多。6.2 声明与实际行为冲突的排查方法还有一种经常遇到的情况AGENTS.md 里写了规则但 AI 还是违反了。不要急着骂 AI 不听话先检查是不是声明本身有问题。最常见的冲突来源是声明与代码现状不一致。比如你写所有接口必须走统一网关但代码里明明有直接暴露的接口。模型读到声明又看到代码发现两者矛盾它就会困惑倾向于按看到的具体代码来行动。这时候不是 AI 的错是你的声明过时了。另一个来源是声明写得不够具体。你说遵循项目代码风格但项目里新老代码风格本身就不统一AI 根本不知道听谁的。这种声明等于没写。正确的做法是明确指出新代码沿用最近重构后的风格类型注解完备、函数体短小、遵循模块内现有命名。排查这类问题我的套路很简单先看是不是声明太笼统再看是不是声明和代码矛盾最后才考虑是不是模型本身理解偏差。绝大多数情况下前两个原因就能解释问题。这个排查顺序反过来用就是在浪费时间。6.3 我对声明式记忆的三条铁律写了这么多最后把我的经验浓缩成三条铁律给想实践的朋友一个清晰的切入点。第一条声明式记忆要写事实不要写命令。事实是本项目用 Python 生态命令是请用 Python 写;事实会约束行为命令只会被选择性执行。多写事实少写祈使句。第二条记忆体系要和项目同步演化。每次架构变动、每次依赖升级、每次 AI 踩坑都回到配置文件里去增删条目。文档不更新等于不存在配置不维护等于没有配置。我见过太多项目配置文件写得很漂亮但都是三个月前的旧信息AI 照着做反而出错。第三条先小步试验再扩大范围。不要第一天就搭一个庞大的记忆体系先从几十行的 AGENTS.md 开始跑两周观察 AI 的行为改善再逐步补充。你会发现真正值得写进去的东西往往比想象中少得多。我自己就是从三行配置起步的慢慢迭代到现在几十行每一行都是踩过坑才沉淀下来的。我在实际项目里用了这套方法之后最大的感受是AI 编程助手不再是那个每次都要重新调教的临时工而像一个读过项目手册的熟手——它知道该看哪个文档、该守哪条边界、该跑哪条命令。省下来的时间我拿去做真正需要人的判断力的事情架构设计、代码评审、和业务方对需求。这才是 AI 编程范式转换最有价值的部分。最后再分享一个小技巧把 AGENTS.md 当成一个普通代码文件来对待该改就改该删就删不要有写完了就定型的心理。你越勤快地维护它它回馈给你的效率就越高。 
长河君 · 2026/10/10 4:16:36 · 阅读 1.2k AI编程新范式：用AGENTS.md构建项目记忆体系，告别无状态困境
作为一个从 AI 编程助手刚出现就开始用、到现在几乎每天离不开的人我最近半年最明显的感受是AI 编程的重心正在从怎么把一句话问得更好转向怎么把项目的记忆交给 AI。这两者听起来差别不大但实际开发体验完全是两个世界。围绕 AI 编程范式转换和 Memory 工程业界讨论越来越热而我更关心的是落地怎么让一个无状态的模型真正记住我的项目。最早的时候我打开一个 AI 编程工具相当于请了一个记忆力只有几分钟的临时工。他每次听完需求、动手改完代码你把对话关掉再开一个新会话他就什么都不记得了。项目结构、依赖关系、编码规范、测试命令——所有这些都要重新讲一遍。讲得烦了我就想凭什么这些东西不能写成一份文件让 AI 自己去看这个念头其实就是 Memory 工程的起点。而 AGENTS.md 这类声明式配置文件则是这个思路目前最成熟的落地形态。这篇文章不打算讲虚的就讲我自己从无状态模型的坑里爬出来到逐步建立一套项目记忆体系的过程以及踩过的坑和总结出的实操方法。如果你每天也在和一问三不知的 AI 编程助手较劲这篇文章应该能帮你省下不少重复劳动。1. 无状态模型的困局每次对话都是初次见面1.1 无状态到底是什么意思先把我理解的无状态这个词讲透。一个无状态的对话模型在处理你的每次请求时它看到的只是你发给它的那一段文本——包括系统提示、历史消息、你的新问题以及其他附加上下文。它没有一个持续存在的大脑来记住上次对话的结论。所谓记住本质上只是把过去的文本重新塞进当前这次请求的上下文里。这就带来一个很反直觉的现象你以为 AI 在学习你的项目实际上它只是在你当前这轮对话的可见范围内临时阅读。对话一关、上下文一清它对你项目的理解就归零。我最早踩这个坑的时候很崩溃——上午刚跟工具确认过项目的目录结构和启动方式下午开一个新会话让它写个新功能它又开始瞎猜甚至连我用的是哪个包管理器都能搞错。这个问题的根子在于大语言模型本身没有项目记忆这个组件。它的知识是训练时固化下来的通用知识而你的项目是训练数据里不存在的私有信息。要让 AI 用得顺唯一的办法就是把这些私有信息在每次请求时以可读的形式喂给它。谁喂得全、喂得准谁用起来就顺。1.2 上下文窗口看着很大实际很挤有人可能会说现在模型上下文窗口不是很大吗动辄几十万 token把整个项目塞进去不就行了想法没错但现实很骨感。上下文窗口是物理上限不是推荐用量。我实测过的经验是当喂给模型的上下文越长模型对中间信息的注意力就越容易被稀释回答质量明显下降。这不是玄学注意力机制就是这样的——长文本里模型更容易盯着开头和结尾看中间夹着的关键约束经常被忽略。于是你陷入一个矛盾想让 AI 懂项目就得给它塞大量项目背景但塞太多了它反而抓不住重点。我自己的体会是无脑把 README、全部文档、几十个模块文件全塞进去效果往往不如一份精心写好的、几百行的项目说明文件。这就是为什么记忆的工程化越来越重要——我们要的不是喂得多而是喂得巧。这里有一个常被忽视的细节上下文里的信息不是平等对待的。开头和结尾的信息被模型记住的概率远远大于中间段落。这意味着如果你把项目背景放在一大段杂乱文本的正中间它大概率被淹没。反过来如果项目约定能每次都出现在对话的最前端那它被模型真正采纳的概率会高很多。后面讲的 AGENTS.md之所以有效和这个机制密切相关。1.3 重复沟通的隐性成本无状态还有一个很现实的成本问题时间。我自己统计过早期在项目里用 AI 编程助手平均每次新开会话至少要花 5 到 10 分钟去热身——讲清项目是做什么的、技术栈是什么、目录怎么组织、有哪些约定。一天开十次会话一小时就没了。这还是顺利的情况如果不顺利它给了个完全不符合项目规范的答案你还要花时间纠正成本直接翻倍。更麻烦的是不一致性。同一个项目上午的会话里你告诉它这里的错误处理统一走自定义异常下午的新会话没这个信息它可能就给你写了个裸抛异常。代码风格漂移、架构约定被破坏这些都是无状态带来的隐性债务。等到项目大了这些不统一的地方就是一个一个的雷。我把这段时期的体验总结成一张表方便你对照自己现在的情况无状态协作的典型表现带来的直接后果我当时的解决尝试每次新会话都要重新介绍项目每天浪费大量时间在重复沟通上把项目描述存在备忘录里开新会话时手动粘贴AI 给出的代码风格和项目不一致代码风格漂移审查成本上升反复在对话里强调规范效果不稳定AI 使用错误的构建或测试命令本地环境报错、CI 意外失败把命令写在提示词里但经常被忽略项目架构约定被 AI 无意破坏事后返工需要人工检查边界靠代码审查兜底但效率很低这些问题的本质都指向同一个结论无状态不是模型的 bug而是这个范式的天然属性。我们不可能要求模型自己记住项目但我们可以改变喂给它的方式。这个改变就是 Memory 工程要干的事。2. Memory 工程从临场指挥到制度治理的范式切换2.1 从 Prompt 工程到 Memory 工程前些年大家爱聊 Prompt 工程教你怎么写提示词才能让模型给出好答案。但用久了你会发现单条提示词再精妙它也是一次性的——这条提示词只能服务当前这个任务换一个任务又要重新写。Prompt 工程解决的是单次对话里的表达效率而 AI 编程真正吃掉的成本恰恰发生在多次对话之间的信息衔接上。Memory 工程不一样。它的核心思路是把那些跨任务、跨会话、长期有效的项目信息从对话里临时说变成文件里固定写。写一次长期复用。AI 每次开始工作前先读这些文件相当于入职第一天先看公司制度手册而不是每次干活都要老板口述一遍规矩。打个比方Prompt 工程是每次点菜时跟厨师说清楚口味偏好Memory 工程是把口味偏好做成一张常客档案卡厨师一看档案就知道怎么炒。后者省的不只是一次沟通而是每一次沟通。这也是我为什么认为 Memory 工程会逐渐取代 Prompt 工程成为 AI 编程领域更核心的实操技能——因为它解决的是更根本的效率问题。2.2 记忆分层全局、项目、会话我后来把 AI 编程的记忆体系分成三层这样理解起来非常清晰。第一层是全局记忆。这是关于你个人的、跨项目的偏好比如你习惯用的代码风格、常用的提交信息格式、偏好哪种测试方式。这类信息适合放在全局配置里让所有项目共享一次配置处处生效。第二层是项目记忆。这是针对某个具体项目的约定包括项目结构、架构决策、构建命令、代码规范、常见坑位。这类信息必须跟着项目走换一个项目就不适用了。AGENTS.md 就是这一层的典型载体也是整个记忆体系里最需要花心思治理的部分。第三层是会话记忆。这是当前这次任务里临时产生的信息比如正在改哪个文件、下一步做什么。这层本来就由对话上下文承载不需要持久化但它的作用同样重要——它是前两层记忆的工作台AI 把项目记忆里的规则拿到这里来执行。这三层各有各的存储和读取方式。很多人只盯着会话那一层折腾比如不断把旧对话复制到新对话里反而忽略了最该工程化的全局层和项目层。我的经验是把 80% 的精力放在项目记忆上收益最大——因为项目记忆最具体、最独特、也是最容易一劳永逸的部分。2.3 声明式与指令式一页纸说清两种范式Memory 工程里还有一对关键概念声明式和指令式。这两个词看着学术其实很好懂。指令式是告诉 AI 每一步怎么做。比如你写先读 README然后看 src 目录找到入口文件再检查依赖最后回答我的问题。这种方式很直接但有两个毛病一是啰嗦每条指令都要从头写二是脆弱AI 一旦漏执行某一步后面的结果就飘了。声明式是告诉 AI 项目当前的状态是什么样的。比如你写本项目是 Python 3.11 生态入口在 app 目录测试走统一命令代码风格遵循项目现有约定。AI 读到这些事实自己就知道该怎么行动。它不需要你一步步指挥因为足够多的事实会自动约束它的行为。这两种范式的差别我常常用一个表格来讲维度指令式声明式核心内容做什么、按什么顺序做项目是什么、有哪些约束典型例子先读文档再改代码然后跑测试测试命令是 make test改动必须配套测试复用性一条指令只针对一个任务一份声明覆盖所有相关任务容错性漏执行一步就出错事实够了AI 自己推导路径维护成本每次会话都要重新写写一次长期更新打个更生活化的比方指令式是给导航软件说左转、右转、直行声明式是告诉它目的地是哪里、走高速还是走小路。显然后者更省心也更接近 AI 编程工具应该有的使用方式。AGENTS.md 就是声明式范式的典型落地。3. AGENTS.md把项目的宪法写进仓库根目录3.1 AGENTS.md 是什么以及它凭什么有效AGENTS.md 说白了就是放在项目根目录下的一个 Markdown 文件内容是用自然语言写清楚这个项目的关键信息供 AI 编程工具在开始工作时读取。它不依赖某个特定工具你完全可以把它当成项目里的一份AI 使用手册来维护。它为什么会有效两个原因。第一它的位置固定——放在根目录任何工具、任何会话只要想了解项目第一个去翻的就是根目录这个文件天然容易被发现。第二它的格式是 Markdown——模型的训练语料里 Markdown 占很大比重解析起来毫无障碍即使没有任何特殊工具支持你直接把文件内容贴给模型它也能理解。我在实际项目中验证过同样的任务有 AGENTS.md 的项目AI 给出可用代码的概率明显更高没有的项目经常要来回纠正三四轮。这让我彻底相信这个文件不是花架子而是真正能改变 AI 工作质量的基础设施。每个接到 AI 编程任务的开发者都应该先问一句我的项目根目录里有没有这样一份给 AI 看的说明书3.2 工具读取它的典型流程为了说清楚它怎么生效我描述一下我观察到的典型流程。当你让 AI 编程工具开始处理一个新任务时工具通常会做这几件事第一步扫描项目根目录寻找 AGENTS.md 这类约定文件。找到后把它作为系统级别的上下文注入到本次对话的最前端。这一步是整个流程的关键——项目约定不是在对话中途被提到而是从第一条消息开始就端端正正地摆在模型面前。第二步如果有其他配套的说明文件比如文档索引、架构文档、README工具可能会按 AGENTS.md 里的引用提示进一步加载相关材料。这一步让配置文件的辐射范围可以延伸到整个文档体系。第三步你的具体任务指令进来后模型看到的是项目约定 文档引用 你的问题三段信息的组合。它先理解项目约定再回答你的问题。这个过程里最妙的一点是项目约定永远出现在对话的前端。还记得前面说的注意力机制吧前端信息是模型最容易关注的区域。把项目宪法放在最前面就等于强制让 AI先看制度再干活这比任何提示词技巧都管用。我后来甚至习惯在 AGENTS.md 开头就写上一句在回答任何问题之前先阅读本文件并遵守其中所有约定效果非常稳。3.3 一个可以拿来就用的 AGENTS.md 模板我不喜欢空谈概念直接上一个我在实际项目里沉淀出来的模板。这份模板覆盖了 AI 干活最常踩的几类坑项目定位、技术栈、目录结构、命令、代码约定。我把模板按项目实际情况删改核心骨架如下# 项目指南 ## 项目定位 本项目是一个 [一句话说清项目做什么] 的工具/服务。 核心目标用户是 [谁在用]核心业务价值是 [解决什么问题]。 ## 技术栈 - 语言/运行时[如 Python 3.11] - 核心框架[如项目使用的 Web 框架] - 数据库/缓存[如关系型数据库 缓存服务] - 包管理器[如项目实际使用的包管理器] ## 目录结构 - src/app业务逻辑入口所有新功能优先放在这里 - src/core与业务无关的通用能力日志、配置、异常 - tests测试目录与 src 保持镜像结构 - docs架构决策记录修改核心逻辑前先查看 ## 常用命令 - 安装依赖make install - 本地开发make dev - 运行测试make test - 代码检查make lint ## 架构约定 - 所有业务错误必须使用自定义异常禁止裸抛通用异常 - 数据访问统一走仓库层业务层禁止直接操作数据库 - 新增对外接口必须附带文档注释 ## 风格要求 - 代码遵循项目现有风格优先模仿相邻文件的写法 - 函数命名用动词开头变量命名用名词 - 注释说明为什么不解释是什么注意这份模板的关键不是字段多而是每一条都有信息量。我曾经见过有人把 AGENTS.md 写成两千字的散文AI 读完依然抓不住重点。好的声明式配置要像 API 文档一样精炼每一句都是可验证的事实而不是可读可不读的废话。4. 实战拆解从零搭建一份项目声明式记忆4.1 先梳理不变事实写配置前的准备动手写 AGENTS.md 之前我建议你先做一件事把项目里那些三个月内不会变的事实列出来。这些事实就是声明的素材。我一般会按这几个问题来梳理第一这个项目到底在做什么不要写一个电商系统这种空话要写面向中小商户的库存管理服务核心是提供实时的库存对账能力。AI 只有知道项目在做什么才能在你让它改功能时做出合理判断——它不会把支付模块的逻辑顺手套到库存模块上。第二技术选型是什么语言、框架、包管理器、数据库这些是对编写代码影响最大的硬约束。我见过 AI 在一个用 Python 的项目里给你生成其他语言的依赖安装指令就是因为缺少这一条声明。第三有哪些规矩错误处理方式、目录职责、数据访问边界、测试要求、代码风格。这些是项目长期演化形成的行为准则新成员包括 AI最需要的就是这类信息。把这个清单整理出来你就完成了 80% 的配置工作。剩下的只是把它组织成 AGENTS.md 的格式。这个过程本身也有价值——你会发现很多你以为团队心里都清楚的约定一旦要写出来才发现根本没达成过共识。这份文件顺便成了团队对齐的工具。4.2 把常用命令写成契约项目里的常用命令是最容易被忽略、但其实价值极高的配置项。原因很简单AI 要跑测试、要起服务、要装依赖如果它不知道正确命令就会自己脑补一个然后在你的环境里跑出一堆莫名其妙的错误。我习惯在 AGENTS.md 里用一个命令契约区块把关键操作和它对应的命令一一写清。比如安装依赖make install注意不要直接调包管理器安装会动锁定文件运行测试make test单元测试make test-e2e端到端测试启动开发服务make dev构建产物make build每个命令后面我会顺手写一句为什么是这个命令。比如不要直接调包管理器安装这句备注看着多余实际非常关键。AI 看到这个约束就不会擅自换命令你的 CI 也不会因为依赖锁定文件被改动而无辜挂掉。顺带说一句命令契约要定期核对。项目升级、脚手架换掉命令也会变。我见过有人 AGENTS.md 里写着上古时期的启动命令项目早换成新框架了AI 照着旧命令跑自然各种报错。配置文件不维护比没有配置文件更误事——因为你会盲目信任它直到被它坑了才反应过来。4.3 架构约定要写边界不要写代码写架构约定这块很多人容易跑偏把 AGENTS.md 写成了代码规范大全什么变量命名、缩进几格、用单引号还是双引号都写上。我倒觉得这类纯风格问题可以交给格式化工具去管AI 编程工具基本都会遵守现成的格式配置。真正需要写进声明文件的是边界——哪些模块可以碰什么什么绝对不能碰。举个例子我负责过一个数据迁移项目最核心的边界是禁止在业务代码里直接更新生产数据。我在 AGENTS.md 里把这个写成一条铁律并说明原因迁移逻辑必须经过审批脚本直接操作会导致数据不一致且无法回溯。加了这个声明之后AI 生成代码时明显收敛了很多再也没有出现过顺手写个更新语句的情况。再比如有的项目里所有对外接口都必须走统一鉴权有的项目里配置项禁止硬编码必须走配置中心。这些边界AI 在代码里是看不出来的只有显式写出来它才知道。声明式配置真正的价值就是把这些看不见的规矩变成 AI 可见的约束。写边界还有一层好处它逼着你自己想清楚项目的底线在哪里这本身就是一次很好的架构复盘。4.4 让配置文件跟着项目一起演进AGENTS.md 不是一次写完之后就永久不变的静态文件它应该和你项目的架构决策一样持续演进。我自己的习惯是每次遇到AI 因为不知道某个信息而犯错的情况就把这个信息补进去每次架构发生变动就同步更新相关条目。举个例子。有次我让 AI 重构一个模块的错误处理逻辑它自作主张引入了一个第三方库理由是可以简化代码。问题是我们的项目对第三方依赖引入有严格审查流程它不知道这个规矩就踩线了。那次之后我立刻在 AGENTS.md 里加了一条引入新的第三方依赖前先向用户确认并获得批准。从那以后再也没犯过同样的错。所以我把 AGENTS.md 当成一个活的文档AI 犯错就是文档内容有缺口文档有缺口就补上。项目在变这个文件也要跟着变。它不是摆设是你和 AI 协作的契约文本。我甚至会把每次补丁的日期和原因写成注释Markdown 里可以写在末尾这样过几个月回头看还能知道当年为什么定下某条规矩。5. 从单文件到记忆体系拆分文档、分级治理、团队同步5.1 单文件什么时候该拆AGENTS.md 做得再精炼也有体积上限。当项目复杂度上来比如有十几个模块、数百个文件时把所有信息塞进一个文件会让文件变得臃肿AI 读取时反而不容易抓住重点。这时候我建议做拆分。核心思路是根目录的 AGENTS.md 只保留全局不变的规则和指向详细文档的索引具体的技术细节放到各自的文档里通过相对路径引用。我常用的拆分方式是这样的根目录的 AGENTS.md项目定位、技术栈、核心边界、命令契约、文档索引docs/architecture.md架构决策、模块边界、关键流程docs/testing.md测试策略、测试数据说明、覆盖率要求docs/operations.md部署方式、环境变量、运维注意事项AGENTS.md 里的索引可以这么写## 文档索引 - 架构说明docs/architecture.md修改模块边界前必读 - 测试策略docs/testing.md新增测试前必读 - 运维说明docs/operations.md涉及部署配置时必读这样的好处是AI 不会一上来就淹没在几十页文档里但它知道去哪里找什么。真遇到相关任务时它会按索引去加载对应文档。这就像给 AI 配了一份项目版的知识地图比起一次性把全部知识灌输给它效果更好。我实测的感受是拆完之后 AI 在具体任务上的命中率明显提升因为它不再被无关信息干扰。5.2 全局记忆与项目记忆怎么协同前面提到记忆分层这里展开说说全局记忆和项目记忆怎么配合。全局记忆适合放那些你在任何项目里都坚持的做法。比如我自己固定的偏好是提交信息用统一的约定式风格生成代码时优先写类型注解注释必须解释为什么而不是复述代码。这些偏好放全局配置里所有项目自动生效。项目记忆放的是这个项目特有的约定优先级应该高于全局。比如你的项目本身不写类型注解那全局优先写类型注解的偏好就要服从项目的既有风格。我用一个简单的优先级原则项目级声明 全局声明 模型默认行为。实际配置时如果项目里有不同意见就写在项目级文件里项目里没提到的才轮得到全局偏好来兜底。这样层级清楚AI 的行为就可预期。如果你有两个记忆来源发生冲突AI 不知道该听谁的它就会随机应变——这恰恰是我们要避免的。5.3 团队协作里的记忆治理当 AGENTS.md 不只是你一个人的工具而是整个团队都在用时它就成了团队知识资产的一部分。这时候有两个新问题谁来维护变了怎么同步我的做法是把它纳入代码评审流程。任何修改 AGENTS.md 的变更必须有明确的理由——通常是AI 犯了某个错误补充某条声明可以避免。这样既防止有人随手乱改也让文件每次变更都有迹可循。还有一个细节AGENTS.md 的变更最好和它所描述的代码改动一起提交。如果架构变了你先合代码、后改文档中间这段时间 AI 拿到的还是旧约束就可能产出不符合新架构的代码。把文档变更和代码变更绑在一起能让记忆体系和代码库始终保持同步。团队协作还有一个好处不同成员的踩坑经验可以沉淀到同一个文件里。我负责某个模块某天发现 AI 总是不写事务边界补充一条声明同事负责另一个模块也可能发现别的坑再补一条。几个月下来这个文件就成了团队和 AI 协作的共同智慧库价值远超任何一个人的单打独斗。这也是我见过的最好的文档形态——它不是为了应付检查写的是真的有人在用、有人在更新。6. 踩坑记录声明式记忆的边界与我的三条铁律6.1 配置过度的反面教材声明式配置不是越多越好这一点我栽过跟头。有段时间我特别兴奋把能想到的约束全写进了 AGENTS.md。从代码风格、目录规范、接口命名、日志格式、异常码规则洋洋洒洒写了上千行。结果呢AI 反而变笨了——因为它要在处理任务前先消化一大堆约束注意力被分散真正重要的边界反而容易被淹没在长篇大论里。那次之后我做了个减法实验只保留 20% 最核心的约束把其余全删掉。效果立刻回升。我总结出的规律是AGENTS.md 应该像一部宪法的总纲而不是法条汇编。只写那些不写就会出大问题的规则其余细节交给格式化工具、模板代码和代码审查去解决。如果你不确定某条规则该不该写我建议用这个标准问自己假设 AI 不知道这条规则它犯错的概率有多大犯错造成的代价有多大两者都高才值得写。用这个标准过滤一遍你会发现能写进文件的东西其实比想象中少很多。6.2 声明与实际行为冲突的排查方法还有一种经常遇到的情况AGENTS.md 里写了规则但 AI 还是违反了。不要急着骂 AI 不听话先检查是不是声明本身有问题。最常见的冲突来源是声明与代码现状不一致。比如你写所有接口必须走统一网关但代码里明明有直接暴露的接口。模型读到声明又看到代码发现两者矛盾它就会困惑倾向于按看到的具体代码来行动。这时候不是 AI 的错是你的声明过时了。另一个来源是声明写得不够具体。你说遵循项目代码风格但项目里新老代码风格本身就不统一AI 根本不知道听谁的。这种声明等于没写。正确的做法是明确指出新代码沿用最近重构后的风格类型注解完备、函数体短小、遵循模块内现有命名。排查这类问题我的套路很简单先看是不是声明太笼统再看是不是声明和代码矛盾最后才考虑是不是模型本身理解偏差。绝大多数情况下前两个原因就能解释问题。这个排查顺序反过来用就是在浪费时间。6.3 我对声明式记忆的三条铁律写了这么多最后把我的经验浓缩成三条铁律给想实践的朋友一个清晰的切入点。第一条声明式记忆要写事实不要写命令。事实是本项目用 Python 生态命令是请用 Python 写;事实会约束行为命令只会被选择性执行。多写事实少写祈使句。第二条记忆体系要和项目同步演化。每次架构变动、每次依赖升级、每次 AI 踩坑都回到配置文件里去增删条目。文档不更新等于不存在配置不维护等于没有配置。我见过太多项目配置文件写得很漂亮但都是三个月前的旧信息AI 照着做反而出错。第三条先小步试验再扩大范围。不要第一天就搭一个庞大的记忆体系先从几十行的 AGENTS.md 开始跑两周观察 AI 的行为改善再逐步补充。你会发现真正值得写进去的东西往往比想象中少得多。我自己就是从三行配置起步的慢慢迭代到现在几十行每一行都是踩过坑才沉淀下来的。我在实际项目里用了这套方法之后最大的感受是AI 编程助手不再是那个每次都要重新调教的临时工而像一个读过项目手册的熟手——它知道该看哪个文档、该守哪条边界、该跑哪条命令。省下来的时间我拿去做真正需要人的判断力的事情架构设计、代码评审、和业务方对需求。这才是 AI 编程范式转换最有价值的部分。最后再分享一个小技巧把 AGENTS.md 当成一个普通代码文件来对待该改就改该删就删不要有写完了就定型的心理。你越勤快地维护它它回馈给你的效率就越高。