AGENTS.md：声明式项目记忆，破解AI编程助手的“失忆症”

最近我在维护一个中等规模的数据处理项目时，发现一个特别有意思的转折：同样一个AI编程助手，半年前我用它干活，得先花十几分钟把项目背景、目录结构、技术栈、常用命令从头讲一遍；改了没几轮它就开始“失忆”，拿通用最佳实践套我们的特殊架构，改出来的代码风格跟现有模块完全拧巴。可现在，它在第一次会话里就能准确说出“这个项目的核心处理链路在哪个目录、测试命令是什么、新增模块该遵循什么依赖原则”，改代码时还会主动提醒我不要碰某个被标记为稳定的核心链路。差别在哪？就在我在仓库里放了一个叫 AGENTS.md 的声明式配置文件。

这件事往深了想，不只是一个文件的问题。它背后是AI编程范式正在发生的一次转换：从把大模型当成无状态的问答机器来用，转向通过 Memory 工程给它构造一个持续存在、结构化、可维护的“项目记忆”。这篇文章想把整条思路完整梳理一遍，包括无状态模型的本质局限、Memory 工程的分层设计、AGENTS.md 的写法与避坑经验，以及我实际踩过的几个真教训。适合正在深度使用AI编程助手、又觉得“每次都要重新解释项目”很痛苦的人，也适合想从零给团队建立一套AI协作规范的读者。

1. 无状态模型的“失忆症”：为什么AI编程越用越累

1.1 无状态模型的工作原理与隐藏短板

大语言模型本质上是无状态的。每次你向它发送请求，它接收到的都是一个完整且独立的输入——可能是一段对话历史、一堆粘贴进来的代码，以及你新写的诉求；模型自身不保存任何关于你项目、你之前提过的问题、半个月前你给它看的文件的状态。这个设计在服务端工程上非常务实：请求之间互不依赖，可以横向扩展，可以随时重试，也不容易出现状态污染。

但无状态是把双刃剑。放到编程场景里，它意味着AI每次都要“重新认识”你的项目。用一个生活化的类比：你每次去一家熟店，老板都把你当第一次来的顾客，你得重新讲一遍你不住几楼、不吃辣、要少糖。偶尔一次还行，天天如此就很崩溃。AI编程同样如此——单次问答它很聪明，可一旦任务变长、变复杂、涉及多个文件和沉淀多年的架构约定，无状态就成了天然短板。

1.2 编程任务是典型的“状态依赖”型工作

写代码这项工作，本质上建立在大量持续状态之上。一个普通仓储项目至少包含几类知识：

• 技术栈约束：指定语言版本、框架选型、依赖管理工具，甚至哪些库被明确禁止使用。
• 既有代码风格：命名习惯、目录组织方式、错误处理模式、日志格式，这些东西不是文档写出来的，而是散落在几十个文件里的群体默契。
• 跨文件架构知识：这个模块依赖哪个模块、数据从哪流入哪里、新增功能该加到哪一层。AI如果看不到这层关系，给出的建议往往“局部正确、全局错误”。
• 历史决策记录：某个组件当初为什么不用现成库而要自己写、某条路径为什么被废弃、哪个函数改过三次并积累了兼容性包袱。这些决策直接影响下一步改动的方向。

这些状态不是一次对话能交代清楚的。上下文窗口再大，你也很难把完整的架构认知塞进一次请求里；就算塞进去了，模型也会在大段信息中迷失重点。

1.3 无状态模式下开发者被迫做的苦差事

在没有记忆机制的年代，我用AI编程时最烦躁的就是三件事。

第一是每次开工都要重写“项目说明书”。项目怎么启动、测试用什么跑、核心模块在哪、有什么禁忌，这些信息一次两次我可以打，可每天都打、每个新会话都打，黏贴模板都嫌烦，关键是还会打漏。

