三周前我在重构某后台系统的权限校验逻辑时让 AI 帮忙改一段路由守卫。前四轮对话非常顺利模型准确定位了三处涉及权限的入口文件甚至主动补了一个被我漏掉的异常分支。到了第五轮我随口提了一句顺手处理缓存失效,它忽然开始大规模改动另外一个完全不相关的模块理由是这个模块看起来也需要更新。那一刻我意识到问题不在于模型笨而在于它从第一轮对话开始就在失忆状态下猜我的项目——没有任何一份文件告诉它代码结构长什么样、哪些是铁律、哪些文件可以动、哪些绝对不能碰。正是这次经历让我认真研究起了 AI 编程范式转换和 Memory 工程最终落到 AGENTS.md 声明式配置上。这个主题解决的是当下 AI 辅助编程最大的痛点模型本身没有项目记忆但真实项目恰恰需要长期、稳定、可共享的项目上下文。搞清楚这套东西你能让 AI 从每次重新认识的临时工变成拿着项目图纸干活的老员工。这篇文章我会从无状态模型的短板讲起拆解记忆分层设计、AGENTS.md 的写法与落地链路最后分享几组真实踩坑记录。内容主要面向正在用 AI 写业务代码、但觉得对话越来越笨重的中高级开发者也适合正在给团队搭建 AI 协作规范的技术负责人。1. 范式转换无状态问答为什么撑不住真实项目1.1 无状态模型的三大先天短板现在的编码模型本质上是一个无状态函数你输入一段文字它根据训练参数和当前上下文窗口里的内容输出一段预测结果。所谓无状态,是指它不保存任何跨会话的持久信息。你上一次告诉它这个项目的错误码统一放在某个文件里下一次对话它完全不记得。这个特性在简单问答场景下没问题放在真实项目里就是灾难。第一个短板是上下文窗口有物理边界。我常用的某款编码模型上下文窗口虽然已经很大但一个真实的中大型项目光源码就有几十万行配套的配置文件、接口文档、数据库设计文档更是浩如烟海。窗口再大也装不下全部模型只能在有限的窗口里挑着看。问题在于它挑的依据往往不准确——经常是根据你最近几句话里的关键词猜而不是根据项目真实的优先级去判断。第二个短板是每次会话都是失忆重启。今天你告诉模型某个历史决策为什么用户表里要冗余一个昵称字段明天新开会话它又会对同一条业务逻辑提出完全相反的修改建议。你要是没把决策沉淀到某个文件里就等于这个决策只存在于你脑子里对 AI 完全无效。第三个短板是团队没有一致性载体。两个人各自用 AI 写代码A 告诉 AI 组件全部用函数式写法B 告诉 AI 组件全部用类写法AI 分别照做最后合并代码时就会产生完全对立的风格冲突。无状态模型天然缺少一个团队共识的落点每个人和 AI 的约定都只活在自己的对话里出了这个对话就归零。1.2 范式转换的核心文件即记忆要解决上述问题唯一可行的思路是把记忆从模型内部搬到代码仓库里。模型无状态没关系我们可以用有状态的文件系统来补——每次对话开始前让 AI 先读项目根目录下专门写好的记忆文件把项目背景、技术约定、关键决策一次性装进上下文。这个范式转换的本质是问答式编程变成协作者编程。问答式编程里模型是被动的答题机器你问一句它答一句协作者编程里模型被设定成一个入职第一天先读文档的新成员它工作的第一件事不是写代码而是理解项目。具体到实践会有三个明显变化约定从口头变成文本。不再是我记得告诉过 AI 不要直接改数据库连接而是把这条规则写进记忆文件AI 每次必读。上下文从随机抓取变成结构化加载。AI 不再靠猜来决定先看哪个文件而是跟着记忆文件里的索引按图索骥。协作从单次会话变成跨会话连续。今天定下的接口约定写进文件之后下周新开的会话同样能读到。我见过不少团队的认知误区觉得无状态模型做不到记住项目所以等模型进化。方向恰恰相反模型越进化上下文窗口越大越需要人有意识地把记忆结构化——窗口大了不等于会自动知道你的项目里哪个目录最重要、哪个历史决策不能推翻。这是典型的工程问题而工程问题要用工程手段解决。2. Memory 工程让 AI 从现场发挥到拿着图纸干活2.1 记忆分层的设计逻辑Memory 工程这个说法听起来玄拆开看其实很像我们人类的工作方式。我自己干活时记忆明显分成三档正在进行的事放在手边项目约定贴在白板上历史经验锁在档案柜里。给 AI 设计记忆体系也应该这样分层不能全都塞在一起。第一层是工作上下文对应模型当前对话窗口里的临时信息。比如这次要改哪个函数、刚读进来的某个接口定义属于短时记忆。它轻量、易失会话结束就没了不需要刻意维护。第二层是项目记忆对应仓库根目录下的约定文件与索引文档。它解决这个项目的规矩是什么的问题是 AI 每次开工前必须加载的核心信息。AGENTS.md 就属于这一层我把这层称为白板——所有协作者抬头就能看见。第三层是长期资产对应代码历史决策记录、架构评审文档、沉淀的业务知识库。它不需要每次全量加载但在遇到涉及架构变动、历史原因的疑难问题时AI 可以根据索引去精读相关文档。很多人一上来就想搭向量数据库把所有文档变成 Embedding 塞进去我觉得这是过度设计。先问一个问题你这个项目里需要 AI每次都知道的信息到底有多少绝大多数项目其实不到几十条。这些信息用一份结构良好的 Markdown 文件就能装下向量库反而会增加检索不确定性和维护成本。我见过比较务实的团队是先用约定文件支撑日常开发只有当约定文件膨胀到装不下、或者检索命中率明显下降时才开始引入语义检索。2.2 记忆的物理载体与组织方式项目记忆落到文件系统里常见载体是仓库根目录下的 AGENTS.md再加上若干辅助文档。为什么主文件要放在根目录因为 AI 读取项目时扫描起点几乎都在根目录它天然会先看到根目录下的说明文件。你放得越深AI 越容易漏掉。我习惯的目录组织长这样project-root/ ├── AGENTS.md # 主记忆文件AI 每次必读 ├── docs/ │ ├── decision-log.md # 历史决策日志 │ ├── module-index.md # 模块索引与依赖关系 │ ├── routes.md # 核心路由与接口登记 │ └── architecture.md # 架构总览精读时才加载 └── src/AGENTS.md 管的是每次协作前必须知道的信息docs 下的文件管的是遇到特定问题时才需要精读的信息。两者是摘要与详情的关系——AGENTS.md 里可以写数据库迁移规则见 docs/migration-policy.md但不要把整篇迁移政策抄进去。2.3 记忆的维护节奏记忆工程里最容易翻车的不是怎么建而是怎么养。文件建好之后躺三个月代码改了三轮记忆文件里的目录结构早就对不上了。这时候 AI 读了反而比不读更糟——它会拿着过期信息一本正经地误导你。我的经验是定一个变更即更新的原则每次发生结构性变更新增模块、路由调整、依赖方向变化时顺手更新记忆文件每次会话结束发现 AI 因为缺少信息而走了弯路时把这部分信息补进 AGENTS.md。这两条行为习惯形成之后记忆文件就会随着项目演进自然生长而不是变成一个需要专门花时间去维护的负担。3. AGENTS.md 声明式配置实操从入门到生产可用3.1 声明式配置的核心要素AGENTS.md 之所以叫声明式是因为它里面写的是项目是什么、有哪些约束而不是一步一步怎么执行。这个区别很关键。命令式的写法是如果用户要求加接口你必须先打开 router.ts然后添加路由再去 controller 目录下新建文件;声明式的写法是接口注册统一在 router.ts 中维护控制器按模块放在 src/modules 下。AI 拿到声明式描述之后自己推理出执行步骤灵活性远高于死板的步骤清单。一份能落地的 AGENTS.md核心要素至少包含五块项目概述与角色设定。用两三句话说明项目是什么、当前处在什么阶段。我给某营销后台项目写的开头是营销活动配置后台支持活动创建、人群包管理、投放数据报表分析。当前处于功能迭代期优先保证接口兼容性与现有页面稳定性。AI 读完就知道自己面对的是一个存量项目不是绿地开发不能轻易大改接口。技术栈与目录结构。列出核心语言、框架、关键依赖以及目录的职责划分。重点写每个目录是干什么的而不是把所有目录名罗列一遍。比如src/modules/campaign 为活动模块包含活动 CRUD 与人群包关联逻辑禁止从其他模块直接 import 其内部非公开方法。编码规范与红线。这是声明式配置里最值钱的部分。写清楚团队在代码里达成的共识命名风格、状态管理方式、错误处理规范、禁止直接触达的底层模块。我在实际项目里体会最深的是红线一定要写得非常具体写请遵循良好代码风格是废话写新代码不得引入任何新的全局状态所有跨组件共享状态必须走某轻量状态库才有约束力。命令与服务信息。把启动、测试、构建、代码检查的常用命令写清楚顺便标出哪些命令是耗时较高的比如全量测试要跑三分钟让 AI 知道该不该默认执行。某次模型为了确认一行修改没有破坏功能主动跑了一次三分钟的全量回归其实我只想让它看单测——后来我在命令清单里加了快速验证单测请使用 npm run test:unit这类问题就消失了。记忆策略与联动规则。说明哪些场景下需要更新哪些记忆文件。例如新增或删除模块路由时同步更新 docs/routes.md涉及架构层面的变化时在 docs/decision-log.md 新增一条记录。这个要素经常被忽略但它决定了记忆工程能不能自动运转。3.2 一份可直接上手的 AGENTS.md 实例下面这份配置来自我目前在维护的一个项目具体代号我隐去了结构可以直接抄。注意看它的措辞每条都是声明而不是命令。# AGENTS.md ## 项目概述 某营销活动配置后台面向运营团队使用。当前处于功能迭代期存量功能稳定优先。 主要模块活动配置、人群包管理、投放渠道对接、报表查询。 ## 技术栈与目录约定 - 前端TypeScript 某组件框架全局状态使用某轻量状态库。 - 后端某 Node 运行时 某接口框架数据库使用某关系库。 - 前端页面入口统一在 src/pages 下注册业务逻辑抽离到 src/modules/module/services。 - src/modules/campaign 为活动模块对外暴露 router.ts 与 services 目录其余模块禁止直接引用其内部文件。 ## 编码规范 - 组件统一采用函数式写法禁止新增类组件。 - API 请求必须走 src/api/client 统一封装错误码释义集中在 src/api/errors.ts。 - 所有涉及金额、人群包规模的计算必须保留两位小数禁止直接使用浮点数比较。 - 禁止在业务代码中引入全局第三方库除已注册的公共依赖外。 ## 红线 - 严禁修改数据库连接逻辑与迁移脚本的历史记录。 - 严禁绕过权限校验直接新增后端接口。 - 严禁删除或重命名存量接口的出参字段确需变更时必须加新字段并在决策日志中记录原因。 ## 常用命令 - 本地开发npm run dev - 单元测试npm run test:unit - 全量回归npm run test:full 耗时较长默认不执行 - 代码检查npm run lint - 构建产物npm run build ## 记忆策略 - 新增或调整核心路由时更新 docs/routes.md。 - 模块间依赖方向发生变化时更新 docs/module-index.md。 - 任何涉及接口兼容性、数据库结构、架构方向的决策追加到 docs/decision-log.md。 - 会话中发现的AI 反复问过的常识问题,下一次直接从 AGENTS.md 里补充澄清。这份文件我控制在六十行以内因为主记忆文件不宜过长。六十行的信息量足够 AI 建立基本认知又不至于把它的上下文窗口全占满。你可以看到里面的每一条都是约束和事实没有第一步做什么、第二步做什么的流程化描述——这正是声明式和命令式最直观的区别。3.3 配置粒度的取舍与常见误区AGENTS.md 的写法非常考验分寸感。写太细几十上百条规则砸进去AI 抓不住重点上下文也浪费严重写太粗只有项目是一个后台系统这种信息AI 读了等于没读。我实践下来的经验是三个只写只写会反复使用的信息只写违反后会出事故的约束只写和 AI 协作直接相关的约定。至于代码缩进是两格还是四格接口返回结构是什么这些交给 linter 和类型系统去管不写进 AGENTS.md。另一个高发误区是把 AGENTS.md 当成需求文档来写。有人会把当前迭代的功能需求、待办列表全塞进去结果文件变成一周就过期的新鲜货。记住AGENTS.md 是稳定的项目上下文不是动态的项目计划。需求类的信息放在任务描述里发给 AI而不是沉淀进长期记忆文件。还有一个常见误区是忽视负面约束。我发现同样一条规则写成禁止直接修改数据库连接逻辑比写成修改数据库连接时请谨慎有效得多。AI 对禁令的执行力远强于对劝告的执行力尤其在存量项目里负面约束能有效防止它自作主张推进看起来合理的优化。4. Memory 工程的落地链路索引、缓存与更新4.1 建立项目地图让 AI 不迷路AGENTS.md 解决了项目规矩是什么但还没有解决项目里有哪些东西、在哪里。对于几百个文件的仓库AI 仍然需要一个地图来定位目标。我的做法是在 docs/module-index.md 里维护一个轻量模块索引内容形式如下modules: - name: campaign path: src/modules/campaign entry: router.ts depends_on: [auth, user] exposes_api: - POST /api/campaigns - GET /api/campaigns/:id tags: [活动配置, 运营侧]这个索引的价值在于AI 收到一个需求给活动列表加一个状态筛选项时可以先读 module-index直接锁定 campaign 模块的位置、入口文件和依赖关系而不是在整个仓库里逐个文件翻找。我把这个过程类比成一个新人入职时拿到公司楼层导览图——它不告诉他每间办公室具体怎么装修但告诉他要找的人在第几层第几间。建立索引不需要自动化脚本人工维护也可以。我在每次新开功能分支时会花两分钟更新这个 YAML成本很低但回报非常大。如果你有几千个文件的巨型仓库可以考虑用脚本扫描 import 关系来自动生成依赖部分但路径描述和模块职责说明仍然需要人工确认纯自动生成的内容往往缺少业务语义。4.2 缓存与增量更新策略Memory 工程落地时最容易出现的问题是每次会话加载太多。如果你的记忆体系把整个项目的地图、决策日志、架构说明全部塞进上下文AI 可能花了大量上下文去理解项目背景留给真正写代码的窗口反而变小了。解决方案是引入按需加载 内容寻址 增量更新三个策略。按需加载指在 AGENTS.md 里只放摘要详情放外部文档AI 只有在处理相关任务时才需要去精读。内容是地址不是内容本身。举个例子AGENTS.md 里写数据模型变更需遵循 docs/data-model-guide.md 的约定这句话只占几十个 tokenAI 实际动手改库表时才去读那篇文档。内容寻址是给每个记忆文档加一个指纹哈希只要文件内容没变对话之间可以复用之前的解析结果。这个思路和浏览器缓存的 ETag 很像。如果你在开发自己的 AI 工具链可以在加载记忆文件时计算哈希比对上次会话的缓存减少重复读盘和重复解析。增量更新则是指定什么变化触发什么更新的规则。我维护了一套简单的钩子接口变化时更新 routes.md依赖变化时更新 module-index.md重大决策时追加 decision-log.md。钩子事件发生时就地更新而不是定期集中大扫除成本低到几乎没有感知。4.3 工具选型的通用思路聊到 Memory 工程很多人的第一反应是上重型基础设施向量数据库、嵌入模型、RAG 框架。我的观点很明确这套东西适合文档数量巨大且查询目标不明确的场景不适合大多数业务代码仓库。判断标准很简单你希望 AI 召回的信息是否可以用目录 文件名 关键词准确表达如果能普通文件索引就够了如果不能比如我想找一个之前踩过的数据库死锁坑但不确定它记在哪个文档里才需要考虑语义检索。大多数项目里这类模糊回忆的需求占比不到百分之十为十个百分比引入一整条 RAG 链路性价比不划算。务实一点的工具链长这样用 AGENTS.md 做入口用若干 Markdown 文档做记忆库用目录结构做索引加上一条改代码时同步改记忆的团队约定。这套方案零依赖、零部署成本、任何团队成员都能参与维护。等到未来某一天记忆库膨胀到几百个文档再考虑自动化索引和语义检索也不迟。5. 实践中的坑与排查速查表5.1 上下文被无关信息冲散我遇到过最典型的问题AI 在一次会话里被测试文件、配置文件、构建脚本占满了上下文结果写业务代码时频频短路。排查时发现AGENTS.md 里写了统一了解项目整体结构,模型于是扫描了整个仓库的目录树——包括 node_modules 和 dist 目录。修复方法是在 AGENTS.md 里明确限定扫描范围## 扫描范围 - 只关注 src、docs、tests 三个目录。 - 忽略 node_modules、dist、coverage、.git 目录不要在分析时读取其中的内容。同时在任务描述里也写一句只处理 src/modules/campaign 下的文件不要读取其他模块。双向限定之后上下文占用率明显下降。5.2 记忆文件本身与代码脱节记忆文件最怕躺尸。某次我查看一个历史项目发现 AGENTS.md 里还在说路由统一走旧版中间件但代码早就迁移到新方案了。AI 读了错误信息给出了与现状完全不符的建议。根治办法是改代码的时候同步改记忆。我在代码评审清单里加了一条验收项本次变更是否触及 AGENTS.md 或 docs 下任何索引文件所描述的结构如果是,请同步更新。同时也建议不要一次性写太多记忆文档信息量越大过期速度越快。保持精简本身就是一种维护策略。5.3 多角色多服务的配置冲突一些仓库会同时维护多个服务或应用单份 AGENTS.md 容易顾此失彼。我在某个微服务仓库里尝试过把所有服务的约定写进一份文件结果 AI 在处理 A 服务任务时被 B 服务的约定干扰出现了张冠李戴的行为。更好的组织方式是按服务拆分子文件根目录的 AGENTS.md 只写仓库级别的公共约定和目录导航每个服务目录下放自己的AGENTS.md或类似命名。AI 在处理某个服务时先读根目录文件定位服务再进入服务目录读取细节。这种根文件导航、子文件专注的层级结构和代码组织的模块化思路是一致的。5.4 常见问题速查表症状常见原因解决方案AI 总是翻阅无关文件缺少扫描范围约束在 AGENTS.md 里增加明确的目录白名单/黑名单AI 反复问同一类问题信息在 AGENTS.md 里没写会话结束后把答案沉淀进 AGENTS.md记忆文件给出已过时的建议代码变了但记忆没更新建立变更即更新钩子评审清单加同步项AGENTS.md 读起来像需求文档把动态内容塞进了长期记忆只保留稳定项目上下文需求走任务描述多服务互相干扰单文件配置混用按服务拆分子 AGENTS.md 并在根文件做导航上下文被长文档挤爆详情未做按需加载主文件只放摘要详情文档按需精读模型完全忽略约定约定太泛或藏在文件深处用禁令式短句放在文件前三分之一5.5 团队协作上的几个维护建议最后说几条团队层面的经验。第一AGENTS.md 要有明确的负责人,否则没人更新就会过期第二每次较大的约定变更在代码评审里过一遍避免某个人拍脑袋定规则第三定期我习惯每个月读一遍 AGENTS.md删掉已经不再适用的旧约定保留真正有效的部分。维护 AGENTS.md 本质上是在维护团队的协作接口它值得和写代码同等程度的认真对待。我个人在实际操作中的体会是AGENTS.md 这套东西最大的价值不是让 AI 在单次会话里写出更好的代码而是让 AI 在跨会话、跨成员的长时间协作里保持一致。它把项目里那些只可意会不可言传的规矩变成了显式、可读、可检视的文本资产。刚开始写会觉得像是在替 AI 准备作业但随着记忆文件的成长你会发现 AI 制造的幺蛾子越来越少代码评审里关于风格和方向的争论也显著减少。如果你团队里正在被AI 每次都像新人折磨我建议从一份精简的 AGENTS.md 开始跑两周看看效果你大概率会回来继续完善它。