这两年我一直在跟 AI 辅助编程打交道从最开始用无状态模型做代码补全到后来深度依赖对话式编程再到如今把重心转向 Memory 工程和 AGENTS.md 声明式配置这条路走下来最大的感受是AI 编程的瓶颈从来不是模型能力而是上下文记忆的组织方式。无状态模型就像每次换一个新人来看你的代码仓库而 AGENTS.md 这类声明式配置本质上是把项目自身的“集体记忆”沉淀成一份可被反复读取、长期生效的工程文档。这篇文章就围绕这个主题聊聊范式转换背后的逻辑以及我这几个月落地的完整经验适合正在用 AI 写代码、做项目协作或者遇到“AI 每次都不记得上次结论”这类问题的开发者参考。1. 无状态模型的困境与范式转换的必然性1.1 无状态模型的头号痛点每轮对话都是新人早期我用 AI 写代码典型是这种方式开一个会话把需求描述一遍让模型生成一段函数复制进项目里跑通结束。下一次要改一个地方可能因为会话太长上下文丢失或者干脆开了个新会话整个模型对项目的了解归零需要重新讲一遍目录结构、技术栈、常见约定。这其实是个无状态模型的天生缺陷模型本身不记得你除非你把信息塞进本轮上下文窗口。我对这个问题有个很形象的类比。它就像一个大型仓库AI 是临时雇来的搬运工每次来都不知道货架怎么摆你得一遍遍告诉他工具在哪个抽屉、易碎品放在哪、哪些货优先出库。项目规模小还好仓库面积一大、货品一多新人的犯错率立刻飙升。无状态模型在真实工程里的表现也差不多——它不记得你上轮约定的接口命名规范不记得你特意排除过某些目录不记得你上次说“这块逻辑先不重构”。这个困局带来的隐性成本非常惊人。我实测过在一个中等规模的后端项目里每轮新会话至少需要 5 到 10 分钟“背景交代”而真正有效的编码时间被压缩更严重的是模型生成的风格每次都可能漂移同一个项目的代码看起来像三个不同的人写的。再往后你会发现一个更深的问题团队协作依赖人脑记忆可人脑记忆会随着时间衰减、人员流动而丢失AI 又完全靠上下文临时发挥整个项目的“软件智商”根本攒不下来。1.2 从“上下文拼接”到“结构化记忆”的范式转向要解决无状态的问题表面上是“把上下文塞进去”实际上是从思路层面的范式转向。第一种思路叫“上下文拼接”也就是每次对话前把一堆相关文件手动丢给模型。我早期就是这么干的结果窗口很快就爆了而且无关代码还会严重干扰输出质量。第二种思路是“检索增强”把项目内容做索引让模型按需拉取相关片段这个思路有效但它仍然是一次性的且缺少全局一致性。再往后衍伸出第三种思路——“结构化记忆”。“结构化记忆”不再追求一次性塞给模型尽可能多的信息而是建立一个长期稳定的、分层组织的项目记忆空间。这个空间里既有高层级的项目目标、架构决策、编码约定也有层级的接口说明、关键业务流程、坑点记录。模型每次工作时先读取这份“记忆”再结合当前任务去查阅细节。本质上这是把 AI 从一个“临时工”变成一个“有工牌的正式员工”。这个转向还有一个非常重要的驱动工程化的可复现性。无状态模式下好不好用全靠现场发挥有了结构化记忆项目团队可以把“如何正确使用 AI”这件事固化成文档别人接手项目时通过这份文档也能获得接近一致的 AI 协作体验。这也直接引出了 AGENTS.md 声明式配置的定位——它就是这个结构化记忆的落地载体之一。1.3 范式转换要解决的根本问题归纳一下这个范式转换要解的题有三类可累积、可共享、可控制。可累积是指每次项目运维中产生的经验能够沉淀下来而不是散落在模型权重和聊天记录里可共享是指团队任何成员、任何工具链都能以统一方式读取这些经验可控制是指项目维护者能够预见且限定 AI 行为的边界不让模型随意发挥越界。这三类问题哪个最容易被忽略我觉得是可控制。多数人一开始只想要“更懂我的 AI”却没意识到如果不设边界模型会很勤快地“过度设计”给你引入不该有的依赖、生成风格迥异的代码、甚至把某些特定的本地路径硬编码进去。声明式配置为什么好因为它是“白纸黑字”的你可以像写代码一样去审查它、修改它、版本管理它AI 的行为不是黑盒而是可解释、可约束、可回滚的工程产物。所以我的基本判断是AI 编程范式从无状态走向有状态关键技术点不是模型本身而是“记忆如何工程化”。记忆工程做好了模型智商的波动可以被项目本身的稳定性抹平这在多人协作时尤其明显。2. Memory 工程AI 编程的记忆体系要怎么搭2.1 记忆分层的核心思路项目级、模块级、会话级说 Memory 工程最忌讳的就是“一段文字存天下”。我的经验是一定要分层分层的逻辑与项目的架构层级对应主要有三层项目级、模块级、会话级。项目级记忆描述的是这个项目的“宪法”包括项目要解决什么业务问题、整体架构怎么分、核心技术栈选型以及原因、代码规范、必须遵守的命名规则和目录结构约束、部署和测试的通用命令。这一层变化频率极低相当于整个项目的锚点。模块级记忆则面向具体的业务模块或系统边界比如某个支付模块的对外接口长什么样、某个后台任务的触发机制、某段复杂算法为什么这么实现、某个模块里的典型坑点。这一层是项目运行过程中最常被查阅的。会话级记忆是临时性的比如“本次任务的目标”“我已经改了哪些文件”“下一步要做什么”。这一层不需要持久化到项目级文档里它会随着一个任务完成而被清空或合并进模块级记忆。我给这三层的定位分别是“常识、经验、工作台”。常识必须长期准确经验需要持续积累工作台则追求即时更新。如果你发现自己把会话级的临时结论写进了项目级文档那很可能是在制造记忆污染后面会讲怎么处理。2.2 什么该进记忆什么不该进记忆筛选原则无差别地把所有对话内容写进项目记忆是 Memory 工程最容易犯的错误。我一开始也踩过把某个临时排查过程完整记下来结果那份文档很快过时AI 反而被误导。后来我给自己定了一条筛选原则只记变更稳定的事实和决策背后的理由不记操作流水。实际操作中有四条判断标准这个信息会不会在三个月后仍然准确如果答案不确定先别写。这个信息是不是 AI 执行任务时的关键输入比如接口格式、错误码含义、启动命令、模块边界这类是。这个信息和“我们已经踩过的坑”是否相关如果是必须写否则模型会重复踩。这个信息一旦写错对项目有多大影响影响越大的越要谨慎确认后再写入。另外还有一个反向原则凡是代码里能直接读到的细节优先让 AI 去读代码而不是复制进记忆文档。记忆文档写的是代码里不直观体现的东西——为什么这么做、考虑过什么替代方案、有哪些隐性约束。例如“这里用了消息队列而不是同步调用是为了应对大促期间的流量尖峰”这种信息进记忆而具体调用了哪个函数不该进记忆去读代码就够了。2.3 记忆的更新、失效与冲突消解记忆如果只增不删最终会变成一堆互相矛盾的陈年旧账。我做过一次项目记忆梳理发现里面有 30% 的条目已经失效但模型还在傻傻地照着执行。所以 Memory 工程必须包含更新、失效和冲突消解机制。更新的契机一般有三种代码合并后接口变化、架构调整后模块边界变化、踩完新坑后补充经验。我现在基本把“更新记忆”作为一个工序塞进日常开发流程改完接口就顺手检查 AGENTS.md 里对应接口描述是否需要同步。失效处理的核心是“标记”不要贪图省事直接删。我会在文档里保留一段历史记录区域标明某条规则适用于哪个时间区间再写上淘汰它的原因好处是避免未来需求回溯时完全找不到上下文。冲突消解则遵循一个简单规则代码是唯一事实来源。如果记忆文档和代码行为出现矛盾先重构代码再改记忆不到万不得已不让模型用历史记忆对抗当前代码现状。如果没有这一层维护机制Memory 工程就会变成一座信息垃圾场AI 读到的每一项记忆都是概率性的“可能对”那还不如无状态。我习惯在项目里每两到三周做一次记忆快照审查看看哪些条目已经和当前代码脱节。3. AGENTS.md 声明式配置把记忆写成工程文档3.1 AGENTS.md 是什么和传统文档的区别AGENTS.md 并不是一个新的技术概念本质上它就是放在项目根目录或子目录下的一个 Markdown 文档但它不是给人读的而是给 AI 辅助编程工具读取的“项目使用说明书”。我把它理解成一份声明式的“AI 协作契约”。传统 README 是面向人类开发者的讲的是“这个项目怎么跑、依赖什么、模块如何组织”而 AGENTS.md 是面向 AI 的讲的是“你进入这个项目后应该遵循什么规则、注意什么边界、优先参考哪些文件”。队形上两者有重叠但定位差别非常大。README 可以写成抒情散文AGENTS.md 不行。它的信息必须高度结构化、可检索且指令语义明确。为什么叫“声明式”因为它描述的是“应该是什么”的状态而不是“如何一步步去做”。就像声明式编程一样你不需要告诉模型先读 A 再读 B 再执行 C你只需要告诉它仓库约定有哪些约束有哪些优先级如何。模型自己会决定具体路径。这个转变对于团队协作的意义很实在。以前团队的 AI 使用经验分布在各成员脑子里A 知道要让模型先读某个配置B 知道有个坑得在提示词里避开结果换人之后这些经验就断了。AGENTS.md 是把这些经验统一落在仓库里任何人打开项目AI 能立刻继承这些集体记忆。3.2 声明式配置的三层结构身份、行为、约束我落地过不少 AGENTS.md 之后总结了一套比较顺手的结构规范大致分三层身份层、行为层、约束层。身份层回答“这个项目是什么”。包含一句话项目定位、技术栈清单、关键目录路径及其用途说明、核心架构决策。模型读完这一层要能够在大脑中构建出一个项目画像。比如你这样写“本项目是面向某行业的库存管理后台后端用 Python 的 FastAPI前端是 React 和 Ant Design数据库为 PostgreSQLORM 使用 SQLAlchemy。目录结构/app/api 放接口、/app/services 放业务逻辑、/app/models 放数据模型。”这一段信息直接影响后续所有决策的判断基准。行为层回答“一般情况下你该怎么工作”。包括启动测试与构建的命令、编码风格的偏好别用尾逗号、函数命名用动词开头、推荐的实现路径先读相关 model 再改 service 最后暴露 API、需要优先遵循的现有模式比如项目里已有批量操作统一走任务队列不要新起线程。行为层的核心是让 AI 生成的代码风格与现有代码库尽可能一致减少人工修复成本。约束层回答“你绝对不能碰什么”。比如不要修改某些自动生成目录、不要引入新的外部依赖未经确认、不要在 service 层直接操作 SQL、小心数据库迁移脚本的兼容性、不要在业务代码里写死绝对路径。约束层是 AGENTS.md 真正体现“可控制”价值的区域因为无状态模型的常见问题就是越权发挥有了明确的负向清单模型的输出会更保守也更安全。这三层结构不要求每次都写成三个显式标题你完全可以按项目习惯混排但内在逻辑是先让它知道你是什么再告诉它怎么做最后划清边界。违反顺序的经验是一上来就写一堆不要这样不要那样模型对项目本身的理解不够约束容易生效但输出质量反而上不去。3.3 一个可直接落地的 AGENTS.md 示例下面给一个我常用模板的简化版你可以按实际项目调整。⚠️ 注意这只是骨架不要直接复制到大型项目里当万能配置。# AGENTS.md ## 项目概览 本项目是一个面向中小企业的库存管理后台提供商品、入库单、出库单、库存快照等核心能力。 技术栈Python 3.11 / FastAPI / SQLAlchemy / PostgreSQL / React 18 / Ant Design。 架构说明后端为 API 服务前端为单页应用。前端通过 REST 接口访问后端不使用后端渲染。 ## 关键目录 - /backend/app/api 路由与请求参数校验层 - /backend/app/services 业务逻辑层核心计算在此完成 - /backend/app/models SQLAlchemy 模型定义 - /backend/app/repositories数据访问层所有数据库查询都走这里 ## 常用命令 - 后端测试cd backend pytest -x -q - 启动开发服务cd backend uvicorn app.main:app --reload - 数据库迁移cd backend alembic upgrade head ## 编码约定 - 函数命名统一使用动词开头如 create_stock_snapshot。 - Service 层禁止直接操作数据库必须通过 Repositories 层访问。 - API 返回统一封装为 {code, data, message} 结构。 - 新功能默认走消息队列异步处理不要在请求线程内做耗时超过 1 秒的计算。 ## 注意事项与边界 - 不要修改 /backend/app/generated 目录下的任何文件该目录由代码生成器维护。 - 不要新增外部依赖如果确实需要请先在讨论中说明理由。 - 数据库表结构与迁移脚本必须保持兼容禁止直接修改已发布的历史迁移文件。 - 若遇到库存数量计算逻辑先查阅 /docs/stock_calculation.md不要凭直觉实现。 ## 当前迭代上下文 - 正在做出库单支持批量审核并自动扣减库存。 - 已完成但不合入旧的同步扣库存逻辑保留在 /backend/app/services/legacy_stock.py 仅供兼容。这个示例看着简单实际效果却立竿见影。我拿这个配置跑一个具体任务模型生成的接口和原有代码风格非常接近而且没有尝试去动 generated 目录也没有自己发明一套错误处理格式。相比无状态模式人工 review 的负担明显下降。需要强调的是AGENTS.md 不是提示词的一部分它是项目的一部分所以你可以像维护代码一样维护它让它跟随项目一起演进。4. 从配置到工程化落地实操步骤与避坑指南4.1 落地 AGENTS.md 的五个步骤一块配置从草稿到真正产生工程价值我建议按这五步走每一步都有实际意义。第一步做现状审计。花一两个小时把团队里问 AI 的问法、踩过的坑、已有的技术决策都列一遍。这一步最直接的目标是找到“项目里最容易被 AI 搞错的高频场景”比如某个接口格式反复写错、某个目录总是被误改、某条命令没人记得住。你的 AGENTS.md 第一版就围绕这些高频痛点展开。第二步起草第一版骨架。按身份、行为、约束三层结构写初稿但先不用追求完美覆盖只要把项目概览、关键目录、常用命令、核心约束写清楚就已经能显著改善输出质量。我当时第一版只有 40 行就足够让模型行为发生质变。第三步找几个真实任务做验证。把它们给 AI 执行观察它是否遵守了配置哪些地方配置说了它依然忽略哪些地方配置没提到但它做错了。这一步就是“调试 AGENTS.md”你得像调试代码一样迭代它。第四步放进版本管理。AGENTS.md 必须提交进仓库并且像代码一样接受 review。团队里任何成员发现 AI 行为异常都应该先想到“是不是 AGENTS.md 缺了一条”。原则上AGENTS.md 的变更需要和对应代码变更一起出现这样历史记录里才能看到清晰的因果关系。第五步纳入评审与复盘节奏。我建议在代码评审模板里加一项“有没有需要更新的 AGENTS.md”并在每个迭代结束后快速检查一遍配置是否有过时的描述。很多团队的 AGENTS.md 死于“写了就再也不管”结果三个月后完全脱节。4.2 实测中常见的 5 个坑与排查技巧我在多个项目里试过 AGENTS.md 的落地公最容易翻车的场景比较固定。有五个坑非常典型我把现象、原因和排查思路整理成了一张速查表。坑点现象根因排查与修复配置过长AI 开始忽略后文或只遵循前半部分约束上下文窗口被无效信息挤占关键约束被稀释把每节压到 5 行以内文字尽量精简、用列表不写长段落约束互相冲突模型输出自相矛盾比如既要求用异步又要求在请求线程里同步做计算行为层与约束层之间没有一致性校验写完后通读一遍重点检查“建议”和“禁止”是否打架让团队同事交叉 review代码与配置脱节文档写的是旧目录代码早改了位置更新配置没被纳入开发流程把配置更新作为代码评审模板的一项强制检查配置里写了过多琐碎细节模型把注意力放在无关细节上关键约束反而失效博主把操作流水写进了配置执行记忆筛选原则凡是代码能读出来的信息一律不写多人协作时配置发散每个开发者都往里加自己的偏好目录越来越厚缺少一个明确的配置负责人指定 AGENTS.md 的 owner任何变更都走 PR 并由 owner 审核排查时还有个技巧主动给 AI 出一个“对抗测试”任务比如故意提供一份和它配置里描述不一致的代码路径看它有没有遵循配置去质疑而不是盲从。这能很灵敏地检验配置是否真的进入了模型的决策流程而不只是摆设。4.3 团队协作中的 Memory 工程评审、版本与角色Memory 工程在团队里能不能持续运转很大程度取决于有没有把它当作正经工程来管理。我观察到一个规律单人项目里 AGENTS.md 很容易维护但一旦进了多人协作制度性保障就成了关键。第一是版本管理。除了 AGENTS.md 本身进仓库我还习惯把模块级记忆放在模块目录下的 MEMORY.md 文件里或者统一放在 /docs/ai/ 目录下这样不会把根目录搞成垃圾场。配置变更和代码变更绑定提交回滚时也能对应。第二是角色分工。建议指定一个“AI 协作配置负责人”这个人负责审核所有 AGENTS.md 和记忆文档的变更防止配置发散。这个角色不一定要有多高职位但必须具备对项目整体架构的把握能力。如果没有负责人过两个月配置就会变得一团糟。第三是把它纳入团队知识库的双向同步。AGENTS.md 不是孤岛它应当和架构文档、技术决策记录保持同源。架构调整时技术决策记录里写清楚了原因AGENTS.md 里只要引用它就好不要复制一整段论证文字否则两处不同步的概率就会成倍增加。我在实际维护中还发现一个很好的实践把每次踩过的坑做一次“错误示范对比”。也就是在验证 AGENTS.md 的过程中保留一次 AI 在无状态模式下生成的错误代码和一次遵循配置后生成的正确代码作为示例放在文档附录里。新成员一看就懂配置到底在解决什么问题比长篇大论洗脑有效得多。最后说点实在的踩过几次坑之后我对 AGENTS.md 和 Memory 工程的态度越来越务实。它确实不是一个能解决所有 AI 编程问题的银弹但它是目前投入产出比最高的做法。每写一条配置都是在减少未来某次对话中模型的不确定性每清理一次记忆文档都是在防止项目本身就“失忆”。如果你准备上手我的个人建议是从最小配置开始只写项目概览、关键目录、常用命令、最不能碰的三条红线然后拿真实任务去跑。等发现模型在哪类问题上反复犯错再把解决方案沉淀成新条目。这个循环跑两到三周你会明显感受到 AI 从“每次重新认识你的项目”变成“越用越顺手的老搭档”。最后再分享一个小技巧给 AGENTS.md 里每条规则都留一行“为什么”哪怕只是半句话。因为模型理解规则背后的意图比死记规则更能在边界场景下做出正确判断这也是 Memory 工程里最容易被低估的一环。 
长河君 · 2026/10/22 5:36:43 · 阅读 1.2k 从无状态模型到AGENTS.md：AI编程的记忆工程化实战
这两年我一直在跟 AI 辅助编程打交道从最开始用无状态模型做代码补全到后来深度依赖对话式编程再到如今把重心转向 Memory 工程和 AGENTS.md 声明式配置这条路走下来最大的感受是AI 编程的瓶颈从来不是模型能力而是上下文记忆的组织方式。无状态模型就像每次换一个新人来看你的代码仓库而 AGENTS.md 这类声明式配置本质上是把项目自身的“集体记忆”沉淀成一份可被反复读取、长期生效的工程文档。这篇文章就围绕这个主题聊聊范式转换背后的逻辑以及我这几个月落地的完整经验适合正在用 AI 写代码、做项目协作或者遇到“AI 每次都不记得上次结论”这类问题的开发者参考。1. 无状态模型的困境与范式转换的必然性1.1 无状态模型的头号痛点每轮对话都是新人早期我用 AI 写代码典型是这种方式开一个会话把需求描述一遍让模型生成一段函数复制进项目里跑通结束。下一次要改一个地方可能因为会话太长上下文丢失或者干脆开了个新会话整个模型对项目的了解归零需要重新讲一遍目录结构、技术栈、常见约定。这其实是个无状态模型的天生缺陷模型本身不记得你除非你把信息塞进本轮上下文窗口。我对这个问题有个很形象的类比。它就像一个大型仓库AI 是临时雇来的搬运工每次来都不知道货架怎么摆你得一遍遍告诉他工具在哪个抽屉、易碎品放在哪、哪些货优先出库。项目规模小还好仓库面积一大、货品一多新人的犯错率立刻飙升。无状态模型在真实工程里的表现也差不多——它不记得你上轮约定的接口命名规范不记得你特意排除过某些目录不记得你上次说“这块逻辑先不重构”。这个困局带来的隐性成本非常惊人。我实测过在一个中等规模的后端项目里每轮新会话至少需要 5 到 10 分钟“背景交代”而真正有效的编码时间被压缩更严重的是模型生成的风格每次都可能漂移同一个项目的代码看起来像三个不同的人写的。再往后你会发现一个更深的问题团队协作依赖人脑记忆可人脑记忆会随着时间衰减、人员流动而丢失AI 又完全靠上下文临时发挥整个项目的“软件智商”根本攒不下来。1.2 从“上下文拼接”到“结构化记忆”的范式转向要解决无状态的问题表面上是“把上下文塞进去”实际上是从思路层面的范式转向。第一种思路叫“上下文拼接”也就是每次对话前把一堆相关文件手动丢给模型。我早期就是这么干的结果窗口很快就爆了而且无关代码还会严重干扰输出质量。第二种思路是“检索增强”把项目内容做索引让模型按需拉取相关片段这个思路有效但它仍然是一次性的且缺少全局一致性。再往后衍伸出第三种思路——“结构化记忆”。“结构化记忆”不再追求一次性塞给模型尽可能多的信息而是建立一个长期稳定的、分层组织的项目记忆空间。这个空间里既有高层级的项目目标、架构决策、编码约定也有层级的接口说明、关键业务流程、坑点记录。模型每次工作时先读取这份“记忆”再结合当前任务去查阅细节。本质上这是把 AI 从一个“临时工”变成一个“有工牌的正式员工”。这个转向还有一个非常重要的驱动工程化的可复现性。无状态模式下好不好用全靠现场发挥有了结构化记忆项目团队可以把“如何正确使用 AI”这件事固化成文档别人接手项目时通过这份文档也能获得接近一致的 AI 协作体验。这也直接引出了 AGENTS.md 声明式配置的定位——它就是这个结构化记忆的落地载体之一。1.3 范式转换要解决的根本问题归纳一下这个范式转换要解的题有三类可累积、可共享、可控制。可累积是指每次项目运维中产生的经验能够沉淀下来而不是散落在模型权重和聊天记录里可共享是指团队任何成员、任何工具链都能以统一方式读取这些经验可控制是指项目维护者能够预见且限定 AI 行为的边界不让模型随意发挥越界。这三类问题哪个最容易被忽略我觉得是可控制。多数人一开始只想要“更懂我的 AI”却没意识到如果不设边界模型会很勤快地“过度设计”给你引入不该有的依赖、生成风格迥异的代码、甚至把某些特定的本地路径硬编码进去。声明式配置为什么好因为它是“白纸黑字”的你可以像写代码一样去审查它、修改它、版本管理它AI 的行为不是黑盒而是可解释、可约束、可回滚的工程产物。所以我的基本判断是AI 编程范式从无状态走向有状态关键技术点不是模型本身而是“记忆如何工程化”。记忆工程做好了模型智商的波动可以被项目本身的稳定性抹平这在多人协作时尤其明显。2. Memory 工程AI 编程的记忆体系要怎么搭2.1 记忆分层的核心思路项目级、模块级、会话级说 Memory 工程最忌讳的就是“一段文字存天下”。我的经验是一定要分层分层的逻辑与项目的架构层级对应主要有三层项目级、模块级、会话级。项目级记忆描述的是这个项目的“宪法”包括项目要解决什么业务问题、整体架构怎么分、核心技术栈选型以及原因、代码规范、必须遵守的命名规则和目录结构约束、部署和测试的通用命令。这一层变化频率极低相当于整个项目的锚点。模块级记忆则面向具体的业务模块或系统边界比如某个支付模块的对外接口长什么样、某个后台任务的触发机制、某段复杂算法为什么这么实现、某个模块里的典型坑点。这一层是项目运行过程中最常被查阅的。会话级记忆是临时性的比如“本次任务的目标”“我已经改了哪些文件”“下一步要做什么”。这一层不需要持久化到项目级文档里它会随着一个任务完成而被清空或合并进模块级记忆。我给这三层的定位分别是“常识、经验、工作台”。常识必须长期准确经验需要持续积累工作台则追求即时更新。如果你发现自己把会话级的临时结论写进了项目级文档那很可能是在制造记忆污染后面会讲怎么处理。2.2 什么该进记忆什么不该进记忆筛选原则无差别地把所有对话内容写进项目记忆是 Memory 工程最容易犯的错误。我一开始也踩过把某个临时排查过程完整记下来结果那份文档很快过时AI 反而被误导。后来我给自己定了一条筛选原则只记变更稳定的事实和决策背后的理由不记操作流水。实际操作中有四条判断标准这个信息会不会在三个月后仍然准确如果答案不确定先别写。这个信息是不是 AI 执行任务时的关键输入比如接口格式、错误码含义、启动命令、模块边界这类是。这个信息和“我们已经踩过的坑”是否相关如果是必须写否则模型会重复踩。这个信息一旦写错对项目有多大影响影响越大的越要谨慎确认后再写入。另外还有一个反向原则凡是代码里能直接读到的细节优先让 AI 去读代码而不是复制进记忆文档。记忆文档写的是代码里不直观体现的东西——为什么这么做、考虑过什么替代方案、有哪些隐性约束。例如“这里用了消息队列而不是同步调用是为了应对大促期间的流量尖峰”这种信息进记忆而具体调用了哪个函数不该进记忆去读代码就够了。2.3 记忆的更新、失效与冲突消解记忆如果只增不删最终会变成一堆互相矛盾的陈年旧账。我做过一次项目记忆梳理发现里面有 30% 的条目已经失效但模型还在傻傻地照着执行。所以 Memory 工程必须包含更新、失效和冲突消解机制。更新的契机一般有三种代码合并后接口变化、架构调整后模块边界变化、踩完新坑后补充经验。我现在基本把“更新记忆”作为一个工序塞进日常开发流程改完接口就顺手检查 AGENTS.md 里对应接口描述是否需要同步。失效处理的核心是“标记”不要贪图省事直接删。我会在文档里保留一段历史记录区域标明某条规则适用于哪个时间区间再写上淘汰它的原因好处是避免未来需求回溯时完全找不到上下文。冲突消解则遵循一个简单规则代码是唯一事实来源。如果记忆文档和代码行为出现矛盾先重构代码再改记忆不到万不得已不让模型用历史记忆对抗当前代码现状。如果没有这一层维护机制Memory 工程就会变成一座信息垃圾场AI 读到的每一项记忆都是概率性的“可能对”那还不如无状态。我习惯在项目里每两到三周做一次记忆快照审查看看哪些条目已经和当前代码脱节。3. AGENTS.md 声明式配置把记忆写成工程文档3.1 AGENTS.md 是什么和传统文档的区别AGENTS.md 并不是一个新的技术概念本质上它就是放在项目根目录或子目录下的一个 Markdown 文档但它不是给人读的而是给 AI 辅助编程工具读取的“项目使用说明书”。我把它理解成一份声明式的“AI 协作契约”。传统 README 是面向人类开发者的讲的是“这个项目怎么跑、依赖什么、模块如何组织”而 AGENTS.md 是面向 AI 的讲的是“你进入这个项目后应该遵循什么规则、注意什么边界、优先参考哪些文件”。队形上两者有重叠但定位差别非常大。README 可以写成抒情散文AGENTS.md 不行。它的信息必须高度结构化、可检索且指令语义明确。为什么叫“声明式”因为它描述的是“应该是什么”的状态而不是“如何一步步去做”。就像声明式编程一样你不需要告诉模型先读 A 再读 B 再执行 C你只需要告诉它仓库约定有哪些约束有哪些优先级如何。模型自己会决定具体路径。这个转变对于团队协作的意义很实在。以前团队的 AI 使用经验分布在各成员脑子里A 知道要让模型先读某个配置B 知道有个坑得在提示词里避开结果换人之后这些经验就断了。AGENTS.md 是把这些经验统一落在仓库里任何人打开项目AI 能立刻继承这些集体记忆。3.2 声明式配置的三层结构身份、行为、约束我落地过不少 AGENTS.md 之后总结了一套比较顺手的结构规范大致分三层身份层、行为层、约束层。身份层回答“这个项目是什么”。包含一句话项目定位、技术栈清单、关键目录路径及其用途说明、核心架构决策。模型读完这一层要能够在大脑中构建出一个项目画像。比如你这样写“本项目是面向某行业的库存管理后台后端用 Python 的 FastAPI前端是 React 和 Ant Design数据库为 PostgreSQLORM 使用 SQLAlchemy。目录结构/app/api 放接口、/app/services 放业务逻辑、/app/models 放数据模型。”这一段信息直接影响后续所有决策的判断基准。行为层回答“一般情况下你该怎么工作”。包括启动测试与构建的命令、编码风格的偏好别用尾逗号、函数命名用动词开头、推荐的实现路径先读相关 model 再改 service 最后暴露 API、需要优先遵循的现有模式比如项目里已有批量操作统一走任务队列不要新起线程。行为层的核心是让 AI 生成的代码风格与现有代码库尽可能一致减少人工修复成本。约束层回答“你绝对不能碰什么”。比如不要修改某些自动生成目录、不要引入新的外部依赖未经确认、不要在 service 层直接操作 SQL、小心数据库迁移脚本的兼容性、不要在业务代码里写死绝对路径。约束层是 AGENTS.md 真正体现“可控制”价值的区域因为无状态模型的常见问题就是越权发挥有了明确的负向清单模型的输出会更保守也更安全。这三层结构不要求每次都写成三个显式标题你完全可以按项目习惯混排但内在逻辑是先让它知道你是什么再告诉它怎么做最后划清边界。违反顺序的经验是一上来就写一堆不要这样不要那样模型对项目本身的理解不够约束容易生效但输出质量反而上不去。3.3 一个可直接落地的 AGENTS.md 示例下面给一个我常用模板的简化版你可以按实际项目调整。⚠️ 注意这只是骨架不要直接复制到大型项目里当万能配置。# AGENTS.md ## 项目概览 本项目是一个面向中小企业的库存管理后台提供商品、入库单、出库单、库存快照等核心能力。 技术栈Python 3.11 / FastAPI / SQLAlchemy / PostgreSQL / React 18 / Ant Design。 架构说明后端为 API 服务前端为单页应用。前端通过 REST 接口访问后端不使用后端渲染。 ## 关键目录 - /backend/app/api 路由与请求参数校验层 - /backend/app/services 业务逻辑层核心计算在此完成 - /backend/app/models SQLAlchemy 模型定义 - /backend/app/repositories数据访问层所有数据库查询都走这里 ## 常用命令 - 后端测试cd backend pytest -x -q - 启动开发服务cd backend uvicorn app.main:app --reload - 数据库迁移cd backend alembic upgrade head ## 编码约定 - 函数命名统一使用动词开头如 create_stock_snapshot。 - Service 层禁止直接操作数据库必须通过 Repositories 层访问。 - API 返回统一封装为 {code, data, message} 结构。 - 新功能默认走消息队列异步处理不要在请求线程内做耗时超过 1 秒的计算。 ## 注意事项与边界 - 不要修改 /backend/app/generated 目录下的任何文件该目录由代码生成器维护。 - 不要新增外部依赖如果确实需要请先在讨论中说明理由。 - 数据库表结构与迁移脚本必须保持兼容禁止直接修改已发布的历史迁移文件。 - 若遇到库存数量计算逻辑先查阅 /docs/stock_calculation.md不要凭直觉实现。 ## 当前迭代上下文 - 正在做出库单支持批量审核并自动扣减库存。 - 已完成但不合入旧的同步扣库存逻辑保留在 /backend/app/services/legacy_stock.py 仅供兼容。这个示例看着简单实际效果却立竿见影。我拿这个配置跑一个具体任务模型生成的接口和原有代码风格非常接近而且没有尝试去动 generated 目录也没有自己发明一套错误处理格式。相比无状态模式人工 review 的负担明显下降。需要强调的是AGENTS.md 不是提示词的一部分它是项目的一部分所以你可以像维护代码一样维护它让它跟随项目一起演进。4. 从配置到工程化落地实操步骤与避坑指南4.1 落地 AGENTS.md 的五个步骤一块配置从草稿到真正产生工程价值我建议按这五步走每一步都有实际意义。第一步做现状审计。花一两个小时把团队里问 AI 的问法、踩过的坑、已有的技术决策都列一遍。这一步最直接的目标是找到“项目里最容易被 AI 搞错的高频场景”比如某个接口格式反复写错、某个目录总是被误改、某条命令没人记得住。你的 AGENTS.md 第一版就围绕这些高频痛点展开。第二步起草第一版骨架。按身份、行为、约束三层结构写初稿但先不用追求完美覆盖只要把项目概览、关键目录、常用命令、核心约束写清楚就已经能显著改善输出质量。我当时第一版只有 40 行就足够让模型行为发生质变。第三步找几个真实任务做验证。把它们给 AI 执行观察它是否遵守了配置哪些地方配置说了它依然忽略哪些地方配置没提到但它做错了。这一步就是“调试 AGENTS.md”你得像调试代码一样迭代它。第四步放进版本管理。AGENTS.md 必须提交进仓库并且像代码一样接受 review。团队里任何成员发现 AI 行为异常都应该先想到“是不是 AGENTS.md 缺了一条”。原则上AGENTS.md 的变更需要和对应代码变更一起出现这样历史记录里才能看到清晰的因果关系。第五步纳入评审与复盘节奏。我建议在代码评审模板里加一项“有没有需要更新的 AGENTS.md”并在每个迭代结束后快速检查一遍配置是否有过时的描述。很多团队的 AGENTS.md 死于“写了就再也不管”结果三个月后完全脱节。4.2 实测中常见的 5 个坑与排查技巧我在多个项目里试过 AGENTS.md 的落地公最容易翻车的场景比较固定。有五个坑非常典型我把现象、原因和排查思路整理成了一张速查表。坑点现象根因排查与修复配置过长AI 开始忽略后文或只遵循前半部分约束上下文窗口被无效信息挤占关键约束被稀释把每节压到 5 行以内文字尽量精简、用列表不写长段落约束互相冲突模型输出自相矛盾比如既要求用异步又要求在请求线程里同步做计算行为层与约束层之间没有一致性校验写完后通读一遍重点检查“建议”和“禁止”是否打架让团队同事交叉 review代码与配置脱节文档写的是旧目录代码早改了位置更新配置没被纳入开发流程把配置更新作为代码评审模板的一项强制检查配置里写了过多琐碎细节模型把注意力放在无关细节上关键约束反而失效博主把操作流水写进了配置执行记忆筛选原则凡是代码能读出来的信息一律不写多人协作时配置发散每个开发者都往里加自己的偏好目录越来越厚缺少一个明确的配置负责人指定 AGENTS.md 的 owner任何变更都走 PR 并由 owner 审核排查时还有个技巧主动给 AI 出一个“对抗测试”任务比如故意提供一份和它配置里描述不一致的代码路径看它有没有遵循配置去质疑而不是盲从。这能很灵敏地检验配置是否真的进入了模型的决策流程而不只是摆设。4.3 团队协作中的 Memory 工程评审、版本与角色Memory 工程在团队里能不能持续运转很大程度取决于有没有把它当作正经工程来管理。我观察到一个规律单人项目里 AGENTS.md 很容易维护但一旦进了多人协作制度性保障就成了关键。第一是版本管理。除了 AGENTS.md 本身进仓库我还习惯把模块级记忆放在模块目录下的 MEMORY.md 文件里或者统一放在 /docs/ai/ 目录下这样不会把根目录搞成垃圾场。配置变更和代码变更绑定提交回滚时也能对应。第二是角色分工。建议指定一个“AI 协作配置负责人”这个人负责审核所有 AGENTS.md 和记忆文档的变更防止配置发散。这个角色不一定要有多高职位但必须具备对项目整体架构的把握能力。如果没有负责人过两个月配置就会变得一团糟。第三是把它纳入团队知识库的双向同步。AGENTS.md 不是孤岛它应当和架构文档、技术决策记录保持同源。架构调整时技术决策记录里写清楚了原因AGENTS.md 里只要引用它就好不要复制一整段论证文字否则两处不同步的概率就会成倍增加。我在实际维护中还发现一个很好的实践把每次踩过的坑做一次“错误示范对比”。也就是在验证 AGENTS.md 的过程中保留一次 AI 在无状态模式下生成的错误代码和一次遵循配置后生成的正确代码作为示例放在文档附录里。新成员一看就懂配置到底在解决什么问题比长篇大论洗脑有效得多。最后说点实在的踩过几次坑之后我对 AGENTS.md 和 Memory 工程的态度越来越务实。它确实不是一个能解决所有 AI 编程问题的银弹但它是目前投入产出比最高的做法。每写一条配置都是在减少未来某次对话中模型的不确定性每清理一次记忆文档都是在防止项目本身就“失忆”。如果你准备上手我的个人建议是从最小配置开始只写项目概览、关键目录、常用命令、最不能碰的三条红线然后拿真实任务去跑。等发现模型在哪类问题上反复犯错再把解决方案沉淀成新条目。这个循环跑两到三周你会明显感受到 AI 从“每次重新认识你的项目”变成“越用越顺手的老搭档”。最后再分享一个小技巧给 AGENTS.md 里每条规则都留一行“为什么”哪怕只是半句话。因为模型理解规则背后的意图比死记规则更能在边界场景下做出正确判断这也是 Memory 工程里最容易被低估的一环。