你有没有遇到过这种情况编码助手上一轮还在帮你按某个设计模式重构模块你换了个对话窗口继续提需求它却像失忆一样把之前的约定全部推翻甚至开始推荐另一套技术方案。我一度以为是自己的提示词写得不到位后来反复试过才发现问题不在于我把需求解释得够不够清楚而在于我们正在用的这些AI编码工具本质上都是“无状态”的。无状态模型是当前绝大多数编码助手背后的架构现实每一次对话都是孤立的模型不记得上一个会话里确认过的规则、否掉的方案、明确过不要碰的代码区域。它看起来很聪明但这种聪明是“片场式的”——每场戏都是新的演员没有连续的角色记忆。真正要解决这个问题光靠堆提示词没有用更本质的做法是转向“记忆工程”把项目的约定、边界、决策和工作流从模型的短期对话里剥离出来沉淀成项目里的持久化资产。这也是AGENTS.md这类声明式配置文件被越来越多人讨论的原因——它试图把“AI应该怎么在这个项目里工作”这件事变成一份只要进入仓库就能被读懂的说明书。这篇文章我想完整拆解这个范式转换为什么无状态会卡住AI编程的脖子记忆工程的分层思路是什么AGENTS.md 到底该怎么写、写到什么程度、哪些坑我实际踩过。内容主要面向正在重度使用编码助手的开发者、技术负责人以及所有想让AI从“偶尔惊喜”变成“持续可靠”的人。1. AI编码助手的“失忆”真相无状态模型的日常翻车现场1.1 最典型的翻车场景几乎每个重度用户都经历过先说一个我最近一周内连续遇到三次的场面。我正在开发一个内部用的数据同步工具代码量不大但模块边界很明确采集层、转换层、写入层分开转换层里有一堆业务规则。头一天我让编码助手帮忙重构了转换层的函数签名把原来传6个参数的旧接口收敛成一个配置对象并且在对话里明确说了“所有调用点一起改测试也要跟上”。它当时完成得相当利索函数重构、调用点替换、测试用例更新都做完了。第二天我新建了一个对话窗口想让它继续给转换层添加一个新的映射规则。结果它开始“自由发挥”先是用回旧接口风格写了一段新函数接着又提议把转换层拆成两个子模块。我盯着屏幕看了半分钟——代码看起来没错测试应该也能过但它完全无视了昨天才建立的项目约定。因为对于每个新会话来说它确实“不知道”昨天发生过什么。它没有恶意它就是一台没有硬盘的电脑每次开机都是全新系统。这种体验带来的挫败感是双重的。一方面你需要反复重申上下文把项目背景、技术选型、编码规范在每一轮对话里重新交代一遍另一方面即使你交代了它也可能因为对话超长、信息过载而把早期的约定遗忘掉。最终的结果就是编码助手从“团队里的实习工程师”退化成“记性很差但手速极快的临时工”。1.2 根因不是“模型笨”而是“架构无状态”很多人在吐槽编码助手“智商不够”之前并没有意识到一个更底层的问题无状态是当前服务体系的基础架构设定。所谓无状态指的是AI服务在处理每一次请求时都不会自动携带上一次请求产生的任何信息。没有跨会话的数据库没有用户可写的持久化存储唯一能传递信息的通道就是你在对话框里敲进去的字。这个设计在Web服务时代是正确的因为无状态意味着可以水平扩展、负载均衡、任意一台机器都可以应答任何请求。但它是为“短请求-短响应”设计的不是为“一个跨越多天、涉及多个文件的软件项目”设计的。软件工程的本质恰恰是长周期、多上下文的状态管理一个项目有几十个文件每个文件有几百行代码文件之间还有复杂的依赖关系这些信息加在一起远超任何一次对话能够携带的内容量。所以问题就变成了一个经典的系统矛盾工具的能力很强但它没有任何“记忆存储”的接口用户手里有海量项目上下文却只能靠一次性的对话窗口一点点投喂。在无法改变模型底层架构的前提下我们应该做的并不是祈祷下一次对话更聪明而是在应用层上建立一套“记忆管理机制”——把该记住的内容从对话里拿出来放到项目里让每个新会话启动时都能自动加载。这就是记忆工程的出发点。2. 为什么“把上下文全塞进提示词”不是出路上下文窗口与项目体积的硬矛盾2.1 上下文窗口看着很大但项目比你想象得更“胖”关于上下文窗口一个常见的误解是现在的主流大模型动不动就是几十万token的上下文一个项目的代码好像也没多少全塞进去不就行了但只要你算过就会发现这个想法并不现实。我以自己那个数据同步工具为例做了一个粗略统计。它总共28个Python文件加起来约8000行代码。8千行代码换算成token大约在12万到16万之间——纯代码部分就已经很接近部分模型的窗口上限了。可项目里的上下文不止代码还需要知道README里的项目目标与运行方式、配置文件里的连接信息与调度设置、测试文件里的断言约定、最近几个版本的变化记录。把这些都算上轻松突破20万token。更麻烦的是token上限只是“容量”不是“有效记忆”。在实际使用中模型对长上下文的注意力是递减的中间部分的记忆往往比开头和结尾要模糊。你把整个项目都粘进对话窗口它反而可能记住开头、记住结尾把中间最关键的逻辑规则给“选择性遗忘”了。所以“上下文窗口越来越大”解决不了根本问题它只是把问题从“装不下”变成了“装下了但记不清”。2.2 伪状态方案RAG召回和会话摘要各自的失真问题既然全量塞进上下文不行业内自然出现了两种折中方案我分别叫它们“伪状态”方案。第一种是检索增强生成通俗地说是把代码库切成小块做向量化索引每次根据用户问题召回最相关的片段再送给模型。第二种是会话摘要在对话超过一定长度后把前面的讨论压缩成一两页的“会议纪要”作为后续对话的前缀。这两种思路我都用过各有各的价值但也都谈不上真正的记忆。检索方案的问题在于召回质量极不稳定模型并不知道自己“不知道什么”它只会把你问的片段找出来却很难主动感知那些相关的、但你根本没提及的文件。如果有一个约定藏在某个模块的注释里而你问的是另一个模块检索系统可能根本不会把它捞出来。摘要方案的问题更直接压缩必然损失信息。一次关于“为什么不用某个框架”的长讨论压缩成摘要可能就只剩一句“经讨论决定不用某框架”可当初否掉它的三个技术原因全部消失了下次遇到类似问题AI还会再踩一遍。我把这两种方案称为“伪状态”因为它们只是在模拟有记忆本质上还是无状态。真正的记忆工程需要更可靠的策略——不是依赖模型在请求时临时拼凑上下文而是把它变成项目结构里的一部分用可声明、可维护、可审计的方式存放起来。3. 记忆工程的基本思路从“让AI记住”到“让AI查得到”3.1 记忆分级会话记忆、项目记忆、长期偏好记忆接触到“记忆工程”这个概念之后我逐渐形成了一个分析框架把AI编程场景中的记忆分成三个层级来管理。第一层是会话记忆也就是当前对话窗口里正在讨论的内容它的特点是生命周期极短对话结束就消失。第二层是项目记忆指这个仓库里所有需要被理解的约定、规则、架构决策和运行方式它的生命周期和项目本身一样长。第三层是长期偏好记忆比如你个人或团队写代码的习惯——喜欢用类型注解、讨厌链式调用、测试必须走某个框架——这些偏好跨越项目属于人的稳定特征。在无状态架构下第一层几乎完全靠提示词支撑第三层几乎完全不存在第二层则被彻底浪费——项目里明明有README、有架构文档、有代码注释模型却很难把它们当作“记忆”来系统性地利用。记忆工程的本质就是把第二层和第三层从“隐含信息”变成“显式文件”让AI在每次启动项目时都能像新入职员工翻看入职手册一样先读一遍再开始干活。3.2 项目里本来就有一座记忆金矿只是没有被结构化大多数项目的文档其实是存在的只是形态不适合AI读取。README往往写得面向用户讲的是“这个产品能干什么”而不是“这个代码库该怎么被修改”架构文档要么严重过时要么位于几层目录之下AI根本不知道要去看真正的编码约定散落在各个文件的开头注释、代码评审的讨论记录、以及老员工的脑子里。做记忆工程的第一步就是把这些散落的记忆重新收集、整理并结构化。比如把“这个项目不允许用全局单例”这种只在评审中被口头提起的规则明确写进文档把“模块间的依赖方向必须从采集层指向转换层再指向写入层”这种架构约束用一段独立的说明文字固化下来。这些内容本身不复杂但把它们从隐性变为显式AI才可能读到。3.3 声明式配置在软件开发里的历史经验让约定可见、可审计、可继承有一点让我特别感慨软件开发领域其实早就经历过一轮“从对话到声明”的范式转换。早年间代码风格和构建约定靠口头传达新人问老人老人翻翻自己的编辑器配置后来大家发明了.editorconfig、.eslintrc、.prettierrc这样的文件把风格约定一笔一画地写成配置谁进项目都能直接加载不用再靠“老人口述历史”。这类声明式配置解决了三个问题可见性——约定不再是口头知识而是文件里的明文可审计性——任何人可以打开文件检查约定是否合理、是否过时可继承性——新成员、新工具、新环境都能通过读取同一个配置文件获得一致的起点。AGENTS.md在这轮AI编码的语境里扮演的正是同一个角色它不是给编译器看的而是给AI编码助手看的行为配置。理解了这层历史映射你就会明白为什么这件事如此值得做——本质上我们是在把“人与AI协作的隐性约定”变成“项目里的一份显式契约”。4. AGENTS.md 是什么以及它改变了什么面向AI的项目说明书4.1 一个文件解决“项目如何被AI理解”的问题AGENTS.md的具体形式很简单放在仓库根目录或者docs目录下的一个Markdown文件AI编码工具在启动时会自动读取它作为理解项目、调整自身行为的基础上下文。它不替代任何代码不包含逻辑只包含描述、规则和指引。用我自己的话定义它是“给AI看的项目入职手册”。这个文件最核心的价值是改变了AI读取项目的顺序和优先级。如果没有它编码助手面对一个新仓库时只能摸黑探索先扫一遍目录结构猜哪个文件是入口再去读几个看起来相关的模块至于项目约定完全靠碰运气。而有了它AI会先获得一份全局视图这个项目是干什么的、分哪些模块、使用什么技术栈、有哪些明确的“能做”和“不能做”、测试怎么跑、任务通常按什么流程来。这些内容相当于赛道地图让AI从一开始就不容易跑偏。4.2 AGENTS.md 与 README、架构文档的定位差异在我分享这个做法时常被问到的一句话是“这跟好好维护README有什么区别”我一开始也觉得只是多此一举但反复对比之后发现两者的受众和写作目标完全不同。README是给人看的核心目标是“让读者理解并愿意使用这个项目”所以它天然倾向介绍功能、展示优点很少会写“禁用全局变量”或“测试超时时间不能超过30秒”这类面向开发过程的规定。而AGENTS.md的核心目标是“约束AI的行为”它只需要关心模型在修改代码时应该掌握的工作规则不需要介绍产品的用户价值。还有一个经常被忽视的区别README的结构由维护者个人喜好决定而AGENTS.md可以设计成“指令友好”的结构——用短句、用列表、用明确的祈使句。因为AI对模糊的语言理解得不如人类准确写“尽量保持代码整洁”远不如写“新增函数必须有类型注解且行数不超过60行”这样的具体规则更有效。一个是说明书一个是操作手册用途不同写法和详略也就完全不同。4.3 可以写进AGENTS.md的内容清单根据我自己的实践我把适合写进AGENTS.md的内容归纳成六类每类都有典型例子分类目的典型示例项目概述让AI快速理解项目性质这是一个将数据从数据库同步到数据仓库的命令行工具采用Python 3.11技术栈与依赖避免AI引入错误技术方案异步网络库使用 httpx不允许改为 requests模块结构明确系统边界与依赖方向转换层不得直接依赖采集层内部实现编码规范统一代码风格减少返工所有公共函数必须写类型注解和 docstring构建与测试让AI能够验证自身修改测试命令为 poetry run pytest不得跳过任何用例工作流约束定义AI的默认行为路径修改任何接口前必须先更新对应测试禁止批量格式化我见过有人把业务领域知识也写进去比如字段映射规则、数据质量校验标准之类的。这种内容是否适合放进AGENTS.md取决于文件长度。我倾向于保持AGENTS.md短小精悍专门管AI的“行为规范”而领域知识可以放在单独的文档里用一句“详细规则见># AGENTS.md ## 项目概述 这是一个把业务库数据同步到数据仓库的命令行工具。 目标用户是数据团队运行环境是 Linux CI 和开发机macOS。 当前版本重点增量同步稳定性。 ## 技术栈与命令 - Python 3.11 Poetry 管理依赖 - Web 框架无纯 CLI - 网络请求httpx - 数据库SQLAlchemy 2.x查询统一走 ORM - 调度APScheduler仅用于本地定时演示正式调度交给外部编排 常用命令 - poetry run python -m sync_tool.cli run - poetry run pytest tests/ - poetry run mypy sync_tool/ ## 代码结构与依赖方向 - 采集collectors/→ 转换transformers/→ 写入writers/ - 禁止跨层反向依赖collectors 不得 import transformers 的函数 - 公共模型放 models/各层之间只允许通过 models 传递数据 ## 编码规范 - 所有公共函数必须有类型注解和 docstring - 函数尽量保持单职责单函数体不超过 60 行 - 异常必须声明可预期的异常类型不允许裸 except - 调试用的 print 必须删除日志统一使用 logging ## 测试要求 - 每次修改必须保证 tests/ 全量通过 - 新增转换规则时必须同时新增或更新对应测试用例 - 禁止为了通过测试而修改断言逻辑除非需求本身变了 ## 工作流约定 - 先读 README.md 和 docs/architecture.md再开始改代码 - 涉及接口变更时优先搜索所有调用方逐个说明影响 - 不要主动重构无关代码在任务执行前声明关注范围 - 遇到不确定的业务规则在 docs/business-rules.md 中查找找不到就向用户确认5.2 逐段解读每一行都是给AI的行为约束第一段的“项目概述”写得很克制只有三行。这是故意的。AI不善于区分“重要”和“次要”如果你把产品的来龙去脉全部堆进去它反而会迷失重点。我只保留了最关键的定位信息这是一个CLI工具和最需要被持续记住的目标当前关注增量同步稳定性。“技术栈与命令”这段主要解决AI爱“自由发挥”的问题。过去它经常在场景里擅自引入新依赖比如明明项目用Poetry管理它会在某个建议里让你装pip包。现在这些都被明确锁死了。同时写明“常用命令”是效果极佳的约束——AI在修改代码后不再问你“怎么验证”它会自己去搜索是否有对应测试命令并主动执行。“代码结构与依赖方向”是我最看重的一段。它对AI的意义相当于给一个新员工画了一张不准越界的部门架构图。没有这段时AI经常写出跨层调用的代码比如在采集层里直接调用转换层的内部函数有了这段它至少会先检查一下自己写的import是否违反方向约束。“编码规范”和“测试要求”两段要避免写得太抽象。我刚写第一版时用了“保持代码质量”“要有良好的可维护性”这种说法结果毫无效果——因为这些词无法被验证。后来全部改成可验证的量化标准60行、必须有类型注解、必须跑全量测试。AI本质上是一个服从指令的系统指令越具体执行结果越好。最后一段“工作流约定”是经验之谈。我发现AI最常见的毛病之一是在实现需求时顺手重构了周边代码导致diff里混入大量无关改动。“不要主动重构无关代码”加上“在任务执行前声明关注范围”这两句能显著减少这类问题。另外“先读README和架构文档再动手”这类顺序指令也要以显式方式写进文件里否则AI肯定会跳过这个步骤。5.3 维护节奏与代码一起Review写了AGENTS.md之后很多人会把它当作一个一次性产物写完就再也不碰。这是错误的。它和所有配置文件一样会随着项目演化而失效。我现在的做法是把它纳入代码评审流程任何一次涉及架构调整、依赖变更、测试策略改变的需求都必须顺带检查AGENTS.md是否需要同步更新。另外我还保留了一个小习惯每隔一两个月我会抽查一次AI的实际行为看它有没有“违反”AGENTS.md里的规则。如果有不一定是AI的问题反而可能是我的声明写得不够明确。比如早期我写“避免使用全局状态”AI仍然偶尔会用全局变量因为“避免”不是一个可执行的语义我改成“模块内禁止出现模块级可变变量”效果立刻好了很多。AGENTS.md与其说是一纸命令不如说是一面镜子——AI执行得不到位时先回头看看自己的描述是否足够精确。6. 用了一个月之后的真实体验与仍然存在的坑6.1 让人惊喜的三件事第一个明显的改善是“抗遗忘”。以前AI在同一会话里隔了几十条消息之后行为就开始漂移现在有了AGENTS.md做持续锚点即使对话很长它也倾向于回到文件里的约定上。尤其是我写入了“先读README和架构文档再动手”之后它每次都能给出更贴合项目现状的方案。第二个改善是“换窗口不换人设”。之前换一个新对话我需要把项目背景重新讲一遍现在只要告诉它“去项目根目录看看AGENTS.md”它就能恢复几乎一致的上下文理解。团队里其他同事使用同一个仓库时也获得了相同的起点——AGENTS.md实际上把“个人经验”上升成了“团队资产”。第三个改善是代码风格显著稳定。我自己写代码的风格是短函数、强类型、显式异常。以前让AI写代码经常得到几百行的长函数和一大堆裸异常。把规范量化写入AGENTS.md之后新生成的代码基本一次到位Review阶段需要挑的毛病少了很多。6.2 过度配置与文档腐化两个踩得最重的坑第一个坑是过度配置。我一度追求“更全面”把几乎所有的代码规范都写了进去包括一些极端场景下的避坑建议整个文件达到两百多行。实际使用之后发现效果反而变差了——AI在长文件里丢失了重点它记住了那些花哨的边缘规则却忽略了“依赖方向”和“测试全量通过”这些核心约束。后来我把文件砍到六十行左右只保留对当前阶段最重要的信息效果回升明显。这说明AGENTS.md不是越全越好而是一份“当前最重要约定”的浓缩。第二个坑是文档腐化。项目演进后旧的约束没有及时更新。比如我们已经把同步调度完全交给了外部编排AGENTS.md里还写着“APScheduler仅用于本地演示”结果AI每次看到调度相关的需求都试图往本地推APScheduler方案。发现问题后我把过时内容删除、更新了描述才算恢复正确。这提醒我AGENTS.md一旦失真危害比没有它更大因为AI会非常自信地照着过时规则行动。6.3 下一步演进规则目录化与AI自维护经历了这两个坑之后我意识到单文件方案在项目复杂度进一步上升时会遇到管理瓶颈。下一步我在尝试的方向是把AGENTS.md做成一个索引具体的详细规则拆到rules/目录下按主题分文件存放例如rules/backend.md、rules/data.testing.md。这样的好处是每份规则文件短小、聚焦、容易更新AGENTS.md本身保留最关键的引导信息。另一个更进阶的想法是让AI自动维护这份文件。既然AI能读AGENTS.md理论上它也能在完成重大改动后主动提出“AGENTS.md需要更新”。目前这个能力还不稳定需要人工确认但它代表了一个更有意思的方向记忆工程不应该只是人类写给AI的说明书更应该是人机协作过程中共同演化出来的活文档。我甚至开始尝试在每次较大功能合并前让AI先给出AGENTS.md的改动提案再随代码一起评审。这比我一个人记住去更新要可靠得多。我自己现在的习惯是新建任何仓库的第一天就把AGENTS.md的骨架放进去哪怕只有五条规则。它不一定能让AI变得更聪明但它能让AI的行为变得稳定、可预测、可审阅。这种稳定性在AI编程里比偶发的天才表现值钱得多。如果你也在被编码助手的“失忆”困扰不妨从一份几十行的AGENTS.md开始把记忆从对话框里搬到仓库里——这件事值得做而且越早做收益越大。