第二是上下文沾在对话里带不过去。我明明在第一个会话里跟AI对齐了“数据仓库模块统一走 streaming 接口”，可开到第五个会话它又默认你用的是批量接口，改出来的代码跟前面的决定自相矛盾，我还得回头把旧代码翻出来证明给它看。

第三是AI给出“正确但不符合项目”的建议。它按通用惯例如期给出最优解，但这个项目和通用场景就是不一样——不能说它错，只能说它不了解我们的约束。可调试这种偏差，往往比我自己写代码还耗时。

2. Memory 工程：把“记忆”装进AI协作流程

2.1 模型无状态，应用层必须有状态

要解决“失忆”问题，不能指望模型自身突然长记忆，更务实的路线是做 Memory 工程：在模型之外构建一套状态系统，把项目认知、对话经历、团队约定持久化下来，在合适的时机注入给模型。核心思想一句话：模型不动，环境动。

这跟我们人类的做法很像。没人能靠脑子记住所有事，所以我们用笔记、文档、待办列表把这些认知外置。模型也一样——它每次启动都是“白纸”，但我们可以给它一份结构化的“工作笔记”，让它一进场就知道自己在什么项目里、要守什么规矩、有哪些工具可用。

2.2 四层记忆的取舍与配合

我在实际项目中把Memory分成四个层次，各有各的适用场景和成本。

四层不是替代关系，而是互补关系。会话内记忆负责临时讨论，检索增强负责“查资料”，跨会话记忆负责个人知识沉淀，而项目级声明式记忆负责提供一个稳定的认知基座。对绝大多数编程项目来说，投入产出比最高的，恰恰是第三个。

2.3 为什么项目级声明式记忆最值得投入

原因在于它的三个特性。

第一个是一次编写、长期复用。会话内的解释只能活一个对话，而项目级配置活在代码库里，每次新会话都被自动加载，不用重复劳动。

第二个是结构化程度高。它不像自由文本笔记那样容易丢失重点，而是有固定区块、明确条目的“项目事实清单”，AI读取时更容易定位到关键约束。

第三个是与代码同版本演进。代码仓库本身就承载了项目生命周期，AGENTS.md 跟代码放在一起，每一次架构调整都能同步更新记忆，不会出现“记忆还停留在半年前”的割裂。

我从那以后就把精力重点放在打磨这个唯一的文件上，而不是每开一个对话就重新“教育”AI一遍。事实证明，这个方向押对了。

3. AGENTS.md：声明式项目记忆的正确打开方式

3.1 AGENTS.md 到底是什么

简单来说，AGENTS.md 是放在仓库根目录（或子目录）下的一个 Markdown 文件，用人类可读、AI 可解析的声明式语言，描述一个项目最核心的事实、约束与操作方式。主流的AI编程工具会在每次会话开始时自动读取这类文件，把它作为理解项目的基础上下文。

它不是给人类看的 README，而是给 AI 看的“用户手册”。人类读者能脑补很多没写出来的背景，AI 不行——它需要明确的信息、目录位置、命令清单和边界条件，才能给出贴合项目的答案。有人会把 AI 想象成特别聪明的新成员，但我更倾向于把它想成一个能力很强但完全不了解项目的实习生：你得把规矩写明白，它才能干得漂亮。

3.2 声明式 vs 命令式：要描述事实，不要指挥流程

写 AGENTS.md 时最关键的思维转变，是从命令式指令切到声明式描述。

命令式写法是这样的：“你必须先读 src/utils 下所有文件，然后再改任何代码；改的时候要按 MVC 分层；写完要跑测试，测试不通过就要重写。”这类指令听上去很严谨，但问题在于它把AI当成一个机械执行者，而大模型本身是语言理解和模式匹配的引擎，给它死板的流程，反而容易机械照搬、不会变通。

声明式写法则是这样的：“本项目基于 Python 3.12 与 Django 5.0，服务层在 src/services，对外接口通过 REST 暴露，所有数据库访问必须经由 repository 封装层；测试统一用 pytest，运行命令为 make test。”它描述的是客观事实和约束边界，至于AI怎么利用这些信息、走哪条路径执行，留给它自己规划。

