如果你已经在用 AI 辅助写代码大概率会有这种感觉它很强但它总是忘事。上午刚跟它对齐过的模块划分下午新开一个会话它就完全不记得了明明仓库里早就写着构建用 pnpm测试用 vitest它还是会随手给你生成 npm 命令。这不是模型不够聪明而是你还没有进入 AI 编程的新范式。这个范式的核心词就是 Memory 工程而 AGENTS.md 声明式配置正是把项目记忆固化下来的最直接做法。这篇文章会把无状态模型的底层逻辑、Memory 工程的落地思路、AGENTS.md 的编写方法与踩坑经验一次讲透适合正在做 AI 驱动开发的工程师、技术负责人以及所有对如何让 AI 助手真正懂你的项目感兴趣的人。1. 无状态模型为什么记不住事范式转换的起点1.1 无状态的本质每次对话都是一次初识大模型的本质是一个无状态函数。你发给它一段输入它给你一段输出除此之外它什么都不保存。今天上午那次对话里讨论的所有内容在它眼里和上个月的对话一样都不存在。它能记住的仅仅是当前上下文窗口里那一堆 token。上下文窗口可以理解成它的工作台你放上去什么它才能看到什么。我经常用一个类比每一次新会话都是给项目派来一个完全没读过简历的新人。这个新人智力在线能写代码、能推理但它对你的项目一无所知。你不把背景交代清楚它就只能在通用常识里瞎猜。猜对了是运气猜错了是常态。过去大家觉得多轮对话能解决记忆问题其实那只是把历史记录硬塞回上下文里一旦超过窗口长度最古老的信息就会被截断模型立刻失忆。这也是为什么很多人在大型项目里越用 AI 越痛苦。代码库里几十个模块、几百个文件、一套独特的分层规范每次新会话都要靠你重新打字复述。说了十分钟它才勉强进入状态等它真正理解项目了一关窗口一切归零。1.2 无状态带来的工程代价这个问题不只是体验不好而是实打实的工程成本。第一个代价是token 浪费。你每次都要把项目的背景、目录结构、技术选型、构建命令重新复制一遍这些重复信息消耗的上下文空间极其可观。上下文窗口是稀缺资源被背景介绍占掉了留给真正代码推理的空间就少了。第二个代价是输出质量不稳定。同一个问题第一天模型给出的方案符合你的架构第二天新会话里它可能给出一个完全跑偏的设计。没有长期约束模型的输出就像没有规章制度的组织每次开会都是新面孔、新议题、新结论。第三个代价更隐蔽——讨论无法积累。你们团队在上一个项目里总结出的禁止在 service 层直接操作数据库所有对外接口必须做参数校验等经验如果不落入某个持久化载体那它们就只存在于某个人的聊天记录里。换一个人、换一个会话这些经验全部蒸发。1.3 范式转换从问答工具到协作者所以过去两年间AI 编程的使用方式出现了一次明显的范式转换。第一代用法是临时问答。把它当搜索引擎用这段代码怎么实现这个报错什么意思用完即走不需要它了解项目。第二代用法是会话补全。开始知道把相关文件贴进去把项目背景写进 prompt让它基于局部信息完成任务。这比第一代强但每次都要手动准备上下文。第三代用法是我现在更推荐的方向叫Memory 工程。思路很简单与其每次临时拼装上下文不如主动设计一套机制让 AI 助手在会话开始时就自动获得项目的关键记忆。它的技术栈、目录约定、架构决策、常见陷阱全部提前注入。你要做的只是把记忆写下来、维护好。从每次重新认识到组装好记忆再来上班这个转变看起来只是流程变化背后是 AI 编程定位的根本升级它不再是你的工具而是你的协作者——一个真正了解项目语境的协作者。2. Memory 工程的思路与分层设计2.1 Memory 工程要解决什么问题Memory 工程直白说就是给 AI 模型设计和管理持久化上下文。模型自身没有记忆能力那我们就用工程手段帮它外挂记忆让它在每次会话开始时能自动加载项目相关的规则、事实和偏好。它和 Prompt Engineering 的区别值得单独说清楚。Prompt Engineering 解决的是这一次对话里怎么说模型才懂Memory 工程解决的是不管哪一次对话模型都应该知道哪些事。前者是会话级的微观优化后者是项目级的宏观设计。打个比方Prompt 是跟新人交代眼前这个任务怎么干Memory 是给新人发一本《部门工作手册》。没有手册你每天要花大量时间反复交代有了手册一次培训全员受益。我见过不少团队Prompt 写得天花乱坠但换一个工具、换一个会话就彻底失效。原因就是他们把记忆寄托在了人肉复制粘贴上而不是结构化的文件系统里。Memory 工程的核心主张是记忆必须落在文件里必须能被工具自动读取。2.2 记忆的三层架构从应用范围看Memory 工程应该按三层来设计缺一层都不完整。会话记忆指的是当前对话里的临时状态比如这次我们先只改下单流程支付部分下周再说。这类记忆不需要持久化它存在于上下文窗口中会话结束就作废。项目记忆是面向单个代码仓库的长期规则包括技术栈、目录结构、代码规范、架构约束、已知陷阱。这是 Memory 工程的重心也是 AGENTS.md 要承接的部分。组织记忆则是跨越多个项目的团队共识例如所有服务必须接入统一日志平台接口文档必须优先更新。它通常沉淀在团队的规范文档或共享配置里再按需被导入到具体项目。三层之间的关系可以看成会话记忆是短期工作台项目记忆是项目专属说明书组织记忆是公司通用价值观。落到工程上就要分别为它们设计存储、更新和注入机制。2.3 声明式配置 vs 命令式注入谈及落地方式业界存在两条路线命令式注入和声明式配置。命令式注入的做法是写一个启动脚本在调用模型之前动态拼接一段背景说明拼进 prompt 再发给模型。它能用但问题很明显脚本一旦变多背景说明散落在各种 shell 脚本、Python 脚本里改一处要翻半天换工具后还得重写一遍而且你无法直观地看到最终模型拿到了什么调试极其痛苦。声明式配置则完全不同。你把规则写进一个约定的文件比如 AGENTS.md放在仓库固定位置然后让 AI 编程工具自动发现、读取、注入。你不关心拼接过程只关心文件内容。这就像环境变量和配置文件的区别环境变量每次启动都要手动 export配置文件放那就可以了所有程序自动读。AGENTS.md 之所以值得推广正是因为它把如何让 AI 知道你项目的规矩这件事变成了一件声明式、可审查、可版本管理的事。3. AGENTS.md 声明式配置核心概念与工作方式3.1 AGENTS.md 是什么AGENTS.md 是一个约定俗成的 Markdown 配置文件通常放在仓库根目录用自然语言描述这个项目的关键信息帮助 AI 编程助手在会话开始时快速理解项目背景和相关约定。它的核心思想是把人类团队的新人入职文档改造成AI 助手的项目说明书。里面可以写项目是干什么的、用什么技术栈、目录怎么组织、代码有什么规范、哪些事绝对不能做。AI 工具会自动读取这个文件把它纳入上下文让后续生成的内容时刻受到这些规则的约束。有人问它和 CLAUDE.md、.cursorrules 有什么区别。在同类的项目记忆文件里AGENTS.md 的最大特点是开放性——它不绑定特定工具而是作为一种通用约定被多个主流 AI 编程助手、CLI 工具和 IDE 插件识别。你可以理解为某几个工具各有自己的私有记忆格式而 AGENTS.md 是它们共同的公共语言。如果你的工作流涉及多个 AI 工具一份 AGENTS.md 就能通吃不用为每个工具维护一套说明书。3.2 工具是怎么消费它的在主流实现里AI 编程助手会在以下时机读取 AGENTS.md初始化项目会话、扫描仓库结构、或用户发出特定指令时。读取之后文件内容会被拼接到系统提示词或初始上下文中成为模型输出的前置约束。 关键点在于AGENTS.md 不是聊天记录它的地位比普通对话内容更高。模型会把它视为项目本身的规则来遵循。你可以在对话里临时调整但如果没有冲突它的约束力会覆盖模型默认的通用行为。这也带来一个重要推论AGENTS.md既是给 AI 看的也是给人看的。一个写得好的 AGENTS.md人类新成员读一遍也能快速上手项目AI 助手读一遍就能生成符合项目预期的代码。两者用同一份文件这本身就是效率极高的投资。3.3 目录与命名规范约定本身并不复杂核心规则如下仓库根目录的AGENTS.md是全局入口作用范围覆盖整个项目。子目录中的AGENTS.md只对该目录生效适合放局部规则。例如backend/AGENTS.md描述后端分层约束frontend/AGENTS.md描述组件规范。推荐使用AGENTS.extra.md或引用机制来拆分超长内容避免一个文件被撑爆。在实际项目中我建议至少做到根目录一份复杂模块按子目录补充。根目录写全局共识子目录写局部执行细节。这样既不会让单文件过长也能让 AI 在进入不同目录时自动切换上下文。这里需要特别提醒如果工具读取的是当前目录向上查找最近的 AGENTS.md那么子目录文件要能独立理解不要一上来就引用一个不存在的根变量。4. 手把手编写一份可落地的 AGENTS.md4.1 编写前的准备工作写 AGENTS.md 之前先在纸上回答三个问题这个项目最核心的技术栈和构建方式是什么代码里最常见的风格约定有哪些过去开发中反复踩过的坑是什么我建议你去翻一下项目的 README、贡献指南和最近的代码评审记录把大家经常重复提醒的内容捞出来。这些东西就是 AGENTS.md 的素材。不要试图一上来写百科全书先记录出现频率最高的 10 到 20 条后续再迭代。还有一个常被忽视的准备让团队一起 review。AGENTS.md 不是个人文件它是团队的协作契约。一个人写的文件往往带有强烈的个人偏好比如坚持某种命名风格、推崇某个不常用的库这些未必是团队共识。你可以在初稿里用建议原则上这类语气词但发布前一定要让核心成员过一遍否则它会变成一份不受执行的摆设。4.2 一份高复用模板下面是一份我在多个模拟项目中验证过的模板覆盖了 AI 编程助手最需要的几类信息# AGENTS.md ## 项目概览 - 项目目标提供商品下单与库存管理能力对外暴露标准 HTTP API。 - 技术栈Node.js 22 TypeScript 5.4 Fastify PostgreSQL 16。 - 目录结构src/api路由、src/service业务、src/repo数据访问。 ## 常用命令 - 安装依赖pnpm install - 本地启动pnpm dev - 运行测试pnpm test - 生成类型pnpm typecheck - 代码检查pnpm lint ## 代码规范 - 所有对外接口必须使用 zod 做参数校验禁止裸接 req.body。 - service 层不得直接调用 SQL统一通过 repo 层操作数据库。 - 错误码格式必须为 { code: ORDER_NOT_FOUND, message: 订单不存在 }。 - 类名用 PascalCase函数和变量用 camelCase常量用 UPPER_SNAKE_CASE。 ## 架构约束 - 本项目采用三层架构禁止跨层调用controller - service - repo。 - 所有事务边界必须落在 service 层使用全局事务管理器。 - 数据库表结构变更必须提供对应的 migration 文件。 ## 常见陷阱 - 更新订单状态时必须用乐观锁 version 字段不要用状态字段直接覆盖。 - 不要在请求处理链路中执行耗时超过 200ms 的同步操作。 - 非空断言!已经被团队禁用改写为显式类型守卫。 ## 工作流提示 - 实现一个新接口时先写路由再写 service最后写 repo并补上最少一个 happy path 测试。 - 涉及数据库迁移时不要修改已有 migration新增一个迁移脚本。 - 在提交前自动运行 pnpm typecheck 和 pnpm lint。这份模板的核心价值不是每一条内容而是它把规则分类了。概览、命令、规范、架构、陷阱、工作流每一类对应模型不同类型的行为。你可以直接替换成自己项目的内容结构保持不变。4.3 编写语言技巧同样的规则写法不同AI 的执行效果完全不同。我总结了三个关键技巧。第一用祈使句不用描述句。写请使用 zod 校验所有接口参数不要写项目通常使用 zod 进行参数校验。模型对明确的指令遵守度远高于含混的描述。你可以把它想象成给新员工做培训你说必须这么做比说一般会这样做有效得多。第二先写否定项再写肯定项。模型对禁止什么的敏感度高于应该什么。比如禁止在 service 层直接访问数据库比建议在 repo 层统一访问数据库更能防止模型跑偏。因为应该类指令给模型留下了自行诠释的空间而禁止类指令是硬边界。第三给出正反例。在关键规则下面接一个good / bad对比块。例如错误码格式必须为 { code: ORDER_NOT_FOUND, message: 订单不存在 }。 - bad: { status: 404, error: not found } - good: { code: ORDER_NOT_FOUND, message: 订单不存在 }模型非常擅长从例子中学习模式。一个正反例顶得上三句抽象描述。这也是我建议所有关键规范都带例子的原因。5. 踩坑实录AGENTS.md 落地中的常见问题与排查5.1 规则太多上下文爆炸很多团队第一次写 AGENTS.md容易把它写成项目百科全书恨不得把所有历史决策都塞进去。结果就是文件长达几千行AI 助手每次会话光读说明书就消耗大量上下文真正用于解决问题的时间变少了生成质量反而下降。这个问题我试过几种方案最有效的是分层与引用。根目录 AGENTS.md 只保留全局高频规则详细的技术细节放到子目录 AGENTS.md或者拆成文档片段再被主文件引用。很多 AI 编程工具支持在文件里写详细说明请参考 docs/architecture.md然后在AGENTS.md中只保留关键约定。这样既能控制注入上下文体积又不丢失信息。另外要养成定期修剪的习惯。每季度过一遍删掉那些已经变成团队肌肉记忆、模型也能通过代码风格推断出来的内容。AGENTS.md 是增量成长的但也要允许自己减量。5.2 与对话内指令冲突怎么办AGENTS.md 建立了默认规则但你在具体会话里还是需要临时打破它比如这次为了迁移演示暂时允许在 service 层直接写 SQL。这种冲突怎么处理我的结论是会话内指令优先于 AGENTS.md。模型在推理时系统级规则、文件上下文和当前用户指令会形成一个排序通常用户最近明确说出的指令具有最高优先级。所以你在对话里要求临时放宽规则模型一般会照做。但如果规则冲突太尖锐有些模型会直接拒绝执行然后提醒你当前文件里写明了禁止跨层调用。处理办法很简单遇到这类覆盖需求先在对话里明确声明忽略 AGENTS.md 第 3 条本次会话允许 xxx把覆盖动作显式化。同时记住这是临时状态不要在 AGENTS.md 里写入一次性决定——你今天因为某个演示宽限了规则明天就会有人利用这个宽限写出生产事故。5.3 多工具兼容与格式差异AGENTS.md 的开放性让它被很多工具支持但不同工具对它读取的时机、方式仍有差异。有些工具只在项目根目录找AGENTS.md有些工具支持子目录限定还有些工具会额外读取类似命名的文件。如果你同时在用多种 AI 编程助手会碰到这个工具读了、那个没读的混乱情况。我目前采用的方案是做一个入口文件 include 引用模式根目录AGENTS.md里写全局规则并在开头注明子模块规则见各自目录下的 AGENTS.md。同时在 CI 里加一个校验步骤检查所有关键目录是否都有 AGENTS.md 文件以及文件是否包含必要字段。这里的实战经验是不要靠软链或符号链接来共享同一个 AGENTS.md。跨平台协作时 Windows 和类 Unix 系统对符号链接的处理不一致容易在拉代码时产生难以排查的故障。宁可复制一份也要保证构建环境稳定。5.4 安全与权限AGENTS.md 会被模型读取而模型的回答理论上可能被展示给任意见到输出的人。所以不要在里面写任何敏感信息。数据库连接串、内网地址、临时密钥哪怕是为了方便调试也不该进文件。如果确有需要用环境变量名或占位符代替再在对话里显式注入真实值。还有一个容易被忽视的点AGENTS.md 是仓库的一部分任何有权查看仓库的人都能看到它。你写进去的任何潜规则本质上都是公开声明。团队如果想在文件里记录一些内部提醒也要切换到中性、合规的措辞不要用嘲讽或抱怨的语气。这既保护团队成员感受也避免后续新成员产生误解。6. 从一个人用到团队落地进阶扩展6.1 结合代码检索从静态记忆到动态记忆AGENTS.md 是 Memory 工程里偏静态的部分内容相对稳定适合承载项目规则。但真实项目的信息是动态膨胀的今天的代码和三个月前的代码可能差异巨大AGENTS.md 不可能也没必要承载全部实现细节。所以更完整的架构是AGENTS.md 代码检索。前者回答项目有哪些规矩后者回答某个功能现在是怎么实现的。很多 AI 编程工具已经内置了代码索引和检索能力会在生成代码时自动补充相关文件内容。你需要做的是把 AGENTS.md 里的关键备忘与检索功能结合起来——在 AGENTS.md 里指向关键模块的位置让助手知道应该重点看哪些文件而不是要求它把整个仓库的文件都读一遍。这样做的最大好处是降低上下文消耗。静态记忆管全局约束动态检索管局部事实两条路径互不干扰。项目越大这种组合的收益越明显。6.2 在 CI 里让 AGENTS.md 保持新鲜AGENTS.md 会腐烂只要你不维护它就会慢慢和项目现实脱节。这里说的腐烂指的是技术栈升级了文件里还写着旧框架的命令目录重构了文件里还描述着旧结构。腐烂的 AGENTS.md 比没有更糟因为它给了模型一个错误的事实基础。我的做法是把 AGENTS.md 也当成代码来治理。在 CI 中加入一个轻量检查验证文件存在、验证关键小节没有空置、验证命令是否和 package.json 中 script 保持一致。更进一步在每次合并涉及架构调整的 PR 时要求 PR 描述中说明是否影响了 AGENTS.md如果有影响则必须同步更新。做法听起来繁琐但实际操作后会发现它带来的维护成本远低于收益。6.3 让模型先读再写反馈死循环最后分享一个我在团队内部推动的细节当我们把 AGENTS.md 写到足够稳定之后不要只在被动场景里用它。可以让 AI 助手在生成任何代码之前先执行一个预检步骤——列出它计划遵循的 AGENTS.md 规则再开始动手。这个做法听起来多余但实测下来能显著提升规则遵循率。原理很简单当模型在输出开头显式复述它要遵守的约束时它的后续推理会更少偏离这些约束。你可以理解为它先把规则放在自己的工作台上而不是等到生成到一半才想起还有规则没看。实现上通常只需要在系统指令末尾加一句在开始完成任务之前先阅读项目根目录的 AGENTS.md并列出你将要遵循的关键规则。很多支持自定义指令的工具都能做到。如果做不到也可以写进 AGENTS.md 本身要求模型输出计划。这是我从多个项目里验证过、投入产出比最高的一项优化。我在实际使用中的体会是AGENTS.md 最容易被低估的价值不是它给 AI 省了多少 token而是它强制整个团队把我们到底是怎么干活的这个问题想清楚了。很多团队写不出来一份靠谱的 AGENTS.md不是工具不会用而是项目本身缺乏明确约定。所以如果你发现自己写这份文件很吃力别急着怪格式先回去审视一下项目文档和实践是否足够清晰。先把文件从 10 条写起在每次踩坑之后补一条坚持一个迭代周期你会发现它逐渐从一份配置文件变成了团队的协作宪法。最后再补一个小技巧给每一份 AGENTS.md 加上日期和版本号让 AI 和人都知道当前看到的是不是最新共识这个细节能帮你省下不少排查时间。