你有没有遇到这种情况同一个问题AI 编程助手第一次回答得头头是道第二次再问就仿佛失忆同一个项目换一个 AI 工具打开对方连项目是干什么的都不知道好不容易把需求聊清楚了过了两天 AI 又把之前约定好的架构方案忘得一干二净。这就是无状态模型的典型症状。大多数生成式 AI 的底层模型本身是没有记忆的它只负责把你当前输入的内容映射成输出对话历史、项目背景、技术决策这些信息都得靠工程手段去补齐。过去几年我们主要靠“把历史塞进上下文窗口”这种笨办法来对付但随着项目复杂度上升、多人协作参与这种方式的瓶颈越来越明显。AI 编程范式正在转换。以 AGENTS.md 为代表的声明式记忆文件正在成为新的主流做法——把项目知识、约束、技术决策固化到项目仓库里让 AI 在每次介入时都能快速加载上下文而不是依赖一段时过境迁的聊天记录。这篇文章我会从无状态模型的问题本质说起拆解 Memory 工程的分层设计再手把手讲清楚 AGENTS.md 该怎么写、怎么组织、怎么落地最后把我踩过的坑和排查经验一并分享。如果你正在用 AI 辅助开发或者想在企业里推广 AI 编程实践这篇文章适合你。我会尽量少讲空泛的概念多给可以直接抄走的东西。1. 为什么“无状态”成了 AI 编程的头号瓶颈很多开发者第一次被 AI 编程工具惊艳到是那种“我把需求一贴代码就出来了”的体验。但用了一阵子之后感受会逐渐从兴奋变成拧巴明明上下文里贴过的东西AI 还是会忘明明代码里写得很清楚AI 还是会按自己的理解瞎写。问题的根源不在模型能力而在于模型天生就不存在“记忆”这个模块。1.1 大模型的信息处理机制与记忆缺失大模型本质上是一个超大规模的条件概率计算器。你给它输入一段 token 序列它预测下一个最有可能出现的 token然后一个接一个地生成。这个过程中模型能利用的全部信息就是当前输入内容加上它内部参数里存储的“世界知识”。当你关闭一次会话、结束一个任务模型立刻回到一张白纸的状态——不是它不想记住是它的结构里根本没有让你“记住”的接口。很多人觉得“AI 有记忆”是因为聊天工具把历史消息都带上了。但这其实是产品的交互层做了手脚每次提问时把之前的对话记录重新拼接到输入里一起发给模型。所以你感觉到的“记忆”本质是上下文长度的不断膨胀。模型本身依然是无状态的。1.2 上下文窗口的物理边界与隐性成本既然记忆靠“塞”来实现那就天然受到上下文的物理限制。当前主流模型的上下文窗口从 128K 到 1M 不等听起来很大但实际可用空间远没有这么充裕。真实项目里一个稍大的代码库可能有数万甚至数十万个文件把全部代码塞进上下文显然不现实。即便只塞关键部分也会带来三个具体问题token 费用快速上升、响应时间拉长、模型注意力被海量无关信息稀释。提示不少人以为“上下文越大越好”实际操作中上下文过长时模型的注意力会明显“掉焦”。你把 200K 的无关代码塞进去模型很可能记不住开头几轮对话里约定的技术方案因为注意力被后面大量的代码片段稀释了。1.3 会话记忆不可复用的工程困境会话记忆还带来一个工程上很头疼的问题不可复用。A 同学用了一晚上的对话把项目背景、技术选型、架构约束全部聊清楚了但这段记忆只存在于他的会话窗口里。第二天 B 同学打开同一个项目AI 又是一片空白。这意味着每一次新会话、每一个新协作者、每一次 CI 里的自动化调用都得从头开始“调教”AI。项目里的隐性知识——为什么用 A 方案不用 B 方案、哪些目录禁止改动、命名规范是什么——全部散落在聊天记录里既没人整理也没法传播。这个问题的解法思路其实在软件工程里早就存在把会变化、会影响行为的信息从进程内部挪到外部存储里。AI 编程也一样Memory 工程就是在做这件事。2. Memory 工程分层解构 AI 的“记忆系统”Memory 工程并不是一个玄学概念它的目标非常朴素让 AI 在合适的时间拿到合适的历史信息。要达到这个目标不能把所有东西一股脑塞进去而要做分层设计。2.1 记忆的三个层次短期、工作、长期我在实际项目中把 AI 记忆分成三层分别对应不同的生命周期第一层是短期记忆也就是会话上下文。它存在于一次对话中负责维持当前任务的连贯性。这一层的容量最小控制手段也最直接——减少废话只保留关键信息超出窗口就做摘要压缩。第二层是工作记忆对应的是项目级别的知识。比如项目的目录结构、代码规范、核心模块说明、当前迭代的目标。这一层需要有载体而且载体必须能跨会话存在。过去业界常用的做法是写一个 CLAUDE.md、.cursorrules 之类的单文件但这些文件往往越写越长最后变成一坨没人维护的“死文档”。第三层是长期记忆对应的是跨项目的个人/团队知识沉淀。比如团队的技术决策记录ADR、领域术语表、公共的基础设施说明。这一层和项目代码解耦适合放在团队知识库里按需检索加载。这三层不是孤立的它们之间应该形成一个滚动机制对话中有价值的信息经过沉淀进入工作记忆项目实践中验证过的决策上升为长期记忆长期记忆中的通用内容在新建项目时填充进工作记忆作为初始上下文。2.2 检索增强还是全量注入确定了分层结构接下来要回答一个关键问题这些记忆怎么被 AI 使用一种方式是全量注入把所有记忆文件在每次对话时都添加到上下文中。优点是实现简单缺点是 token 消耗大、上下文迅速膨胀。一旦记忆文件总量超过某个阈值还会挤占代码内容的上下文空间。另一种方式是检索增强也就是按需拉取。AI 根据当前用户输入和文件状态判断需要哪些记忆片段然后去读取对应文件。这种方式对工程能力要求较高但效果好得多。现在主流的 AI IDE 代理比如能自动操作文件系统的编程智能体都已经内置了这种能力它会先扫一眼项目目录读取 AGENTS.md再根据任务决定要不要深入某个子目录的记忆文件。实用的做法是两者结合核心约束文件全量注入保证不跑偏细节知识按需检索保证不膨胀。AGENTS.md 作为核心约束文件全量注入而它指向的深层记忆文件只在需要时读取。2.3 记忆更新的闭环没有写回的缓存都是死缓存分层设计和检索机制说完了还有最重要的一环——记忆的更新。如果没有写回机制记忆就只会腐烂。什么叫写回就是 AI 在完成一次有意义的任务后主动把关键信息写到记忆文件里。比如 AI 帮你引入了一套新的测试框架它应该顺手更新 AGENTS.md 里的“当前技术栈”段落并在 ADR 目录下记录这次决策的原因。这样下次任何协作者打开项目都能知道“测试框架是这套是因为原先那套不支持参数化”。注意AI 的写入行为需要约束。如果不加约束它可能把不该写的东西写进文件里或者在代码里乱加注释。所以必须声明清楚哪些文件 AI 可以写、哪些文件任何人都不许改、写更新时要不要附带理由说明。做好这三层设计之后才有资格聊 AGENTS.md 的写法。它不是一个孤立的文件而是整个 Memory 工程体系里的“入口索引”和“总纲”。3. 为什么是 AGENTS.md从命令式到声明式的范式转换AGENTS.md 这个文件本身并不神奇它只是一个 Markdown 文档放在项目根目录AI 编程工具会自动读取。真正值得琢磨的是它代表的范式转变从“命令 AI 怎么做”转向“声明项目是什么”和“让 AI 自己推导怎么做”。3.1 README 解决“人”的问题AGENTS.md 解决“AI”的问题很多团队的第一反应是我明明有 README里面写了项目介绍、安装方式、使用说明为什么 AI 还要单独读一个 AGENTS.md原因很简单两者面向的读者不同。README 面向人类开发者和使用者强调的是“项目能做什么、怎么跑起来”AGENTS.md 面向 AI 代理和编程智能体强调的是“这个项目的边界在哪里、有什么约定、哪些操作禁止”。换句话说README 是门面AGENTS.md 是施工规范。举个例子你的 README 里可能写了“本项目使用 pnpm”这句话人类看了就明白了。但 AI 在尝试安装依赖时可能依然会使用 npm——因为很多优秀项目的 README 没写这句话模型根据训练数据里的“多数派”行为走了默认路线。而 AGENTS.md 里清晰声明一句“Always use pnpm for package management”AI 的行为就会被约束住。3.2 声明式配置的三个典型优势为什么说 AGENTS.md 是“声明式”而非“命令式”因为文件里的内容绝大部分是描述性的项目是什么、在哪个目录做什么事、什么事情绝对不允许。AI 读完之后自行推理出具体怎么做。这带来了三个实打实的优势。第一个优势是稳定性。命令式的提示词依赖“这条指令被完整执行”一旦指令里描述的步骤和实际代码库状态对不上AI 就会卡住或者瞎做。而声明式描述的是目标和约束AI 有更大的自主空间去适配实际情况反而更不容易翻车。第二个优势是可维护性。AGENTS.md 本质上是一份文档不是一段逻辑。修改它不需要理解代码不需要考虑执行顺序团队里的任何人都能轻松维护。即使不太熟悉 AI 的开发者也敢改它因为改的是一段人话不是一套规则引擎。第三个优势是跨工具兼容。目前主流的 AI 编程工具都已经或正在支持读取 AGENTS.md这意味着它成为了一个半标准的约定。你不再需要为 IDE 插件、命令行工具、CI 代理分别维护不同的提示词文件一份文档各处通用。3.3 从提示工程到上下文工程思维惯性要换很多从提示工程时代过来的开发者写 AGENTS.md 时容易犯一个毛病把文件写得像一套“万能咒语”试图覆盖所有可能的错误行为。这种思路的失败几乎是注定的——AI 不会因为你多写了“不要乱改代码”就真的不乱改这种模糊的否定指令反而会稀释文件的整体约束力。正确的姿势是“上下文设计”思维你想清楚在什么样的上下文里AI 最可能做出正确行为然后把 AGENTS.md 设计成能引导它进入那类上下文的东西。你不是在写指令你是在设计信息环境。举例来说与其写“修改代码时不要破坏其他功能”不如在文件里给出一段“受影响分析模板”要求 AI 在改动前列出受影响的文件清单和风险点。后者不是否定式命令而是一个工作流约束AI 自然会按最小风险路径行事。4. 实操落地从零搭建一套 AGENTS.md 记忆体系概念聊透了接下来是真正的干货。我会用一个模拟项目 X 来演示它是一个典型的后端服务项目包含 API 模块、数据库迁移脚本、定时任务还有一套内部的前端控制台。这个结构在真实工作中很常见——足够复杂足以展示 AGENTS.md 该覆盖哪些内容。4.1 目录结构与文件组织先看一套我经过多次迭代后沉淀下来的模板目录project-x/ ├── AGENTS.md # 总纲入口索引 全局约束 ├── docs/ │ └── agents/ │ ├── api.md # API 模块专属记忆 │ ├── database.md # 数据库与迁移规则 │ └── console.md # 前端控制台约定 └── memory/ └── decisions/ ├── 001-use-drizzle.md # 决策记录为什么用 Drizzle └── 002-api-versioning.mdAGENTS.md 写在根目录承担“入口索引”职责。它的特殊之处在于不要太长我的经验是控制在 60 到 120 行以内。太短了覆盖不住核心信息太长了 AI 读取时注意力会被稀释而且维护成本会飙升。注意项目根目录下不要再放 CLAUDE.md、.cursorrules、rules.md 之类的文件。多个配置文件同时存在时不同工具读取的文件不一样同一个项目在不同工具里表现不一致排查起来极其痛苦。统一收敛到 AGENTS.md 一个入口。4.2 AGENTS.md 核心内容模块详解下面是一份精简但完整的示例我会逐段说明为什么这么写# Project X — AI Agent Guidelines ## Project Overview Project X is a backend-as-a-service platform. It exposes a REST API for client applications, runs scheduled background jobs, and ships with an internal admin dashboard. ## Tech Stack - Backend: Node.js, TypeScript, Fastify - Database: PostgreSQL, Drizzle ORM - Frontend: React, Vite, Tailwind - Package manager: pnpm ## Repository Architecture - src/api/ — REST API route definitions. Controllers are thin; business logic lives in src/services/. - src/services/ — Business logic layer. All nontrivial behavior must be in this layer, not in controllers. - src/jobs/ — Scheduled jobs, triggered by a cron service. - console/ — Admin frontend. Keep it separate and rarely touch it unless the task is explicitly about the console. - db/migrations/ — SQL migrations generated via drizzle-kit. Never edit files manually; regenerate. ## Critical Rules - **Never modify db/migrations/ directly.** Change the schema in src/db/schema.ts and run pnpm db:generate. - **Never bump a dependency without adding an ADR entry.** - **API responses must follow the standard error envelope** defined in src/lib/error.ts. Do not invent new error formats. - **Do not use any in TypeScript unless there is a comment explaining why.** The codebase has strict mode enabled. ## Workflow Preferences - Before making cross-file changes, create a short impact plan: list files to change, expected risks, affected tests. - Run pnpm test after every change. Fix failures before proceeding. - Keep changes in small chunks. Prefer 3 commit series (feature, tests, docs) over one giant commit. - When unsure about a design decision, read memory/decisions/ first; if no precedent exists, start an ADR. ## Memory Map - API internals, route conventions → docs/agents/api.md - Database schema, migration workflow → docs/agents/database.md - Console UI conventions → docs/agents/console.md - Past decisions → memory/decisions/ ## Write Permissions AI agent may write to: - docs/agents/*.md (keep existing style) - memory/decisions/ (with date-stamped filename) - AGENTS.md itself only when the change is directly required by the task Agent must NOT modify: - CHANGELOG.md - files under vendor/ - any file outside the repository root这段内容看着不长但每一块都有明确的设计意图。Project Overview要在三行内让 AI 知道这个项目是干嘛的。很多开发者不重视这一小段其实它直接影响 AI 的决策质量——如果 AI 不知道这是一个 BaaS 平台它可能会按普通的单体应用思路去处理问题。Tech Stack里明确写“pnpm”而不是泛泛地写“package manager”。大多数 AI 基础模型会被训练数据里的高频行为带跑默认用 npm你如果不明确写出来就等着它自作主张。Critical Rules是全文件的灵魂。它必须只包含“违反了一定会出问题”的规则而不是一堆“最好这样”的建议。规则多了AI 会当成噪音反而记不住真正重要的。Workflow Preferences这一段看似可有可无实际效果极大。它把 AI 的行为模式从“一股脑生成代码”改成了“先列计划再分步执行”。这一步能把大改翻车率降低一半以上。Memory Map是索引。它告诉 AI 去哪里找更详细的信息。没有这一段深层记忆文件就是死文档。Write Permissions是我的核心心得。没有这个区块时AI 在高自由度环境下容易“过度主动”把不该动的文件改了。加了写入权限约束后AI 的行为边界清晰很多。4.3 深层记忆文件怎么写与 AGENTS.md 的配合节奏AGENTS.md 只是总纲项目里还有很多细节不适合放在根文件里——比如 API 路由的命名规范可能需要一百行才写得清楚放在总纲里纯属浪费。这些内容应该下沉到 docs/agents/ 对应的文件里。来看 docs/agents/api.md 的节选# API Module Conventions ## Route Registration All routes must be registered in src/api/routes/index.ts using the registerRoutes helper. Do not create standalone route files without adding them to the index. ## Response Envelope Every endpoint returns: { code: 0, data: ..., message: } For errors, use code ! 0, and message must be human-readable. ## Pagination List endpoints accept page and page_size query params, default page1, page_size20. Max page_size is 100. Each list response must include a total field. ## Naming Style - Route files: plural noun, e.g. users.ts, orders.ts - Controller methods: get{Resource}, create{Resource} etc.这文件里没有任何“如何写代码”的教学内容全部是项目特定的约定。AGENTS.md 负责“知道在哪个文件里找规矩”具体文件负责“告诉你这个模块的规矩是什么”。当 AI 接到一个“添加用户列表接口分页功能”的任务时它会先读到 AGENTS.md 里的 Memory Map意识到需要看 api.md然后按 api.md 里的约定开发。这就是“总纲全量注入 细节按需检索”的完整闭环。4.4 决策记录ADR长期记忆的落地形式很多团队花时间建立 Memory 工程却发现三个月后记忆文件就开始腐烂。腐烂的原因是只记录了“当前状态”没记录“为什么变成当前状态”。要解决这个问题我的建议是引入轻量级 ADR。ADR 文件不需要很长三五段话就够# 002: Use Drizzle ORM instead of Prisma Status: Accepted Context: Prisma 4 had issues with our multi-schema setup on PostgreSQL 15, generating wrong foreign key relations in two migrations. We also needed raw SQL escape hatches for a few complex queries. Decision: We migrated to Drizzle ORM. Drizzle supports multi-schema migrations out of the box, gives us full TypeScript inference, and provides a db.push workflow that matches our iterate-fast style. Consequences: Existing Prisma migrations were rewritten. A few queries were rewritten to use db.execute with raw SQL. The migration workflow changed; the new one is described in docs/agents/database.md.有了这样的记录后续 AI 在遇到“要不要换回 Prisma”这种讨论时可以直接查 ADR 拿到完整上下文而不需要重演一遍当初的踩坑过程。5. Memory 工程实战中的坑与排查技巧理论和模板都给了最后这部分是我最想聊的——真实项目中你会碰到的那些破事。每一条都是我实际踩过、摔过、又爬出来的。5.1 AGENTS.md 过长导致约束失效我见过最离谱的一个 AGENTS.md 有 700 多行团队把所有的代码规范、历史决策、Todo List 全塞进去了。结果就是 AI 每次读取它要消耗大量 token更糟的是模型在长文档里寻找关键规则的准确率急剧下降——它能记住中间的几段却记不住文件开头和结尾的内容。排查看一眼你就明白了根目录文件只写全局约束和索引具体规范下放到子文件。如果 AGENTS.md 超过 150 行先问自己一个问题——这内容是不是本来就该放到下的深层文件里5.2 规则写得模糊AI 表面遵守实则偏离很多人在 AGENTS.md 里写“using conventional commits”或者“write clean code”这种表述是没有约束力的。模型不知道你的团队对 conventional commits 的定义不知道你的 clean code 标准是什么。排查和修正把每一条规则都改成可以被机器验证的表述。不要写“code should be formatted”要写“runpnpm formatbefore submitting”;不要写“avoid any type”要写“do not useanyunless a comment explains why”。规则验证成本越低AI 遵守意愿越高。5.3 与 README、代码注释互相矛盾这个坑的隐蔽性最强你有了 AGENTS.md但项目里还有旧的 README、有大量历史遗留的代码注释它们提供的信息互相矛盾。AI 读取时无法判断谁更权威行为就会变得不可预测。解决方案是在 AGENTS.md 里加一条“信息优先级”声明## Information Hierarchy When instructions in this file conflict with README or inline comments, this file takes precedence. If AGENTS.md is unclear, prefer code over documentation — code is a better source of truth for what actually runs.这一条一旦加进去AI 在矛盾面前有了明确的出路比你反复调整描述词管用得多。5.4 AI 不主动读取深层记忆文件有朋友反馈我的 AGENTS.md 写得很好深层文件也写了但 AI 干活时完全不看深层文件。排查后发现原因极可能是“深层文件名太模糊”。比如docs/agents/info.md——AI 无法从文件名判断这个文件对自己有没有价值自然不会去读。把文件名改成带明确语义的比如docs/agents/database-migration-guide.md、docs/agents/api-response-envelope.md。同时确保 AGENTS.md 的 Memory Map 里加上一句“Read this file before touching any migration code”给 AI 提供明确的行为触发条件。5.5 团队协作中的记忆同步问题最后是组织层面的问题AGENTS.md 由谁维护、多久更新一次、怎么保证质量和时效性我的经验是把 AGENTS.md 的维护纳入 code review 流程——任何涉及架构变更、依赖升级、目录调整的 PR必须同步修改 AGENTS.md。换句话说文档变更和代码变更一起 review不允许单独一个。这条规则执行起来需要一点意志力但坚持两三个迭代之后团队的 AI 协作效率会有质的提升。写在最后回到开头那句话无状态模型是这个时代的底色但不是你的宿命。模型记不住你的项目但项目文件可以替它记住。从无状态模型到 AGENTS.md 声明式配置转变的实质是重新分配记忆的载体——把“记在模型的隐藏状态里”改为“记在项目仓库的显式文件里”。这意味着 AI 编程的可靠性、可复审性、协作性都上了一个台阶。我已经在自己的项目和几个合作团队里验证了这套做法的稳定性如果你正准备开始尝试建议先挑一个小项目练手把 AGENTS.md 写出来、让 AI 跑一个真实任务、观察它去哪里找信息、在哪里掉链子然后持续迭代这个文件。文件是死的迭代的过程才是活的。