建议把 AGENTS.md 看作项目的接口契约：对外声明边界、输入输出、约束条件，不规定内部实现路径。这样文件才能长期稳定，也不会因为某个任务的步骤变化而频繁失效。

3.3 文件层级与优先级策略

项目变大之后，一个根目录文件可能不够用。我建议把 AGENTS.md 按层级拆成三层：

• 全局级：放在用户全局配置目录，描述个人或团队的通用编码偏好，比如不用的语言、强制用的格式化工具、提交风格。它对所有项目生效，沉淀的是“你是谁”的通用规则。
• 仓库级：放在代码库根目录，描述整个项目的定位、技术栈、结构、命令、核心约束。这是最重要的一层，覆盖90%的场景。
• 子目录级：放在特定模块或子项目目录下，描述该局部区域特有的规则，比如“这个目录下的代码不允许引入外部数据源访问”“这里的工具函数必须保持无副作用”。它补充或覆盖仓库级文件里的通用规则。

优先级上，更具体的层级覆盖更普遍层级。给AI配置文件的路径会按“就近原则”加载，子目录规则优先、其次仓库级、最后才是全局级。这个优先级层级可以避免规则冲突时AI无所适从。

3.4 一份可复用的结构模板

我给自己项目的 AGENTS.md 设计过一个比较顺手的模板，结构如下（内容为虚构示例）：

# 项目概览 一句话：本项目是一个面向零售场景的批量数据处理流水线，负责从外部数据源拉取订单数据、清洗转换后写入分析仓库。 技术栈：Python 3.12、Django 5.0、PostgreSQL 16、Redis 7；依赖管理使用 uv；任务调度采用内置 Celery。 # 目录结构与职责 - src/harvester：数据拉取入口，负责对外部接口的轮询与断点续传 - src/normalizer：清洗与字段映射，所有字段级规则集中在此 - src/loader：结果写入与分析层的 repository 封装 - tests：与 src 保持同构的测试目录，新增模块必须同步补测试 # 常用命令 - 启动开发服务：uv run python manage.py runserver - 运行全部测试：make test - Lint 检查：uv run ruff check . - 生成数据库迁移：uv run python manage.py makemigrations # 编码规范与硬约束 - 所有跨模块数据访问必须走 repository 层，禁止直接操作 ORM - 日志统一使用标准 logging，格式为 json，字段含 request_id - 数据清洗规则必须写在 normalizer 集中，不得散落在服务层 - 新增外部依赖需要先发评审确认，禁止直接进 requirements - 测试用例必须包含正常路径、异常路径、边界值三组 # 常见任务流程 - 新增数据源：先在 harness 下加 adapter，再注册到 sources registry，然后在 normalizer 里补字段映射，最后在 tests 目录补适配器测试 - 修改字段映射：只改动 normalizer 对应文件，并同步更新测试夹具 # 已知坑与反模式 - 不要直接改数据库线上数据，必须走迁移脚本 - 不要用全局变量缓存配置，设置会走 apollo 配置中心 - 历史遗留的 legacy_importer 模块已废弃，勿再在其上迭代

这份模板的核心逻辑是：先给身份和定位，再给地图，然后给命令，最后给约束和坑。AI按这个顺序读下来，会对项目形成一个相当完整的初始认知。

4. 实操：从零搭建一套有效的项目记忆配置

4.1 第一步：盘点项目，提炼硬约束

最开始动手写 AGENTS.md 时，别急着打开编辑器空想。我先花一个下午做“项目盘点”：把 README、架构设计文档、Makefile、package.json、CI/CD 配置、最近几次技术评审记录全翻一遍，边看边记，找出哪些信息是 AI 每次干活都必须要知道的。

