1. 先想清楚一个问题：AI 编程助手到底缺的是什么
这两年我身边越来越多的人开始用生成式 AI 助手写代码，但大家很快发现一个共性现象：同一个项目，昨天刚讨论清楚的架构决策，今天开一个新会话，助手又像第一次见面一样问东问西。你在上下文里喂进去的约束、偏好、边界，只要对话一关就全部归零。于是每轮都要重新解释项目背景，重新强调技术栈，重新叮嘱“这块别动、那边别碰”，活脱脱一个金鱼记忆力的人在帮你干活。
这个问题的本质，就是 AI 编程领域一直以来的“无状态模型”困境。模型本身很强，能写代码、能重构、能解释报错，但它在每次对话开始时是一张白纸，所有关于你项目的知识都只能靠本轮对话临时注入。对话窗口就是它的全部记忆，窗口之外一概不知。而一个真实的软件项目是典型的有状态系统：一年前的技术决策、半年前引入的第三方库、上个月定下的代码风格，都沉淀在仓库里、注释里、人的脑子里。这两者之间天然错位，而且越大的项目错位越严重。
过去大家的解法很朴素：把项目说明复制粘贴给 AI，每次开头先贴一大段背景，或者写一个 personal prompt 文件，新对话开始时手动引用。这些办法有一定效果，但本质上还是“人在维护记忆”，AI 并没有主动从项目里获取它该知道的上下文。
直到 AGENTS.md 这一类声明式配置的出现，才让我意识到：AI 编程的记忆问题不应该靠对话轮次去迁就，而是要搬进仓库里，用一种结构化的、可持续维护的方式，把项目的关键记忆显式地写下来。这就是我理解的 Memory 工程——不是给 AI 加一个神秘记忆插件，而是用工程化的方法，把项目上下文整理成 AI 和人可以共同读取、共同维护的资产。AGENTS.md 就是这种思路目前落地最顺的一种形态。
这篇文章我会从无状态聊到有状态，从 AGENTS.md 的基本写法聊到它背后的范式转换，再到 Memory 工程往后还能怎么走。我不会只扔一堆示例文件给你，而是把每个设计决策背后的理由也讲清楚，这样你拿回去能真正落地，而不是抄完格式就完事。
2. 从“每次重新解释”到“进仓库就读懂”：无状态模型为什么必须被打破
2.1 对话式上下文的三个硬伤
我们先认真拆一下，为什么依赖对话窗口传递项目信息这条路走不通。第一个硬伤是容量问题。主流编码助手的上下文窗口再大，也是有上限的。一个中型项目的目录结构、技术选型文档、接口约定、测试规范加起来，轻松超过几十万 token；更别提还有历史 commit、issue 讨论、设计文档这些散落的记忆。你不可能每次启动对话都把这些全塞进去，就算塞得进去，模型也会在超长上下文中逐渐丢失细节，出现所谓“中间遗忘”的现象。
第二个硬伤是维护成本。上下文里的信息是一次性的，项目改了、依赖升了、目录重构了，你手工维护的那一长串背景说明根本来不及跟着改。我自己有段时间维护过一个几十行的“AI 项目背景模板”，每次都要手动更新版本号和目录结构，后来项目一忙就放弃了。只要“背景说明”和“真实仓库”分离，它最终一定会腐化，因为你多了一个本来不该有的维护负担。
第三个硬伤是最隐蔽的：不可复现性。上下文是即时输入的，它没有版本，没有 diff，没有责任人。今天你给 AI 说的是 A 版本的项目背景，明天你自己都可能忘了昨天给的是哪一版。团队协作时，每个人各自维护各自的 prompt，同一段代码在不同人手里，AI 给出的建议可能完全不一样。这种状态对个人用还能忍，对团队项目就是灾难。
2.2 仓库本身才是项目记忆的源
想通这三个硬伤之后，解决方案其实是显而易见的：项目记忆本来就应该待在项目里，而不是待在对话里。仓库里有真实的技术栈声明、真实的目录结构、真实的构建脚本、真实的代码风格，这些才是项目记忆的源头。AI 助手缺的不是“更强的上下文能力”，而是一条从仓库直达模型的路。
AGENTS.md 走的就是这条路。它被放在仓库根目录或者文档目录，作为一个显式声明的入口文件。AI 助手在进入项目后，会先读取这个文件，从而快速重建对项目的整体认知。它的位置是固定的，内容是面向 AI 和人类双重优化的，格式是 Markdown 这种天然可读可写的约定。于是“记忆”第一次从对话里的临时参数，变成了仓库里的持久化资产。
我把这个过程理解成一次范式的转换：从“每次对话临时教”，变成“进仓库就读懂”。前者是无状态模型下被动的补救，后者是主动给模型一个状态初始化入口。这个入口不是模型天然自带的，而是我们通过工程手段构造出来的。这就是 Memory 工程的核心思想——把记忆当作工程对象来设计、部署和维护，而不是听天由命地依赖对话窗口。
2.3 为什么偏偏是 Markdown 而不是别的形式
有人可能会问，项目上下文为什么不用 JSON、YAML 或者专门的配置文件？这个选择其实挺讲究的。Markdown 最大的好处是双重可读：AI 能解析，人也愿意维护。你用 YAML 写项目背景，团队里的工程师大概率没有动力去编辑；但用 Markdown 写，它看起来就像一份普通的项目文档，任何一个路过的开发者都愿意顺手改两句。而且 Markdown 可以自然地承载长文本、列表、代码示例、表格，表达能力的上限很高。
还有一个容易被忽略的点：AGENTS.md 不需要“编译”。任何新加入的 AI 工具，只要支持文件读取，不需要配套的解析器，不需要注册表，不需要插件中心，就能直接从这份文件里获益。这份文件同时也能被人类开发者当作新手指南来读。也就是说，Agents 可读，Agent 可读，人也可读，维护一次，多方受益。这种低摩擦的特性，正是它能在各类项目里快速传播的根本原因。
3. AGENTS.md 到底该怎么写：一份能真正落地的声明式配置
3.1 先定位置：根目录还是 docs 目录
我见过各种放置 AGENTS.md 的习惯，但最稳妥、兼容性最好的位置就是仓库根目录。因为这个路径足够显眼，AI 工具扫描时几乎不需要额外配置就能发现。如果嫌仓库根目录太乱，也可以放在 docs 目录下再在根目录放一个一行软链接式的说明，但我个人不建议绕这一步。文件命名方面，我建议用 AGENTS.md 这个约定俗成的名字，不要改成 project_context.md 或者给 AI 的备忘录之类的自定义名称——约定比特性更值钱，新工具进来能自动识别的，只有约定俗成的名字。
位置定下来之后，再强调一个对齐原则：AGENTS.md 必须和 README 分工明确。README 是给人类看的门面，通常讲项目是什么、能干什么、怎么跑起来；AGENTS.md 是给 AI 辅助编程时的操作手册，重点讲怎么改代码、遵循什么约束、架构上哪里是雷区。两者内容重叠没关系，但视角必须不一样。你如果只把 README 复制成 AGENTS.md，AI 的编码能力并不会提升太多，因为 README 很少写边界约束和代码约定。
3.2 内容区块怎么设计
我给团队和项目写 AGENTS.md 时，基本遵循一个五段式结构：项目认知、构建与验证、代码约定、架构边界、常见陷阱。这五段分别回答 AI 最需要的五类问题：这是什么、我怎么确认没改坏、我下笔该遵循什么风格、哪里不能乱碰、以前在这踩过什么坑。
项目认知段不用长篇大论，三到五句话讲清楚项目定位、主要模块、核心依赖链即可。这里要注意的是，不要写那种放之四海而皆准的空话，比如“本系统采用微服务架构”，而要具体到“本仓库只有一个服务，gateway 模块负责鉴权，mis 模块负责规则计算，两者通过本地消息队列通信”。AI 能从这个描述里获得相对准确的空间感。
构建与验证段是最实用但最容易被忽略的。很多 AGENTS.md 模板都只写“如何构建、如何测试”，但我强烈建议把“如何快速验证一次改动没破功能”这句话单独写清楚。因为 AI 改代码时最大的风险就是瞎改而不自知，如果它每改完一步都知道去跑哪一个具体命令来验证，出错概率会低非常多。比如我要写，就写清楚“改动业务逻辑后必须运行 npm run test:unit；如果需要重新生成接口快照，运行 npm run gen:schema”，这就给了 AI 一条明确的反馈回路。
代码约定段要尽量写成可检查的规则，不要写成抽象理念。与其写“代码要保持高质量”，不如写“本项目禁用 any 类型；函数入参超过两个时必须用对象参数；所有外部 API 调用必须有超时处理和错误上报”。规则越可检查，AI 执行得越可靠。这里还建议把 linter 的名字和配置位置写进去，让 AI 知道它写完可以用什么工具自检。
架构边界段是 Memory 工程里最有价值的部分，相当于把项目里不能碰的“刹车片”声明出来。比如“utils 目录下的代码不允许依赖 domain 层；数据库迁移脚本只允许手工执行，禁止 AI 自动修改；config 文件中的服务地址由部署平台注入，不要在代码里硬编码”。这些人类团队靠口头相传的约束，一旦写进 AGENTS.md，就成了 AI 每次动手前都会过一遍的固定记忆。
常见陷阱段是踩坑经验的沉淀。我会在里面记录一些很奇怪但很真实的坑，比如：这个项目的测试在 Windows 下一定会失败，但 CI 里是正常的，别去改；某个接口的返回值可能有 null，历史上有过三次因为这个导致的线上事故。这些信息对 AI 来说是异常珍贵的先验知识，能避免它重复人类的弯路。
3.3 一个可以直接抄作业的骨架示例
为了更直观，我贴一个精简但结构完整的 AGENTS.md 示例。这个风格适用于中大型仓库，你可以按需删减。
# AGENTS.md ## 项目定位 本仓库是某图像处理服务，负责批量图片的标准化与特征提取。 核心模块：ingest（输入读取）、pipeline（处理流水线）、export（结果输出）。 依赖外部服务：对象存储、结果队列。本地开发使用 docker-compose 启动依赖。 ## 构建与验证 - 安装依赖：pnpm install - 本地启动：pnpm dev - 单元测试：pnpm test （修改 pipeline 相关代码后必须执行） - 集成测试：pnpm test:integration （涉及外部服务调用前执行） - 提交前必须执行：pnpm lint && pnpm typecheck ## 代码约定 - 使用 TypeScript，禁止出现 `any` - 所有异步操作必须处理错误，禁止静默 catch - 函数参数超过 2 个时，使用对象形式传递 - 日志统一使用仓库内的 logger，禁止直接 console.log - 新增环境变量必须同步修改 .env.example 并添加到 README ## 架构边界 - pipeline 目录不允许直接调用外部服务客户端，必须经过 adapter 封装 - export 模块的输出结构变更需要得到全组确认，禁止单方面改动 - 所有数据库查询必须走仓储接口，禁止在业务代码中拼 SQL - 禁止修改 docker-compose.yml 中服务名称和端口 ## 常见陷阱 - Windows 本地跑集成测试大概率超时，这是环境问题，别改测试代码 - 对象存储的公共前缀曾在某次重构中被误改，读取路径必须以配置项为准 - 某些历史图片没有宽高信息，处理时要做空值保护这个示例里，每一段都是能直接转成 AI 行动准则的内容。你不需要写得像散文一样优美，越接近指令集越好。
3.4 好坏的界限：能用一句话判断 AGENTS.md 设计得好不好
每次给新项目写完 AGENTS.md，我都会做一个简单测试：把文件丢给一个没有看过这个仓库对话历史的 AI，让它自己写一个一两百行的小功能，看它会不会踩到仓库里那些隐蔽的雷。如果它一上来就试图修改 docker-compose.yml 或者直接跳过 logger 用 console.log，说明我这份文件写得还不够细；如果它写出来的代码风格跟团队平常的提交几乎没有差别，说明这份文件已经进入了状态。
这个测试思路其实就是 Memory 工程里的“冷启动验证”。无状态模型下，每次启动都是冷启动；有了 AGENTS.md 之后，冷启动的时间被压缩到了读文件的那一刻。判断配置好不好，就看 AI 读完之后的行为偏移量有多大。偏移量越小，说明记忆工程做得越到位。
4. 声明式配置带来的连锁变化：从提示词工程到记忆工程
4.1 提示词工程为什么慢慢不够用
前两年大家谈 AI 编程提得最多的词是“提示词工程”，怎么措辞、怎么给例子、怎么拆步骤，都在对话层面做文章。我承认提示词工程在单次对话里依然重要，但它有一个天花板：提示词是一次性的，它解决的问题是“如何让模型在当前对话里更好地理解我”，而不是“如何让模型在下一次对话里还记得我”。
当项目规模变大、协作人数变多之后，你会发现“如何把上下文稳定地传给模型”比“如何措辞让模型听懂”更棘手。这时候重心就转移到了记忆侧。AGENTS.md 就是一种把提示词沉淀到仓库的问题。它的思路是：把那些你反复在对话里输入的背景和约束，一次性写进仓库，模型自动读取。你不再需要在每次对话里重新精准地措辞，因为文件就是最大最稳定的提示词。
4.2 AGENTS.md 不只是给 AI 看的配置文件
有一个很容易被低估的实际效果：AGENTS.md 写清楚之后，团队里的人类新成员也受益。这份文件本来是要让 AI 读懂项目的边界，但它同时也能帮新人快速了解哪些地方不能乱动。我们团队现在有一个惯例——新人入职第一周不读长篇架构文档，先读一遍 AGENTS.md，跟着它把构建命令、代码约定、架构边界过一遍，比看三天 wiki 都管用。
我甚至觉得，AGENTS.md 的长期价值甚至不是帮你更好地用 AI，而是逼迫你把项目里那些“默认大家都懂但其实没人写下来”的知识显式化。这类知识一旦显式化，团队就不再依赖某个资深工程师的口头记忆，项目的健壮性因此上了一个台阶。记忆工程听起来像给 AI 做的，实际操作下来，最先受益的反而是人。
4.3 声明式的边界：为什么不用复杂 DSL
这款方案也有人上来就问：AGENTS.md 这么普通，为什么不做一个专用的 AI 记忆格式，结构更强、校验更强？我的观点是，复杂度必须和收益成正比。专用格式需要工具链支持，而每个团队的 AI 工具栈千差万别，今天这个助手认这个格式，明天换一个助手可能就不认了。Markdown 恰好站在兼容性和表达力的交叉点上，用极低的格式成本获得了最大的共识度。
但反过来也要承认，AGENTS.md 不是银弹。它适合描述稳定的事实约束，不适合承载动态变化的实时信息。比如“当前某任务的最新进展”“这个 bug 正处于排查中段”这类时序性记忆，就不适合写进静态文件里。这一块需要别的工具来补充，我在第六节会展开讲。
4.4 Memory 工程不是让你把所有东西都写进文件
这里我要特意泼一盆冷水：AGENTS.md 是一个入口，不是一个垃圾桶。有人看到这个模式之后开始事无巨细地把所有东西往里塞，目录里每个文件都写一行说明，每个模块的历史决策都写一段长篇分析。这么做的问题在于——AI 每次读文件都要消耗上下文窗口，文件越长，有效信息的密度反而越低。你写了两千行 AGENTS.md，AI 真正锚定在关键约束上的注意力反而被稀释了。
所以 Memory 工程的第一条纪律是克制。写进 AGENTS.md 的每一条都必须回答一个问题：“AI 不知道这件事，会不会写出让我返工的代码？”如果答案是“不会”，那就别写。上下文密度比文件完整性重要得多。
5. 从单仓库文件到多层级记忆：团队协作时 AGENTS.md 的完整形态
5.1 根文件与子模块文件怎么分工
很多项目长得并不是一个平面，而是 monorepo 或者多仓库结构。这种时候只放一个根级 AGENTS.md 就有点不够用了。我目前验证下来比较靠谱的做法是二级结构：仓库根目录放一个面向全局的根文件，定义通用约定、构建入口、团队规范；每个独立子包或子模块里再放一个轻量级 AGENTS.md，只写这个模块特有的边界和陷阱。AI 进入某个模块所在的路径时，可以同时参考两层文件。
做这种分层时，要注意保持约束方向的一致，不能根文件说“禁止使用 any”，子模块文件里却写“本模块可例外”。如果真存在例外，正确的做法是在根文件里明确写“全局禁止 any，仅某模块内部因历史原因可有限使用，且新增代码仍需避免”，而不是在子文件里悄悄开口子。因为 AI 读取文件的顺序不确定，互相矛盾的约束会让它的行为非常不稳定。
5.2 团队如何维护 AGENTS.md 的质量
任何文件只要没有人维护，就会慢慢腐烂。AGENTS.md 也一样，所以必须把它纳入正常的代码审查流程。我建议约定“任何改动项目架构、构建方式、关键依赖、代码风格规则时，必须同步更新 AGENTS.md”，这个要求可以写进团队的 PR 模板里。它不是一个文档任务，而是一个工程质量任务，和更新测试用例同等重要。
我在实际维护中还会定期做一个“记忆审计”：每隔一段时间，挑一个 AI 实际产生的 diff，对比它在 AGENTS.md 更新前后的行为差异。如果发现 AI 反复犯某一类错误，而仓库里没有一条声明能阻止它，那就补一条；如果某条规则 AI 从来不会触发，而人看了又觉得多余，那就删掉。这个过程和代码重构里的“坏味道清理”很像，只不过清理的对象是 AI 的先验知识。
5.3 争议场景：AI 修改 AGENTS.md 要不要管
一个很有意思的问题是：AI 在写代码时，能不能让它自己顺手修改 AGENTS.md？我的态度比较谨慎。AI 可以提出修改建议，但不应该被授权直接修改。因为 AGENTS.md 是对项目记忆的固化，一旦 AI 可以自行改写记忆，它就可能为了让自己的行为看起来合规而淡化一些真实约束。这种自我参照的修改会破坏记忆的可信度。
更好的流程是，AI 在实现一个新功能时，如果发现项目存在与 AGENTS.md 不一致的地方，先在代码注释或 commit 里记录，然后在输出中明确提示人类维护者，你需要去看看这份记忆文件是不是过期了。也就是说，AI 是记忆的使用者，人类才是记忆的裁决者。
6. AGENTS.md 只是起点：Memory 工程的下一个阶段
6.1 静态文件解决不了的时序问题
AGENTS.md 解决了大部分“项目是什么、有什么规则”的静态上下文问题。但我很快碰到了它的边界：有一次我让 AI 接着昨天的任务继续实现某个模块的消息重试逻辑，它确实读懂了项目结构，却完全不知道“重试队列的设计我们已经讨论过三轮、排除了延时队列方案”这个关键结论。这种动态决策记忆，AGENTS.md 里没有，也不可能静态地写全。
这类记忆属于“会话流”层面。要想接住它，就需要在对话之外维护一份持续更新的会话摘要或决策记录，让 AI 在跨会话恢复任务时，不只是知道项目长什么样，还能知道上一次讨论停在哪里、哪些方案被否决过、眼下正在进行什么。这不是 AGENTS.md 的任务，但它绝对是 Memory 工程的下一个交叉点。
6.2 记忆的三个层次可以同时存在
我现在倾向于把 AI 编程里的记忆理解成三个层次。第一层是仓库层，由 AGENTS.md、README、架构文档这类声明式文件组成，特点是稳定、可审阅、面向全体；第二层是会话层，由每次对话的摘要、活跃任务状态、未完成决策组成，特点是易变、需要持续更新；第三层是个人层，由每个人使用 AI 的习惯、偏好、常用技术决策组成，特点是主体绑定、跨项目复用。
AGENTS.md 完美覆盖了第一层，但第二层和第三层目前还没有统一标准。好在很多工具和框架已经开始探索这些方向。我自己目前的做法是，在关键会话结束时用一小段时间把“本轮决定了什么、下一步要做什么”摘出来，追加到项目内的一个 CHANGELOG_ai.md 文件里，让下一个会话说：“可以参考根目录的 AGENTS.md，再翻一下 CHANGELOG_ai.md 里最近三条决策记录”。这个做法很朴素，但效果立竿见影。
6.3 声明式配置的哲学：约束可读性，胜过约束模型
我在这段时间的实践里，慢慢形成了一个判断：AI 编程的工具形态一定会进入一个“配置显式化”的时代。AGENTS.md 是这个时代的第一块基石，它的精髓不在于语法多强、格式多复杂，而在于它把人类对项目的理解，以可读、可审查、可演进的方式交给了 AI。
顺着这个思路，Memory 工程未来很长一段时间的主线，都是不断把潜意识里的项目知识转译成清晰声明。今天你用 AGENTS.md 记下的每一条架构边界，明天就会变成 AI 少犯的一个错误、少给团队添的一个麻烦。对个人开发者来说，这是给未来的自己减少重复解释的工作量；对团队来说，这是把隐性知识显性化、把个人经验组织化。
所以我最后的建议是：不要等技术社区形成所谓标准再动手。你现在就可以在你的仓库根目录创建一个 AGENTS.md，先写五条这个项目里你一定要强调的约束，下次开新会话时把它指给 AI 读一遍，感受一下状态的切换。跑完这第一轮，你就明白我前面说的范式转换是什么体验了。剩下的，就是把这个文件当作代码一样持续打磨。
