这两年做 AI 辅助开发有一个感受特别深模型的能力一直在涨但它在项目里的“记性”始终是那块短板。你用同一个工具今天聊清楚了模块边界、数据流向、哪些文件不能动明天重新开一个会话它又全忘了。你只能一遍遍地把项目结构、构建命令、代码规范贴进上下文然后眼睁睁看着它在不该改的地方乱动。这个问题的根源恰恰就藏在“无状态模型”这四个字里。围绕这个痛点行业内其实已经走过了两条路一条是给模型补记忆的 Memory 工程另一条是近两年才真正火起来的 AGENTS.md 声明式配置。这两种思路不是替代关系而是一次编程范式的转换——从“无状态模型 每次现场沟通”走向“有状态协作 一次性约定”。这篇文章不是纯概念科普我想把它讲成一段可以落地的演进记录无状态模型到底卡在哪Memory 工程补了什么、又漏了什么AGENTS.md 为什么能补上这块以及我实际给项目写配置时踩过的坑。适合正在重度使用 AI 编程助手、又受够了反复“调教”的工程师也适合对 AI 编码工具链有兴趣、想弄明白背后机制的人。文中我会给出一份可以直接抄的配置模板以及几个容易踩但不有人明说的细节。1. 无状态模型的本质与 AI 编程的第一性困境1.1 无状态到底意味着什么每次对话都是一次“失忆”开机先说一个最容易被忽略的基本事实绝大多数 AI 编程工具背后的大语言模型在 API 层面是“无状态”的。所谓无状态是指每次请求之间没有任何天然的记忆模型处理完一次输入、给完一次输出这段对话就结束了。开发者如果想要让模型“想起”稍早前的内容唯一的办法是把那些内容重新拼进下一次请求的输入里。这个机制很像一个极端场景你面前坐着一个非常聪明、但患有严重短期失忆的实习生你每说一句话他都当你是第一次开口。你只能在每次开口时把前因后果、背景材料全部塞进一张纸上递给他。那张纸就是上下文窗口内容一多前面的字就被挤掉了。理解这一点才能理解后面所有的问题。所谓“AI 编程助手”在无状态约束下的本质工作方式就是“一次性输入 一次性输出”。工具本身或许会在产品层面帮你缓存对话历史但缓存不等于记忆——它只是把你和模型之间发生过的内容再翻出来重新放进上下文窗口。缓存一断、会话一重启一切归零。1.2 失忆现场AI 编程中最典型的几个崩坏场景无状态带来的失忆在真实开发流程里非常具体我列几个你一定见过的现场换会话后失忆。早上你和工具一起梳理了某个老项目的三层架构约定好“所有数据库访问必须走仓储层”。下午开新会话让它加个功能它直接绕过仓储层在控制器里裸写查询。长对话末尾被人为截断。聊了一个小时上下文窗口快满了工具开始“忘了”最开始的架构约束甚至为了节省 token 自己压缩历史摘要。摘要一压缩细节丢失。多文件修改时缺少全局观。让它重构一个函数它只改了函数本体不改所有调用方因为调用关系在之前几轮对话里出现过但现在已经滑出窗口了。执行链断裂。你让它跑测试、发现失败、修复、再跑这一整套动作如果跨了多个会话它每次都要重新理解“项目怎么跑测试”“当前的失败是什么”。这些现场的共同点是什么不是模型能力不足而是模型根本没有一个跨越时间的稳定记忆载体。能力再强也架不住每次都是全新的开局。1.3 提示工程的手动补偿为什么撑不住既然无状态是前提那早期几乎所有团队的做法就是用提示工程去补偿。典型操作有三种把项目约定写进系统提示词、在每次会话开头复制一段“项目须知”、或者干脆搞一个巨大的 prompt 模板让工具每次先读一段自我介绍再开始干活。这三种做法我全都试过结论是短期有效长期痛苦。第一上下文窗口是稀缺资源你把几 KB 的项目约定塞进去留给真实代码和任务的空间就少了尤其是处理长文件、大改动的场景非常吃亏。第二这种“须知”是人肉维护的和代码仓库脱节项目一改提示词忘了改工具拿着过时约定反而帮倒忙。第三每个开发者自己存一份模板格式五花八门团队内部根本没有统一口径。这其实是“无状态模型”时代的一种必然挣扎——你把记忆硬塞进每次对话的输入里代价高昂还不可持续。所以行业内开始认真想过一个问题能不能给模型一个真正的外置大脑这就是 Memory 工程。2. Memory 工程为模型搭一个外置大脑2.1 Memory 工程的核心命题把上下文变成可管理资产Memory 工程的目标很简单让模型在多个会话、多个任务之间保留并复用信息而不是每次从零开始。这个概念最初是从对话机器人领域火起来的后来被引入 AI 编程工具链。它的核心思路是把“对话历史”“项目知识”“用户偏好”这些信息从易失的上下文窗口里抽出来放到一个可读写、可检索、可持续更新的存储层。我习惯把这里的记忆分成两层短期记忆和长期记忆。短期记忆就是当前会话内来回传递的对话历史和当前任务状态它生命周期短但实时性最强。长期记忆则需要跨会话存活比如一个项目的架构决策、API 约定、目录规范、团队成员的工作习惯。AI 编程真正缺的主要是长期记忆——它要能在新会话开始时自动“想起”这个项目是什么、应该怎么干。2.2 记忆的四种常见载体与取舍行业内做长期记忆主流有四种载体各有各的适用场景对话摘要。把每次会话的关键结论自动缩写成摘要下次会话开始时加载。轻量但丢失细节摘要本身就是有损压缩。记忆文件。用一个或多个文本文件如项目说明、约定文档存放关键信息会话开始时让工具读取。直观、可控但依赖人工维护。向量数据库 / RAG 检索。把项目文档、代码注释、历史对话切片做成向量索引工具根据任务语义自动检索相关内容。自动化程度高但需要额外基础设施同时存在检索不精确的问题。自动记忆模块。部分工具提供了记忆插件自动记录用户偏好和历史决策下次自动调用。体验好但黑盒属性强你不知道它记住了什么、什么时候会忘。如果把这些方案并排放在一起能明显看到一个矛盾越自动的方案越不可控越可控的方案越依赖人工。向量检索很聪明但它是猜你要什么而不是明确告诉你“这个项目就是这样”对话摘要很方便但压缩过程中会丢掉棱角人工记忆文件最可靠但维护成本全部压在人身上。2.3 早期 Memory 工程的局限记忆和代码仓库脱节我实际用下来早期的 Memory 工程方案有一个通病记忆被放在项目之外。你的摘要存在工具的本地配置里向量库存在数据库或云端自动记忆模块存在工具自己的存储空间。这些记忆跟代码仓库没有版本关系项目迭代了记忆却可能还停留在三个月前。而且它们基本是私有数据换一台机器、换一个工具、加一个协作同事记忆就断档了。更隐蔽的问题是被动性。记忆系统做得再好它也是在“模型需要时”去查、去读模型自己并不知道哪些信息是这个项目里不可违背的硬约束。你可以让摘要里写“不允许改用户表结构”但模型仍然可能忽略——因为在它看来那只是一条参考信息不是行为边界。这些局限让我意识到光靠“给模型补记忆”是不够的记忆必须升级成一种项目层面的、对模型有强制力的“约定”。于是 AGENTS.md 这种声明式配置开始进入视野——它不是给模型提供背景知识而是直接告诉模型在这个项目里什么必须做、什么不能做、按什么流程做。3. AGENTS.md 声明式配置从每次解释到一次性约定3.1 AGENTS.md 到底是什么给智能体看的 READMEAGENTS.md 本质上是一个放在项目根目录或子目录的 Markdown 文件里面用结构化、声明式的语言描述这个项目的“智能体行为契约”。当 AI 编程工具进入项目时会自动读取这个文件把它当作理解项目、规范自身行为的第一手资料。你可以把它类比成给智能体看的 README传统 README 是写给人类开发者看的介绍项目是什么、怎么跑起来而 AGENTS.md 是写给 AI 智能体看的重点不止于此还包含你在编程协作中希望它遵守的规则和边界。一次声明之后每次会话都自动生效不需要你再复制粘贴。这个思路最大的变化是把“记忆”从工具的私有存储里解放出来放进项目的版本控制里。AGENTS.md 成为代码仓库的一部分跟着代码一起演进、一起审查、一起被所有人分享。记忆从此变成了协作资产而不是某个人的私有配置。3.2 它解决的是提示工程里最无解的隐性知识问题为什么说 AGENTS.md 补上了记忆工程漏掉的那块因为它解决的是“隐性知识显性化”的问题。任何项目里都有一堆没人写进文档、但老手默认知道的事情这个模块虽然叫 payment但里面核心逻辑是库存锁定那个脚本只在本地调试用CI 里绝对不能跑后端改了接口前端类型总是人马不停蹄地对齐……这些知识以前存在于老成员的脑子里新人靠问、靠踩坑才能积累AI 工具则靠每次会话里被反复重申才能勉强不犯错。AGENTS.md 给了它们一个标准落点你把所有想对智能体讲的边界和流程写进去工具启动时必读、且按此执行。这比任何 RAG 检索都更直接——不需要模型去“猜测”这个项目的规矩项目自己把规矩说清楚了。3.3 配置里到底该写什么核心板块拆解根据我给多个项目写 AGENTS.md 的经验一份好配置通常包含六个板块每个板块对应一类信息项目一句话概述。告诉智能体“你在哪个项目里、这个项目是干嘛的”避免它用通用知识误解代码意图。技术栈与目录地图。列出主要语言、框架、关键目录职责。这点特别适合 monorepo能帮工具快速锁定改动范围。常用命令清单。构建、测试、lint、单测、特定环境的命令要写清楚而且必须是真实可用的命令不是“建议参考 package.json”。代码风格与约束。缩进、命名、组件组织、接口设计约定越具体越好。架构边界与禁区。哪些层之间不能直接调用、哪些表不能随便动、哪些文件是生成的不要手动改。这部分最提气因为它直接阻止了模型干蠢事。工作流约定。改完代码要不要跑测试、提交前要做哪些检查、遇到 API 变更的第一动作是什么。实际写的时候很多人会犯一个毛病把 AGENTS.md 写成一本代码规范书。其实它应该更像一份“作战简报”——短、准、可执行每一条都能直接约束行为而不是表决心的废话。3.4 和同类配置的对比为什么“声明式”是范式转换现在市面上的 AI 编程工具不少都已支持“项目级规范文件”的机制有些以工具名命名、有些沿用通用约定AGENTS.md 是目前被讨论最多的一种开放形式。把它们放在一起看能更清楚看到趋势维度传统 README / 文档工具私有记忆 / 向量检索AGENTS.md 声明式配置目标读者人类开发者AI 模型被动获取AI 智能体主动读取存储位置代码仓库工具本地 / 外部存储代码仓库 / 版本控制更新方式人工维护自动/半自动人工维护 代码评审强制力无弱可能不加载强启动必读跨工具通用是否是开放性约定维护成本中低但不可控中但可控这张表背后是一次看待 AI 协作方式的范式转换以前我们默认模型是“无状态的临时工”于是每次都得面试式地把规矩讲一遍记忆工程则是试图给临时工开小灶而 AGENTS.md 的思路是把“这个项目怎么干活”直接做成了标准合同一入职就自动签好。用工程化的语言说就是把每次对话都要重新博弈的高成本协商变成了一次低成本、可版本管理的配置协商。这就是“声明式”三个字的真正分量。4. 实操为项目编写一份高质量 AGENTS.md4.1 写之前先用三个问题盘点项目事实动手写配置前先不要打开编辑器而是先回答三个问题这个项目是怎么被构建和测试的这个项目里有哪些“看不见但很重要”的约束哪些代码我绝对不想让 AI 动我通常会在终端里快速收集信息。先用 ls 和 find 摸清目录结构再看 README 和根目录下的配置文件确认技术栈翻几眼 package.json、pyproject.toml、go.mod 这类文件拿到命令入口。最关键的一步是看最近两位数的 git log 提交记录从中找到那些反复出现的模式大家改哪些文件、提交前做什么检查、哪块代码一直出问题。这个过程能帮你把“我认为项目是这样”和“项目实际是这样”对齐。我知道有人会嫌麻烦但 AGENTS.md 的价值是长尾的前期盘点做得越真实后面工具帮你省的时间越多。4.2 一份可以直接抄的配置模板下面是我在内部项目里长期使用的精简模板你可以直接拿过去改。需要注意模板只是骨架具体内容必须来自你项目的事实不能照抄。# AGENTS.md ## 项目概述 这是一个基于 XX 框架的 YY 服务主要负责提供 ZZ 能力。 代码采用分层架构接入层 / 业务层 / 数据层禁止跨层调用。 ## 常用命令 - 安装依赖npm install - 本地开发npm run dev - 运行测试npm test - 类型检查npx tsc --noEmit - 代码检查npm run lint ## 目录地图 - src/apiHTTP 接口定义所有路由入口只允许出现在这里 - src/services业务逻辑一个 service 文件只处理一个业务域 - src/repositories数据访问层所有数据库操作必须经过这里 - src/generated生成代码永远不要手动修改改完重新生成 ## 代码约束 - 接口返回统一用标准响应格式错误码定义见 docs/error-codes.md - 数据库表结构变更必须走迁移脚本禁止直接改历史迁移文件 - 新增第三方依赖前先查一下是否已有同类依赖 ## 工作流 1. 修改代码后必须运行 npm run lint通过后再提 MR/PR 2. 涉及数据层的变更必须在提交说明中标注影响的表 3. 如果测试失败先修复导致失败的代码再重跑测试写这份文件的几个要点每条都不能有歧义比如“禁止直接改”就比“尽量别改”有效得多命令必须是实际跑过、验证过的不能凭感觉写涉及链接的地方直接指向仓库内的文档路径让工具能自己打开。4.3 怎么验证配置真的生效了很多人写完 AGENTS.md就以为万事大吉。我见过最坑的情况是配置写了一长串工具根本就没读而作者浑然不知。所以落地之后必须做一轮验证。我的验证套路分三步。第一步新建会话故意问工具两个问题“这个项目怎么运行测试”“这个项目里哪些目录是不能手动改的”看回答内容是否来自你的 AGENTS.md。如果它答得和文件里一致说明加载链路通了。第二步给它布置一个轻微“越界”的任务——比如让它在 src/generated 里改一行代码看它会不会主动拒绝或提示“根据项目约定此文件不应手动修改”。第三步有条件的话开工具的执行日志确认每次会话启动时 AGENTS.md 是否被读取以及被读取的目录范围。这三步走完你对这份配置是“真合同”还是“摆设”就有了确切答案。4.4 避坑指南我从实盘里总结的五个反模式写 AGENTS.md 踩过的坑远比写的过程多。这里列几个最常见的给后来人排雷把配置写成散文。大段描述性文字对模型的理解帮助有限声明式配置功夫在结构化、条文化的约束上每条最好能独立生效。写过多无效信息。“使用代码质量较高的方式”“优雅地处理错误”这类话等于没说模型不知道你心里的“优雅”到底是什么。宁可写“错误响应必须包含 code 和 message 两个字段”。命令没有验证。写测试命令之前自己先跑一遍确保命令真的存在、真的能跑通。机器人可不会帮你圆场。混入过期信息。AGENTS.md 不是一次性文件它跟着项目走。技术栈换了、目录重构了、命令变了都要同步更新否则就是给工具喂过期的地图。试图一文件管所有。单个根目录文件适合中小项目大型仓库建议根目录只写全局约定子模块用独立的嵌套配置细分避免主文件膨胀。5. 常见问题与排查技巧实录5.1 配置好像没生效先检查这四个地方遇到 AGENTS.md 没生效先别急着怀疑工具坏。我通常按这个顺序排查第一文件位置是否正确——必须是项目根目录名称大小写要严格符合约定第二文件编码是否为 UTF-8有时候用其他编码会导致识别异常第三工具是否真正重启多数工具只在会话启动时加载配置改完文件必须开新会话第四确认这类配置文件没有被工具的忽略机制排除掉比如有些只能读特定名称的规范文件。这一套下来八成问题都能定位。剩下的要么是工具不支持、要么是加载链路太深需要去翻工具的文档确认支持范围。5.2 指令冲突了怎么办谁能覆盖谁在项目里同时存在多个规范文件时冲突不可避免。比如根目录 AGENTS.md 说了“所有路由必须走 api 目录”但子模块的配置文件里写了“本模块独立路由”工具听谁的我的经验是约定一个明确的优先级规则并把规则写进根目录文件的开头。常见做法是子目录配置优先于根目录配置因为它更接近具体代码描述的场景更准确同一目录下项目级约定优先于工具私有配置因为前者被代码评审控制后者可能存在个人偏好。冲突时不要指望工具自己判断你必须在文件里明确写出来让规则本身没有歧义。5.3 文件越来越长token 开销变大怎么收敛瘦身和落地是同步的工程不是头痛医头。如果发现 AGENTS.md 越来越长、上下文窗口摄入开销明显我会做三个动作。第一步内容分级把“必须遵守的硬约束”留在 AGENTS.md把“背景知识、细节指南”挪到 docs 子目录在文件里只留链接。第二步压缩表达能用表格和列表演达的不要写成句子两行表格往往能替代八行文字。第三步动态加载如果工具支持按目录递归读取根目录只放全局信息细分约定下沉到具体模块这样大多时候工具只读跟手头任务相关的那份而不是每次都吞下整个仓库的规范。5.4 团队协作怎么让规范文件不过期AGENTS.md 最大的风险不是写不好而是没人维护。我的做法是把它当成一等公民对待进代码评审范围谁动了目录结构谁来同步更新通过 CI 脚本校验关键命令是否仍然存在于配置文件里每隔一段时间专门安排一次“规范对账”拿真实任务测试配置有没有过时。听起来繁琐但比每次新人都来问“这个项目怎么跑”要省得多。另一个值得提的点是把 AGENTS.md 纳入团队 onboarding 流程。新人进项目第一件事是读这份文件再让他在工具里开个会话验证 AI 的回答是否和文件一致。这个动作能同时检验规范和工具链的健康度一举两得。6. 个人体会与后续扩展6.1 用了 AGENTS.md 之后我对 AI 编程的心态变了对我来说AGENTS.md 最大的意义不是让 AI 少犯错而是把我和 AI 协作的方式从“每次现场调教”变成了“事先约定好再开工”。以前新会话启动我总是抱着“这次它会不会又乱来”的警惕现在只要项目根目录有这份文件开新会话的焦虑感会低很多因为我知道初始约束已经就位了。心态转变也带动了工作方式的变化。以前写代码前要花时间在对话里描述任务背景现在背景都写在配置文件里我可以直接把精力投到更具体的业务逻辑上。这个体验就像从“每天面试一个新实习生”变成“团队里固定有一个熟悉项目规矩的老成员”。6.2 顺着这个思路我还在玩两件事AGENTS.md 只是一个起点。我现在在尝试把它和 Memory 工程的其他手段组合成一套分层记忆AGENTS.md 负责静态约定向量检索负责动态知识会话摘要负责短期上下文。静态约定保证底线动态检索负责喂料短期上下文负责临场发挥。三者各管一段效果比单一手段好用得多。第二件事是用脚本自动生成 AGENTS.md 的项目事实部分。我写了一个小工具扫描项目结构、提取命令入口、解析目录注释自动生成配置的初稿人工再补充业务约束。这样既降低了写配置的启动成本也保证基础信息不过期。后面如果有精力我甚至想把它接进 CI每次代码更新都自动 diff 一下配置文件是否过时。说到底AI 编程的前沿不只在模型参数里也在于我们怎么组织人和模型协作的上下文。AGENTS.md 这类声明式配置用最小的成本把这个组织过程工程化了。我个人的体会是别把它当成又一个要维护的文档把它当成你写给智能体的第一行代码——这行代码写好了后面所有对话都会顺畅很多。