这一步的产出物不是写好的文件，而是三张清单：一是高频命令清单（启动、测试、打包、lint，只要是人肉敲过的都要列上）；二是核心模块地图（项目里哪几个目录最重要、谁依赖谁、改动危险区在哪）；三是硬约束清单（团队明确立的规矩、踩过坑后才制定的红线，比如禁用的库、禁止直接操作的地方）。这三张清单，恰好在后面会变成 AGENTS.md 的三个核心区块。

4.2 第二步：按优先级撰写核心区块

撰写顺序建议和AI读取顺序一致：“项目概览与价值定位”先写，让AI秒懂这是干什么的；接着写“目录结构与数据流”，让AI建立空间认知；然后写“常用命令”，让AI能立刻执行验证；最后才是“编码规范、任务流程、已知坑”。

写作过程中要刻意追求清晰与简洁。我总结出几条实用的措辞原则：

• 用陈述句描述事实，不用祈使句要求行为。“所有跨模块数据访问必须走 repository 层”比“你要使用 repository 层”更稳定、更像不可违背的事实。
• 信息要短、要具体、要无歧义。“运行测试：make test”不要写成“跑一下测试”。路径要写清楚是相对根目录的相对路径，还是绝对路径，避免AI瞎猜。
• 重要约束尽量往前提。AI读长文本时注意力前重后轻，对合规类、安全类的硬约束要放在文件前半部分，不要藏到最后一个区块。
• 不要用“应该、最好”这类模糊词。AGENTS.md 只写确定性内容；“统一使用”“强制要求”“不允许”这类词才适合写进文件里。

一个容易犯的错是“什么都想往里写”。把项目里所有细枝末节都塞进文件，会稀释真正的重点。我给自己定的规则是：只有两种信息有资格进 AGENTS.md——AI不知道就一定会干错的事实，以及团队花了很大代价才形成、不希望被打破的约定。其余临时性内容，交给会话内对话去沟通就够了。

4.3 第三步：用“验收测试”驱动迭代

写完第一版后不要急着欢呼，更不要急着让全团队都抄过去。我自己的做法是给 AGENTS.md 做“验收测试”：新建一个空会话，不给任何额外提示，直接问几个固定问题，看AI回答得对不对。

• “这个项目怎么跑测试？Lint命令是什么？”
• “我现在要新增一个外部数据源，需要动哪些文件？”
• “访问数据库的方式有没有什么约束？”
• “这个项目的核心链路在哪里，哪些地方不能随便改？”

如果AI答得基本准确，说明文件有效；如果它还在猜、还在胡诌，就得回到文件里看是信息没写齐还是措辞有歧义。这套“配置的单元测试”流程，我每改一次 AGENTS.md 都会跑一遍，成本低、反馈快，能持续保障配置质量。写过四五轮之后，AI 对项目的理解会稳定在一个相当高的水平。

4.4 维护与版本管理建议

AGENTS.md 是会腐烂的。代码改了、目录重构了、命令更新了，文件却没跟上，AI 就会拿着过时的信息开工，干得越起劲错得越离谱。我的维护策略有三条。

一是把 AGENTS.md 纳入代码版本管理，和代码一起评审、一起合并。不把它当文档，而是当代码的一部分。所有涉及架构调整的 PR，都顺手检查一下 AGENTS.md 是否受影响。

二是每次迭代只做小改动。不要攒几个月再大改一次，那样中间AI一直在用坏信息干活。小步持续更新，比一次性重构成本低得多。

三是在项目模板里就内置一份基础版。如果团队有统一的脚手架，新项目生成时把通用的 AGENTS.md 模板一并生成，开发者只需要补项目特有信息，不需要从零开始写。这样团队内所有项目的AI认知基线都能拉齐。

5. 常见问题与避坑实录

5.1 常见问题速查表

把我在实践中踩过、以及在团队里看到别人踩过的坑整理成一张速查表，按症状查找比较方便。

5.2 最大的坑：写太长等于没写

我见过的第一个失败案例就是我自己。第一次构建 AGENTS.md 时，我洋洋洒洒写了四百多行，把数据库表的字段含义、接口参数、部署拓扑都塞进去了。结果AI的表现反而更差了——上下文被一堆低频信息占满，真正关键的“新增模块必须补测试”反而被淹没在角落里。

