1. 从无状态到有状态：AI 编程范式转换的底层逻辑
1.1 为什么无状态模型是当前 AI 编程的最大瓶颈
如果你最近半年深度用过任何一款 AI 编程助手，大概率经历过这种场景：第一轮对话它帮你把某个模块重构得漂漂亮亮，第二轮你让它接着改另一个关联文件，它却像失忆了一样，把你上一轮定下的命名规范、目录结构、错误处理风格全部抛到脑后。你不得不把之前的上下文重新贴一遍，甚至贴了三遍它还是记不住。
这不是模型不够聪明，而是无状态（Stateless）架构决定的。当前绝大多数 AI 编程工具的运行模式是：每次请求把上下文窗口塞满，模型基于这一次的输入生成输出，请求结束，一切归零。下一次请求，模型面对的是一张白纸。它没有持久记忆，没有跨会话的项目认知，更没有对你个人编码偏好的长期积累。
这个问题的本质，跟早期 Web 开发从无状态 HTTP 协议演进到 Session、Cookie、Token 机制的过程极其相似。HTTP 本身是无状态的，但工程师们通过外部存储层把状态"挂"了上去。AI 编程现在正处在同一个转折点上——从无状态模型调用，走向有状态的工程化配置。
我自己的体感是，无状态带来的损耗远比想象中大。一个中型项目里，每次让 AI 参与编码，光是"项目背景介绍"这一项就要消耗 800 到 1500 个 token，如果涉及多轮迭代，重复上下文的开销能占到总 token 消耗的 40% 以上。更致命的是一致性断裂：同一个项目里，AI 今天给你写getUserInfo，明天写成fetchUserData，后天又变成queryUser，命名风格飘忽不定，代码 review 时看得人血压升高。
1.2 范式转换的核心：把"记忆"从模型内部搬到工程配置层
既然模型本身不记忆，那我们就不能指望它记住。正确的思路是：把需要持久化的信息，从模型内部搬到模型外部的工程配置层。这就是 Memory 工程的核心思想。
打个比方。模型是一个能力极强但每天上班都失忆的天才程序员。你不能指望他记住昨天开会的内容，但你可以给他准备一份工位上的项目手册——他每天到岗第一件事就是翻这本手册，翻完就知道项目用什么框架、遵循什么规范、上次改到哪了。这本手册就是 Memory 工程要解决的东西。
具体到落地层面，Memory 工程要解决三类记忆：
- 项目级记忆：技术栈、目录结构、构建命令、依赖版本、代码规范。这类信息相对稳定，变更频率低。
- 会话级记忆：当前任务的上下文、已完成的改动、待办事项、决策记录。这类信息生命周期短，但需要跨多轮对话保持。
- 用户级记忆：开发者个人的编码偏好、常用工具链、沟通风格。这类信息跨项目复用，是长期资产。
传统做法是把这三类信息全部塞进 prompt，每次请求都重复发送。问题是 token 成本高、维护困难、容易遗漏。而声明式配置的思路是：把这些信息写成结构化的配置文件，放在项目仓库里，AI 工具启动时自动读取，按需注入上下文。这样既保证了信息的一致性，又大幅降低了重复输入的负担。
1.3 AGENTS.md 为什么成为这个范式的关键载体
在众多声明式配置方案里，AGENTS.md这个约定值得单独拿出来讲。它的设计哲学非常朴素：用一份 Markdown 文件，声明这个项目里 AI 代理应该如何工作。
为什么是 Markdown 而不是 JSON 或 YAML？因为 Markdown 对人类友好，对模型也友好。开发者可以直接阅读、编辑、版本控制，模型解析起来也没有格式负担。更重要的是，Markdown 天然支持自由结构，你可以用标题分层、用列表枚举、用代码块给示例，表达力足够覆盖绝大多数配置需求。
AGENTS.md通常放在项目根目录，内容涵盖几个核心板块：项目概述、技术栈说明、目录约定、编码规范、常用命令、禁止事项、以及特定任务的执行指引。AI 工具在启动时读取这份文件，把它作为系统提示的一部分注入，从而让模型"知道"这个项目的规矩。
我实测下来，一个配置得当的AGENTS.md能把 AI 生成代码的首次可用率从 50% 左右提升到 80% 以上。这个提升不是模型变强了，而是信息对齐成本被前置消化了。模型不再需要猜你的意图，因为意图已经白纸黑字写在配置文件里。
注意：
AGENTS.md不是某个厂商的私有标准，而是一种社区约定。不同工具对它的解析方式可能有差异，但核心思路一致——用声明式文件承载项目记忆。
2. Memory 工程的核心细节与配置实操
2.1 AGENTS.md 的黄金结构：六个必写板块
很多人第一次写AGENTS.md会写成一篇散文，想到哪写到哪，结果模型读完之后还是抓不住重点。我踩过这个坑之后，总结出一套相对稳定的结构，分成六个板块，每个板块解决一类问题。
第一板块：项目定位。用三到五句话说明这个项目是干什么的、服务谁、核心价值是什么。这部分不需要技术细节，目的是让模型建立宏观认知。比如"这是一个面向中小团队的内部工单系统，前端用 React，后端用 Node.js，数据存储用 PostgreSQL"。
第二板块：技术栈清单。把语言、框架、主要依赖、版本号列清楚。这里有个细节：版本号一定要写。我遇到过模型用 React 18 的语法写 React 16 项目的情况，就是因为没声明版本。版本信息能避免大量低级错误。
第三板块：目录结构约定。用代码块画出关键目录树，标注每个目录的职责。模型对目录结构的理解直接影响它把文件放对位置的能力。不写这块，它可能把组件扔到utils里，把工具函数塞进components里。
第四板块：编码规范。命名风格、缩进、注释要求、错误处理模式、日志规范。这部分越具体越好。不要写"遵循最佳实践"这种废话，要写"函数名用 camelCase，常量用 UPPER_SNAKE_CASE，异步操作统一用 async/await 不用 then 链"。
第五板块：常用命令。安装依赖、启动开发服务器、跑测试、构建产物的命令全部列出来。模型在需要执行命令时会直接引用这些，避免它自己瞎猜。
第六板块：禁止事项。明确列出不能做的事。比如"不要引入新的第三方依赖除非明确要求"、"不要修改config目录下的文件"、"不要用any类型"。禁止事项是防止模型"自作聪明"的关键护栏。
下面是一个精简版的示例结构：
# AGENTS.md ## 项目定位 内部工单系统，React + Node.js + PostgreSQL。 ## 技术栈 - 前端：React 18.2, TypeScript 5.3, Vite 5.0 - 后端：Node.js 20, Express 4.18 - 数据库：PostgreSQL 15 - 测试：Vitest, Playwright ## 目录结构 - src/components：UI 组件 - src/hooks：自定义 hooks - src/api：接口封装 - src/utils：纯工具函数 - server/routes：后端路由 - server/services：业务逻辑 ## 编码规范 - 函数名 camelCase，常量 UPPER_SNAKE_CASE - 异步统一 async/await - 所有导出函数必须有 JSDoc 注释 - 错误统一用 AppError 类包装 ## 常用命令 - 安装：pnpm install - 开发：pnpm dev - 测试：pnpm test - 构建：pnpm build ## 禁止事项 - 不引入新依赖除非明确要求 - 不修改 config 目录 - 不使用 any 类型 - 不写 console.log，用 logger这份文件大概 300 到 500 字，但信息密度极高。模型读完它，基本就能像一个熟悉项目的成员一样工作。
2.2 会话级记忆的落地：任务清单与决策日志
AGENTS.md解决的是项目级记忆，但会话级记忆需要另一套机制。核心思路是：在项目里维护一份任务清单和一份决策日志，让 AI 在每轮对话开始时读取，结束时更新。
任务清单可以是一个简单的TASKS.md，记录当前迭代的待办、进行中、已完成事项。决策日志可以叫DECISIONS.md，记录"为什么这么做"——比如"选择 Zustand 而非 Redux，因为项目状态复杂度低，Redux 样板代码太多"。
这两份文件的价值在于：当 AI 在新会话里接手任务时，它不需要你从头解释，读一遍这两份文件就能接上进度。我实测下来，这套机制能把多轮迭代的上下文重建时间从平均 5 分钟压缩到 30 秒以内。
具体操作上，我会在AGENTS.md里加一段指引：
## 会话工作流 1. 开始任务前，先读 TASKS.md 和 DECISIONS.md 2. 完成任务后，更新 TASKS.md 的状态 3. 做出重要技术决策时，追加到 DECISIONS.md这样模型就形成了"读记忆-干活-写记忆"的闭环。这个闭环一旦跑通，AI 编程的体验会发生质变——它不再是每次从零开始的工具，而是一个有连续性的协作者。
2.3 用户级记忆：跨项目的个人偏好配置
项目级和会话级记忆解决的是"这个项目怎么干"，用户级记忆解决的是"我这个人习惯怎么干"。这部分信息跨项目复用，值得单独抽出来维护。
我的做法是在用户主目录下放一份~/.ai-preferences.md，记录个人编码偏好。比如：
- 我偏好函数式风格，少用 class
- 我习惯用早返回（early return）减少嵌套
- 我要求所有异步函数处理错误，不允许裸 await
- 我偏好简洁的变量命名，不用匈牙利命名法
- 我讨厌过度注释，只在复杂逻辑处写注释
然后在每个项目的AGENTS.md里引用这份文件：
## 个人偏好 参考 ~/.ai-preferences.md，项目规范与个人偏好冲突时以项目规范为准。这个优先级声明很重要。项目规范是团队共识，个人偏好是补充，冲突时必须让项目规范优先，否则多人协作时会乱套。
2.4 配置文件的版本控制与团队协作
AGENTS.md和相关的记忆文件应该纳入 Git 版本控制，跟代码一起管理。这样做有三个好处：一是团队成员共享同一份 AI 配置，保证 AI 辅助产出的一致性；二是配置变更可追溯，谁改了规范一目了然；三是新人入职时，AI 配置直接跟着仓库走，不需要额外培训。
但这里有个坑：不要把敏感信息写进AGENTS.md。比如内部 API 地址、密钥、特定人员信息。这些应该放在环境变量或独立的私有配置里，AGENTS.md只引用不展开。
团队协作场景下，我建议把AGENTS.md的修改纳入 code review 流程。任何对 AI 行为规范的调整，都应该像改代码一样被 review。我见过团队里有人随手在AGENTS.md里加了条"允许使用 any 类型"，结果整个团队的 AI 生成代码质量集体下滑。
3. 完整实操流程：从零搭建一套 Memory 工程
3.1 第一步：盘点现有项目的记忆缺口
动手写配置之前，先做一次盘点。拿一个你熟悉的项目，问自己几个问题：AI 在这个项目里最常犯什么错？哪些信息你每次都要重复解释？哪些规范 AI 总是记不住？
把答案列出来，就是你的记忆缺口清单。常见的缺口包括：目录职责不清导致文件放错位置、命名风格不统一、错误处理模式不一致、测试写法不符合项目习惯、依赖引入不受控。
我自己的盘点习惯是翻最近 20 次 AI 对话记录，统计哪些纠正性回复出现频率最高。出现三次以上的问题，就值得写进AGENTS.md。这个方法很土但极其有效，因为它直接对准了真实痛点，而不是拍脑袋想规范。
3.2 第二步：编写 AGENTS.md 并做首次验证
盘点完成后开始写AGENTS.md。第一版不要追求完美，先把六个板块的骨架搭起来，内容填个七八成即可。写完立刻做验证：让 AI 执行一个典型任务，观察它是否遵循了配置。
验证时重点看三个指标：首次可用率（生成代码直接能用不用改的比例）、规范遵循率（命名、结构、错误处理是否符合配置）、追问次数（你需要额外解释多少次）。我第一版配置的首次可用率大概 65%，追问次数从平均 4 次降到 1.5 次，已经能明显感觉到效率提升。
验证过程中发现的遗漏，立刻补进配置。比如发现 AI 总是忘记写测试，就在编码规范里加一条"所有新增函数必须配套单元测试"。这种迭代式完善比一次性写完美配置更实际。
3.3 第三步：接入任务清单与决策日志
AGENTS.md跑顺之后，接入会话级记忆。创建TASKS.md和DECISIONS.md，在AGENTS.md里声明工作流。然后开始实际使用：每接一个任务，先让 AI 读这两份文件，任务完成后让它更新。
这里有个实操细节：任务粒度要适中。太粗（比如"重构整个后端"）AI 抓不住重点，太细（比如"改一个变量名"）又没必要走这套流程。我的经验是，单个任务控制在 30 分钟到 2 小时工作量之间最合适。
决策日志的记录时机也有讲究。不要等任务全部做完再补，而是在做出决策的当下就记。因为事后回忆容易丢失当时的权衡过程，而权衡过程恰恰是决策日志最有价值的部分。
3.4 第四步：建立个人偏好层并处理优先级
项目级和会话级跑通后，抽出个人偏好层。把跨项目通用的偏好写进~/.ai-preferences.md，在各项目AGENTS.md里引用。这一步的关键是明确优先级：项目规范 > 个人偏好 > 模型默认行为。
我见过有人把个人偏好写得比项目规范还强势，结果在团队项目里 AI 生成的代码跟团队风格格格不入。记住，个人偏好是锦上添花，不是喧宾夺主。
3.5 第五步：持续迭代与效果度量
Memory 工程不是一次性工程，而是持续迭代的过程。我建议每个月做一次回顾：统计这个月 AI 生成代码的首次可用率、规范遵循率、追问次数，跟上月对比。如果指标停滞或下滑，说明配置需要更新。
度量指标不用太复杂，三个就够：
| 指标 | 含义 | 目标 |
|---|---|---|
| 首次可用率 | 生成代码直接可用比例 | 80% 以上 |
| 规范遵循率 | 符合项目规范的比例 | 90% 以上 |
| 平均追问次数 | 每个任务额外解释次数 | 1 次以内 |
这三个指标能直观反映 Memory 工程的健康度。首次可用率低说明配置信息不足，规范遵循率低说明规范描述不清，追问次数高说明记忆覆盖有盲区。
4. 常见问题与排查技巧实录
4.1 配置写了但 AI 不遵守怎么办
这是最高频的问题。配置明明写了"用 async/await"，AI 还是给你写 then 链。排查思路分三层：
第一层，检查配置是否被正确加载。不同工具加载AGENTS.md的方式不同，有的自动读取，有的需要显式指定路径。先确认配置真的进了上下文。可以在对话里直接问 AI"你读到了哪些项目规范"，看它的回答是否包含你写的内容。
第二层，检查配置表述是否明确。模糊的表述模型容易忽略。比如"遵循良好命名规范"这种话等于没说，要改成"函数名用 camelCase，常量用 UPPER_SNAKE_CASE"。越具体越容易被遵守。
第三层，检查配置是否过长。AGENTS.md不是越长越好。超过 2000 字之后，模型的注意力会被稀释，后面的内容容易被忽略。如果配置确实很长，把次要内容拆到独立文件，在AGENTS.md里用引用方式链接。
4.2 多项目配置冲突怎么处理
同时维护多个项目时，配置冲突很常见。比如 A 项目用 tabs 缩进，B 项目用 spaces。这时候项目级配置必须覆盖用户级配置，这是铁律。
我的做法是在用户级偏好文件顶部写一句声明："以下偏好为默认值，项目级 AGENTS.md 中的规范优先级更高。"然后在每个项目的AGENTS.md里明确写出该项目特有的规范。这样模型读到冲突信息时，有明确的优先级指引。
4.3 配置更新后 AI 行为没变化
有时候你更新了AGENTS.md，但 AI 行为跟之前一样。这通常是缓存问题。很多工具会缓存配置文件，更新后需要重启会话或手动刷新。排查时先确认工具是否有缓存机制，如果有，清缓存后重试。
另一个可能是会话上下文污染。如果当前会话已经进行了很多轮，早期的上下文可能还在影响模型。这时候开一个新会话，让模型重新读取最新配置，通常就能解决。
4.4 团队协作中配置被随意修改
团队场景下，AGENTS.md被随意修改是个隐患。防护措施有三条：一是把AGENTS.md纳入 code review，修改必须经过 review；二是用 Git hook 在提交时检查配置文件的变更，重要变更触发通知；三是在AGENTS.md顶部加一段"修改须知"，提醒修改者谨慎操作。
我见过最有效的做法是给AGENTS.md加一个"变更日志"板块，每次修改记录谁改的、改了什么、为什么改。这样既留了痕，也让修改者更有责任感。
4.5 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 |
|---|---|---|
| AI 不遵守配置 | 配置未加载/表述模糊/过长 | 确认加载、具体化表述、拆分文件 |
| 多项目配置冲突 | 优先级不明确 | 项目级覆盖用户级 |
| 更新配置无效果 | 缓存/上下文污染 | 清缓存、开新会话 |
| 团队配置被乱改 | 缺乏 review 机制 | 纳入 review、加变更日志 |
| 首次可用率低 | 记忆覆盖不足 | 盘点缺口、补充配置 |
| 追问次数高 | 会话记忆缺失 | 接入任务清单与决策日志 |
4.6 几个我踩过的坑
第一个坑是配置写太满。我一开始恨不得把所有规范都写进去，结果AGENTS.md写到 3000 多字，模型反而抓不住重点。后来精简到 800 字左右，效果反而更好。配置不是越多越好，而是越精准越好。
第二个坑是忽略版本号。有次没写 React 版本，AI 用 React 18 的并发特性写 React 16 项目，跑起来直接报错。从那以后我所有依赖都标版本号。
第三个坑是决策日志记太晚。有次任务做完一周后才补决策日志，结果当时为什么选某个方案完全想不起来了，补出来的日志全是套话，毫无价值。决策日志必须当场记。
第四个坑是个人偏好压过项目规范。我在一个团队项目里，个人偏好写了"偏好函数式风格"，结果 AI 把团队约定用 class 写的组件全改成函数式，review 时被同事吐槽。后来我在个人偏好文件里加了优先级声明，问题才解决。
5. 范式转换的边界与后续演进方向
5.1 Memory 工程解决不了什么
说了这么多 Memory 工程的好处，也得说清楚它的边界。它解决的是信息对齐问题，解决不了能力上限问题。如果模型本身不具备某种能力，配置写得再好也没用。比如让一个不支持长上下文的模型处理超长文件，配置再完善它也会截断。
它也解决不了需求模糊问题。如果开发者自己都没想清楚要做什么，配置里写不出清晰的任务描述，AI 照样抓瞎。Memory 工程的前提是，你知道自己要什么，只是懒得每次重复说。
还有一个边界是动态变化。项目在快速演进期，目录结构、技术栈频繁变动，配置维护成本会很高。这种情况下，配置的更新频率要跟上代码变更频率，否则配置会变成过时信息，反而误导 AI。
5.2 从声明式配置到自适应记忆
当前 Memory 工程的主流形态是声明式配置——人写配置，AI 读配置。下一步的演进方向是自适应记忆：AI 从实际交互中自动提取记忆，减少人工维护成本。
这个方向已经有了一些雏形。比如某些工具能自动记录"用户上次纠正了什么"，下次遇到类似场景自动应用。但目前的自动化程度还比较低，提取的记忆质量参差不齐，人工审核仍然必要。
我个人的判断是，未来两到三年内，声明式配置和自适应记忆会并存。声明式配置负责稳定的、需要精确控制的记忆，自适应记忆负责动态的、需要快速积累的记忆。两者互补，而不是替代。
5.3 给不同阶段开发者的建议
如果你是刚接触 AI 编程的新手，建议从最简单的AGENTS.md开始，先写项目定位和技术栈两个板块，跑顺了再逐步补充。不要一上来就搞全套 Memory 工程，容易劝退。
如果你已经用了一段时间 AI 编程，感觉效率遇到瓶颈，那大概率是记忆缺口在拖后腿。做一次系统盘点，把重复解释的内容固化到配置里，效果立竿见影。
如果你是团队负责人，建议把 Memory 工程纳入团队规范。统一AGENTS.md模板，纳入 code review，定期回顾指标。这套东西的团队收益远大于个人收益，因为一致性在协作场景下价值更高。
5.4 一个值得关注的趋势：配置即文档
最后分享一个我观察到的趋势：AGENTS.md这类配置文件，正在变成一种新型项目文档。传统项目文档写给人类看，AGENTS.md同时写给人类和 AI 看。它既是 AI 的工作指引，也是新人的入职指南。
这个双重属性带来一个好处：写AGENTS.md的过程，本身就是一次项目知识的梳理。很多团队写着写着发现，自己对项目的理解都更清晰了。这可能是 Memory 工程的一个意外收获——它不仅让 AI 更懂项目，也让人更懂项目。
我在实际使用中的体会是，Memory 工程的价值不在于省了多少 token，而在于它强迫你把隐性知识显性化。那些平时靠口口相传、靠肌肉记忆的项目规范，一旦写下来，就变成了可传承、可迭代的资产。这件事的意义，可能比 AI 编程本身还要大。
