★ FEATURED ARTICLE 1. 从每次重新解释一遍说起无状态模型到底卡在哪如果你最近半年深度用过任何一款 AI 编程助手大概率经历过这种循环新开一个会话先花五分钟把项目背景、技术栈、目录约定、命名规范、测试命令一股脑喂进去然后才开始真正干活。等到第二天再开一个会话同样的五分钟又得重来一遍。模型本身没有任何记忆它不知道你昨天说过什么也不知道这个仓库里service 层不许直接调 DAO这条铁律。这就是无状态模型的本质困境。大语言模型在单次推理里是失忆的它的全部上下文都来自你这一次塞进去的 token。上下文窗口再大也架不住你每次都从零开始描述。更麻烦的是当项目规模上去之后你根本没法把整个仓库塞进上下文——几万行代码、几十个模块、上百条约定光是把这些描述清楚就够写一篇文档了。我见过太多团队卡在这个阶段AI 写出来的代码风格飘忽不定今天用camelCase明天用snake_case今天把业务逻辑写在 controller 里明天又塞进 util。你以为是模型不行其实是你从来没告诉过它这个项目到底长什么样。问题的根子不在模型能力而在上下文供给方式。于是就有了AI 编程范式转换这个说法。它指的不是模型本身变强了而是我们使用模型的方式发生了根本变化从每次对话临时喂上下文转向把项目知识沉淀成模型可读的持久化配置。这个沉淀的载体就是标题里说的AGENTS.md这类声明式配置文件。它把散落在开发者脑子里的隐性约定变成模型每次都能读到的显性声明。这篇文章想聊的就是这条演进路径为什么无状态模型会逼出 Memory 工程AGENTS.md 这类声明式配置到底解决了什么问题它和传统的 README、注释、lint 规则有什么区别以及在实际项目里怎么落地、怎么避坑。适合已经用过 AI 编程工具、但总觉得差点意思的开发者也适合正在考虑给团队引入 AI 协作规范的负责人。2. Memory 工程不是给模型加记忆而是给项目建档案很多人第一次听到Memory 工程这个词会下意识理解成给模型装一个记忆模块。这个理解方向偏了。真正的 Memory 工程核心不是改模型而是改项目——把项目里那些原本只存在于老员工脑子里的知识整理成模型能稳定读取的结构化档案。2.1 无状态模型的三个真实痛点先把这个痛点拆细才能理解为什么需要一整套工程方法而不是随手写个 prompt 模板。第一个痛点是上下文漂移。同一个需求你今天描述得详细一点模型输出 A 方案明天描述得简略一点模型输出 B 方案。两次结果都对但风格、结构、依赖选择全不一样。项目里代码越攒越多一致性就越差。这不是模型不稳定是你给的输入本身就不稳定。第二个痛点是知识断层。项目里有些约定是只可意会的比如所有对外接口必须走统一的 response wrapper、数据库迁移脚本必须带 rollback、新增依赖要先在群里同步。这些规则没人写进 README新人靠 code review 被骂几次才记住。模型更惨它连被骂的机会都没有直接写出违规代码。第三个痛点是重复劳动。每次开新会话都要重新交代背景这件事本身就是纯浪费。一个开发者一天开五次会话每次五分钟一天就是二十五分钟纯消耗。团队十个人一年下来这个数字相当可观。2.2 Memory 工程的本质把隐性知识显性化Memory 工程要解决的就是这三件事。它的做法不是去改模型权重而是在项目里建立一套模型可读、人类也可读的知识层。这套知识层有几个特征持久化写在文件里进版本控制不随会话消失。声明式描述是什么和要什么而不是怎么做的步骤脚本。分层项目级、模块级、任务级各有各的配置不混在一起。可执行不只是给人看的说明还能被工具链读取并影响实际行为。这里要区分一个常见误解Memory 工程不等于把 README 喂给模型。README 是给人看的它的组织逻辑是介绍项目而 Memory 配置的组织逻辑是约束模型行为。两者目标不同写法也完全不同。README 可以写本项目是一个电商系统但 Memory 配置要写的是新增 API 必须放在src/api/下文件名用 kebab-case必须导出handler和schema两个成员。前者是介绍后者是契约。2.3 为什么是声明式而不是命令式声明式和命令式的区别用过 Kubernetes 的人应该有直觉。命令式是你先做 A再做 B然后做 C声明式是我要的最终状态是 X你自己想办法达到。放到 AI 编程场景里命令式配置大概长这样第一步读取需求第二步分析现有代码第三步生成新文件……这种写法的问题是它把模型的推理路径写死了遇到稍微不同的任务就失效。而声明式配置写的是本项目使用 TypeScript strict 模式禁止any所有异步函数必须显式处理错误。模型读到这些约束会自己决定怎么在具体任务里满足它们。声明式的另一个好处是可组合。项目级配置管全局约束模块级配置管局部约定任务级配置管当前这次改动的特殊要求。三层叠加模型读到的是一个完整的约束集合而不是一堆互相打架的指令。3. AGENTS.md 到底该写什么一份可落地的字段清单理解了 Memory 工程的定位接下来就是最实际的问题AGENTS.md 这个文件里到底写什么。我见过不少团队兴冲冲建了这个文件结果写成了第二份 README模型读了跟没读一样。问题出在内容选择上。3.1 必须写进去的四类信息根据实际使用经验AGENTS.md 里真正影响模型输出质量的内容集中在四类第一类是技术栈与版本约束。不是笼统写用 React而是写清楚React 18 TypeScript 5.x Vite状态管理用 Zustand 不用 Redux样式用 CSS Modules 不用 styled-components。版本和选型写清楚模型才不会给你生成一堆过时写法或者混用两套方案。第二类是目录结构与文件职责。这是最容易被忽略但收益最大的一块。把src/下的目录树和每个目录的职责写清楚模型生成新文件时就知道该放哪。比如src/ api/ 对外接口层只做参数校验和转发 service/ 业务逻辑层禁止直接操作数据库 repository/ 数据访问层唯一允许写 SQL 的地方 utils/ 纯函数工具禁止有副作用第三类是命名与代码风格约定。文件名、变量名、函数名、常量名的规则以及缩进、引号、分号这些格式约定。这些本来可以交给 lint 工具但写进 AGENTS.md 能让模型在生成阶段就遵守减少后续格式化返工。第四类是禁止事项与边界。这一类的价值最高。明确写出禁止在 service 层引入 HTTP 客户端、禁止修改generated/目录下的文件、禁止新增未在package.json中声明的依赖能挡掉大量低级错误。3.2 不该写进去的三类内容有该写的就有不该写的。以下三类内容写进去反而有害大段业务背景介绍模型不需要知道公司是做什么的它需要知道代码怎么写。业务背景占字数还稀释关键约束。临时性任务说明这次要改哪个 bug、加哪个功能属于任务级上下文不该塞进项目级配置。与代码无关的流程比如提交前要找谁审批这类流程对模型生成代码没有帮助。3.3 一个字段对照表把上面的内容整理成一张表方便对照检查自己的 AGENTS.md 是否完整字段类别是否必写典型内容常见错误技术栈版本必写框架、语言、构建工具及版本只写框架名不写版本目录职责必写目录树 每层职责只列目录不写职责命名风格必写文件/变量/函数命名规则与 lint 配置冲突禁止事项必写明确的红线清单写得太笼统无法判断测试命令建议写单测/集成测试执行方式命令过期未更新业务背景不写公司业务介绍占篇幅稀释约束审批流程不写人工审批节点与代码生成无关这张表不是死的团队可以根据实际情况增减但必写那几行建议一个都别省。4. 从零搭一套 Memory 配置分阶段落地路径知道了写什么接下来是怎么落地。我建议分三个阶段推进不要一上来就追求大而全那样很容易半途而废。4.1 第一阶段单文件起步先跑通闭环最开始不要搞复杂的分层就在项目根目录建一个AGENTS.md把上面说的四类必写信息填进去。这个阶段的目标不是完美而是跑通配置影响输出这个闭环。具体做法先写技术栈和目录职责两块然后随便让模型生成一个小功能观察输出是否符合约定。不符合的地方回头补充对应的约束条目。这个生成—观察—补充的循环跑上几轮文件就自然长出来了。这个阶段有个小技巧用模型帮你写 AGENTS.md。把现有代码库的关键文件丢给模型让它总结出技术栈、目录结构和命名规律你再人工校对。这比从零手写快得多而且能发现一些你自己都没意识到的隐性约定。4.2 第二阶段引入分层处理模块差异当项目里出现多个差异较大的模块时单文件就不够用了。比如前端模块和后端模块的约定完全不同塞在一个文件里会互相干扰。这时候引入分层根目录AGENTS.md放全局约束语言、版本、通用禁止事项。各模块目录下放自己的AGENTS.md写模块特有约定。模型读取时就近的配置优先级更高。分层的关键是避免冲突。全局说用双引号模块说用单引号模型就懵了。所以分层时要明确一条规则模块配置只能补充全局配置不能覆盖全局配置里的硬性约束。硬性约束要改就改全局那份。4.3 第三阶段接入工具链让配置可校验前两个阶段靠人自觉第三阶段要让配置可被工具读取和校验。这一步是 Memory 工程从文档升级为工程的关键。具体做法有几种。一是把 AGENTS.md 里的关键约束抽成机器可读的格式比如 JSON 或 YAML让 CI 流程能校验代码是否符合。二是写一个简单的脚本在提交前检查 AGENTS.md 是否被同步更新——比如新增了目录但没更新目录职责说明就报警。三是把配置接入 AI 工具的读取路径确保模型每次都能读到最新版本。这个阶段投入产出比很高但前提是前两个阶段已经稳定运行。跳过前两步直接上工具链往往因为配置本身还不成熟而白费功夫。5. 踩过的坑声明式配置最容易翻车的五个地方讲完方法论得说说实际踩过的坑。这些坑在官方文档里基本不会写但每一个都能让你白忙活好几天。5.1 配置写成了愿望清单最常见的翻车方式是把 AGENTS.md 写成了一份我希望代码长这样的愿望清单。比如写代码要优雅、命名要清晰、结构要合理。这些描述对模型来说等于没说因为它无法判断什么叫优雅、什么叫清晰。正确的写法是可判定。把命名要清晰换成布尔变量以is/has/should开头函数名用动词开头常量全大写加下划线。这样模型才能对照执行你也能对照检查。5.2 约束之间互相打架第二个坑是约束冲突。比如一处写所有异步操作必须用 async/await另一处写优先使用 Promise 链式调用。模型读到这两条会随机选一条输出就不稳定了。避免这个坑的办法是建立约束的唯一来源。同一条规则只在一个地方定义其他地方引用。如果确实需要例外明确写出例外条件而不是在另一处写一条相反的规则。5.3 配置更新滞后于代码演进第三个坑最隐蔽项目代码已经重构了AGENTS.md 还停留在三个月前的状态。模型读到过时的目录结构生成的文件放错位置你还以为是模型笨。解决办法是把 AGENTS.md 的更新纳入 code review 流程。任何涉及目录结构、技术栈、命名规范的改动都必须同步更新配置。可以在 PR 模板里加一条检查项强制提醒。5.4 把配置当成了一次性任务第四个坑是心态问题。很多团队建完 AGENTS.md 就再也不碰了觉得配置好了就一劳永逸。实际上 Memory 配置是活的它需要随着项目演进持续调整。哪些约束模型总是违反说明写得不够清楚哪些约束从来没被触发过说明可能多余。我自己的习惯是每个月花半小时过一遍 AGENTS.md删掉过时的、补充新出现的、改写模型老是不遵守的。这半小时的投入能省下后面无数次的返工。5.5 忽略了人也要读最后一个坑是把 AGENTS.md 写成了只有模型能懂的机器语言。实际上这个文件新人也要读它是团队约定的载体。如果写得晦涩难懂新人看不懂那它就失去了显性化隐性知识的意义。好的 AGENTS.md 应该人和模型都能顺畅阅读。用清晰的标题分节用列表和表格组织信息关键约束加粗。这样既方便模型解析也方便人查阅。6. 范式转换的真正价值从用工具到建系统聊到这里可以回头看看AI 编程范式转换这个说法到底意味着什么。早期的 AI 编程本质上是用工具——你把模型当成一个更聪明的自动补全用完即走不留痕迹。这个阶段的天花板很低因为每次交互都是孤立的经验无法积累。Memory 工程代表的是另一种思路把 AI 协作当成一个系统来建设。项目知识沉淀成配置配置影响模型输出输出结果又反过来验证和修正配置。这是一个有反馈、能进化的循环。在这个循环里模型的能力只是其中一个变量真正决定上限的是你给它的上下文质量。这个转换对开发者的能力要求也变了。以前比的是谁 prompt 写得巧现在比的是谁能把项目知识整理得清楚、结构化得好。前者是技巧后者是工程。技巧会过时工程能力会沉淀。我个人的体会是认真维护 AGENTS.md 的团队AI 生成代码的可用率能明显高出一截。不是因为模型变强了而是因为输入变干净了。这件事没有捷径就是把项目里那些大家都知道但没人写下来的东西一条一条写清楚。写的过程本身就是一次团队知识的梳理收益远不止于让 AI 少犯错。如果现在就要动手我的建议是从一个模块开始先写十行 AGENTS.md跑一周看看效果再决定要不要推广到整个项目。别追求一步到位Memory 工程是个持续迭代的活儿先跑起来比什么都重要。
阅读完成 · 觉得有帮助？