大模型的上下文注意力是有限的，文件越长，单位信息的权重就越低。我现在会把 AGENTS.md 控制在 100 到 150 行左右，核心约束控制在 80 行以内。写完后做一个“五秒测试”：随机找一个人（或者AI自己），让它快速扫描文件并在五秒内说出项目最重要的三条规则，如果做不到，就说明内容需要精简。

5.3 规则冲突与优先级混乱

一个典型冲突场景是：全局配置里写“所有项目统一使用 Black 格式化”，但某个仓库的 AGENTS.md 写“本项目使用 Ruff 格式化”，AI就会不知所措。这种情况往往出现在团队级模板和项目级文件之间。

解决思路是明确一个优先级原则：更具体的层级，拥有更高优先级。全局文件里可以加一条说明“本文件规则仅为通用默认，与仓库级 AGENTS.md 冲突时以仓库级为准”。同时在项目文件里，只保留与全局确实不同的特例，其他规则不要重复声明，以免形成“冗余覆盖”。如果项目内部两个模块有不同约束，把子目录级 AGENTS.md 放到对应目录下面，靠路径就近生效。

5.4 配置过时与内容失真

AGENTS.md 过时的危害比没有还大。没有它，AI至少知道自己不知道，会问、会查；有过时配置，AI会笃信错误信息，在错误的路径上快速行进，做出看起来很合理、实则完全不符合现状的方案。

处理办法有两层。第一层是流程防呆：把 AGENTS.md 更新纳入代码评审模板，每次架构调整顺手标注“本变更是否影响项目级配置”。第二层是识别“失真信号”：如果发现AI连续多次引用同一个已经废弃的目录或命令，大概率不是模型不行，而是配置文件没跟上；别急着在会话里纠正AI，先回去把文件改对。改一次，等于一劳永逸地修好所有后续会话的通病。

5.5 与既有工作流的衔接技巧

AGENTS.md 不需要跟现有文档体系抢地盘。它跟 README 的分工是：README 给人看，AGENTS.md 给 AI 看，两者内容可以重叠，但阅读对象不同。我在维护时会保持两者同步，README 更新了说明性内容，AGENTS.md 里对应的命令或描述也顺手改掉。

更进一步，还能把它跟项目脚手架、CI 校验结合起来。比如在 CI 里加一个轻量检查，确保 AGENTS.md 中的命令实际可执行；或者脚手架生成时自动校验 AGENTS.md 里的目录结构是否真实存在。这类自动化的价值在于，让配置文件不只是一个“文本约定”，而是一个和代码库真实状态保持一致的活文档。

6. 范式切换后的一点个人体会

从无状态模型一路走到 AGENTS.md 声明式配置，我最大的感受是：问题从来不在“AI记不记得住”，而在“我有没有把值得记的东西交给它”。无状态不是缺陷，它是大模型的基本属性；真正需要建设的，是我们和AI协作之间的状态层。Memory 工程的所有努力，本质上都在回答同一个问题——如何在模型每次“失忆”之后，让它迅速恢复对项目的完整认知。

我自己踩过几次坑之后，现在的习惯是：每次遇到AI反复理解偏差，先不急着在对话里解释，而是问自己“这个信息是不是应该写进 AGENTS.md”。如果是，改完配置再开新会话验证；如果不是，再回到对话里沟通。这样迭代几轮之后，项目里需要口头重复的东西越来越少，AI 干活的质量也更稳定。

如果你刚准备入坑，我的建议非常朴素：别想着一步到位写出一份完美文件，先立一个只有二十行的最小版本，写明项目技术栈、核心目录、常用命令、三条硬约束，用一周试试。一周后你会明显发现AI“像样”了许多，这时候再根据真踩的坑逐步往文件里补内容。从最小可用开始，让配置文件跟着实际协作一起长，远比一开始就追求面面俱到更靠谱。