1. 从无状态到有状态AI 编程范式转换的底层逻辑1.1 为什么无状态模型是当前 AI 编程的最大瓶颈用过 AI 辅助编程的人都有一个共同感受每次开新对话就像换了一个失忆的搭档。你昨天刚跟它讲清楚项目用的是什么框架、目录结构怎么组织、命名规范是什么今天开个新窗口它又变回一张白纸你得从头再讲一遍。这不是模型不够聪明而是当前主流大模型 API 的调用方式决定的——每次请求都是独立的模型本身不保存任何跨会话的状态。这个特性在简单场景下问题不大比如你只是让它写一个排序算法、解释一段正则表达式一次对话就能搞定。但一旦进入真实项目开发问题就暴露了。一个中型项目动辄几十个模块、上百个文件涉及特定的架构约定、错误处理模式、日志规范、测试策略。你每次让 AI 帮你写一个新模块都得把相关的上下文重新喂一遍token 消耗巨大不说还经常因为上下文窗口限制而丢三落四。我自己的体验是在一个前端项目里让 AI 帮忙写一个表单组件它默认用了受控组件写法但我们项目统一用的是非受控加 ref 的方案。我没提它就按自己的习惯来。等我发现不对再纠正它改了但下一个组件它又忘了。这种反复纠正的成本累积起来非常可观。所以核心矛盾在于AI 编程的效率瓶颈已经从“模型能力不足”转移到了“上下文管理低效”。模型本身能写出高质量代码但它不知道你的项目长什么样、有什么约定、之前做过什么决策。每次都要靠人肉去补全这些信息本质上是在用人的记忆力弥补模型的失忆。1.2 Memory 工程要解决的核心问题到底是什么Memory 工程这个词听起来很玄但拆开看其实很朴素让 AI 在多次交互之间保持对项目上下文的一致认知。它要解决的不是“让模型更聪明”而是“让模型更懂你”。具体来说Memory 工程要处理三类信息。第一类是静态约定比如项目的技术栈、目录结构、代码风格、命名规范这些在项目生命周期内基本不变。第二类是动态状态比如当前正在开发哪个功能、上次对话中做了什么决策、有哪些待办事项这些会随着开发进度变化。第三类是历史决策记录比如为什么选了这个方案而不是那个、踩过哪些坑、有哪些已知问题这些是项目演进过程中积累的隐性知识。传统做法是把这些信息塞进每次请求的 prompt 里但这样做有几个致命问题。一是 token 成本随信息量线性增长二是上下文窗口有硬上限三是信息多了之后模型反而抓不住重点容易“迷失在中间”。所以 Memory 工程的核心挑战不是“能不能存”而是“怎么存、怎么取、怎么让模型在需要的时候恰好看到需要的信息”。这就引出了声明式配置的思路。与其每次动态拼接上下文不如把项目的核心约定写成一个结构化的配置文件让 AI 在每次对话开始时自动加载。这个配置文件就是 AGENTS.md 这类方案的雏形。1.3 声明式配置为什么比命令式拼接更适合 AI 编程命令式拼接的思路是每次请求前用代码动态组装上下文把相关的文件内容、历史记录、约定说明拼成一个长字符串塞给模型。这种方式灵活但脆弱因为拼接逻辑本身需要维护而且很难保证每次都能拼出正确的上下文。声明式配置的思路是把“AI 需要知道什么”写成一个静态文件放在项目根目录AI 工具在启动时自动读取。这个文件用自然语言描述项目的关键信息不需要写代码来解析模型自己就能理解。打个比方命令式拼接像是你每次出门前都要手动检查钱包、钥匙、手机带没带声明式配置像是你在门口贴了一张清单出门前看一眼就行。前者依赖你的记忆力和执行力后者依赖清单本身的完整性。对于 AI 编程来说清单的维护成本远低于每次手动拼接而且不容易遗漏。更重要的是声明式配置让“项目知识”变成了一个可版本控制的文件。你可以把它提交到 Git 仓库团队成员共享同一份配置新人加入时 AI 也能立刻获得项目上下文。这就把原本散落在各人脑子里的隐性知识变成了团队共有的显性资产。2. AGENTS.md 的核心设计一份文件如何承载项目记忆2.1 AGENTS.md 应该包含哪些内容AGENTS.md 不是随便写写就行的它的内容质量直接决定了 AI 对项目的理解程度。根据我的实践经验一份有效的 AGENTS.md 至少应该覆盖以下几个维度。项目概览是必须放在最前面的。用三五句话说明这个项目是做什么的、面向什么用户、核心功能有哪些。这部分不需要太详细目的是让 AI 建立一个大致的认知框架知道自己在什么语境下工作。技术栈与工具链要列清楚。用什么语言、什么框架、什么构建工具、什么测试框架、什么包管理器。这些信息看起来基础但 AI 如果不知道就会按自己的默认习惯来。比如你不说用的是 pnpm它可能给你生成 npm 的命令你不说用的是 Vitest它可能给你写 Jest 的测试。目录结构说明是很多人容易忽略但极其重要的一部分。不需要列出每个文件但要说明主要目录的职责。比如src/components放通用组件、src/features放业务模块、src/lib放工具函数。这样 AI 在新建文件时就知道该放哪里而不是随便找个地方塞进去。代码规范与约定要写得具体。不要只说“遵循 ESLint 规则”而要说明关键约定比如“组件文件用 PascalCase 命名”、“工具函数用 camelCase”、“常量用 UPPER_SNAKE_CASE”、“每个导出函数必须有 JSDoc 注释”。越具体AI 越不容易跑偏。常用命令要列出来。开发服务器怎么启动、测试怎么跑、构建怎么执行、代码检查怎么做。这些命令 AI 在需要验证自己的改动时会用到提前告诉它能省很多来回。已知问题与注意事项是加分项。比如“这个模块依赖一个尚未稳定的第三方库升级时需谨慎”、“这个目录下的文件不要手动修改由代码生成”、“测试环境需要先启动本地数据库”。这些信息能帮 AI 避开很多坑。2.2 怎么写才能让 AI 真正读懂写 AGENTS.md 最大的误区是把它写成给人看的文档。人看文档可以跳读、可以脑补、可以根据经验填补空白但 AI 不行。AI 会逐字逐句地理解你写的内容你写得模糊它就理解得模糊。第一个原则是具体优于抽象。不要写“代码要整洁”要写“函数不超过 50 行参数不超过 4 个嵌套层级不超过 3 层”。不要写“遵循项目风格”要写“参考src/utils/format.ts中的写法”。具体的规则 AI 能执行抽象的规则 AI 只能猜。第二个原则是正面描述优于负面禁止。尽量告诉 AI“应该怎么做”而不是“不要怎么做”。因为负面指令需要 AI 先理解什么是不该做的再推导出该做什么多了一步推理容易出错。比如与其说“不要用 any 类型”不如说“所有变量和函数返回值必须有明确的类型标注”。第三个原则是结构化优于流水账。用标题分层、用列表罗列、用代码块展示示例。AI 对结构化信息的解析能力远强于大段散文。一份好的 AGENTS.md 应该像一份精心组织的 checklist而不是一篇随笔。第四个原则是控制篇幅。AGENTS.md 不是越长越好。太长了会占用宝贵的上下文窗口而且模型在长文本中容易丢失重点。我的经验是控制在 2000 字以内把最关键的信息写进去次要信息可以放在单独的文档里按需引用。2.3 一个可参考的 AGENTS.md 模板结构下面是我在实际项目中反复打磨出来的一个模板结构你可以直接拿去改。# 项目名称 ## 项目概览 一句话说明项目定位两三句话补充核心功能和目标用户。 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 状态管理Zustand - 样式Tailwind CSS - 测试Vitest Testing Library - 包管理pnpm ## 目录结构 - src/components/通用 UI 组件每个组件一个目录 - src/features/业务功能模块按领域划分 - src/lib/工具函数和第三方库封装 - src/hooks/自定义 React Hooks - src/types/全局类型定义 ## 代码规范 - 组件文件用 PascalCase工具文件用 camelCase - 每个导出函数必须有 JSDoc 注释 - 优先使用函数式组件和 Hooks - 样式统一用 Tailwind 类名不写独立 CSS 文件 - 所有异步操作必须有错误处理 ## 常用命令 - 开发pnpm dev - 测试pnpm test - 构建pnpm build - 检查pnpm lint ## 注意事项 - src/generated/ 下的文件由代码生成不要手动修改 - 新增依赖前先确认是否已有替代方案 - 提交前必须通过 lint 和测试这个模板的好处是信息密度高、结构清晰、AI 容易解析。你可以根据项目实际情况增删条目但建议保持这个骨架。3. 实操落地从零搭建一套 Memory 工程工作流3.1 环境准备与工具选型要落地这套方案你需要一个支持读取项目配置文件的 AI 编程工具。目前主流的选择有几类一类是 IDE 插件形态的比如在 VS Code 里运行的 AI 助手一类是命令行形态的比如在终端里交互的 AI 工具还有一类是独立编辑器形态的比如专门为 AI 编程设计的编辑器。选型的核心考量是是否支持自动读取项目根目录的配置文件。如果不支持你就得每次手动把配置内容粘贴到对话里那就失去了声明式配置的意义。我建议优先选择那些明确支持 AGENTS.md 或类似机制的方案这样配置一次就能长期生效。除了 AI 工具本身你还需要一个版本控制工具来管理 AGENTS.md 的变更。Git 是标配没什么好说的。建议把 AGENTS.md 放在项目根目录和 README.md 平级这样既显眼又符合惯例。另外建议准备一个docs/目录用来存放更详细的文档。AGENTS.md 只放最核心的约定详细的架构说明、API 文档、部署流程可以放在docs/下在 AGENTS.md 里用链接引用。这样既保持了 AGENTS.md 的精简又不会丢失重要信息。3.2 第一步梳理项目现状并提取关键约定在写 AGENTS.md 之前先花半小时把项目现状梳理一遍。这一步很多人会跳过直接开始写结果写出来的东西要么遗漏关键信息要么包含大量无关内容。梳理的方法是打开项目根目录从入口文件开始沿着目录树走一遍。每看到一个目录问自己三个问题这个目录是干什么的AI 在什么情况下会往这里加文件加文件时有什么约定把答案记下来。然后看配置文件。package.json里的 scripts 和 dependencies、tsconfig.json里的编译选项、.eslintrc里的规则、vite.config.ts里的构建配置。这些文件里的信息很多可以直接提炼到 AGENTS.md 里。接着看代码风格。随便打开几个代表性文件观察命名习惯、注释风格、错误处理方式、测试写法。把这些观察总结成几条明确的规则。最后回忆一下过去踩过的坑。有没有因为 AI 不知道某个约定而写错代码的情况有没有某个模块特别容易出问题把这些经验也写进去。3.3 第二步编写并迭代 AGENTS.md第一版 AGENTS.md 不需要追求完美先把能想到的都写进去然后在实际使用中迭代。我的经验是第一版写完后用 AI 做几个真实任务观察它在哪些地方理解错了、哪些地方需要你额外解释。每次纠正后把对应的约定补充到 AGENTS.md 里。迭代的频率建议是项目初期每周更新一次稳定后每月更新一次。每次更新不需要大改补充几条规则、修正几处表述就行。关键是保持这个习惯让 AGENTS.md 始终反映项目的最新状态。有一个技巧是当你发现自己在对话中反复向 AI 解释同一个东西时就说明这个东西应该写进 AGENTS.md 了。比如你第三次告诉 AI“这个项目的 API 请求都要走src/lib/api.ts里的封装”那就别再口头说了写进配置文件。另一个技巧是让 AI 帮你写 AGENTS.md。你可以把项目结构贴给 AI让它根据观察生成一份初稿然后你再修改。这样能省不少力气而且 AI 可能会发现一些你忽略的细节。3.4 第三步验证配置效果并建立反馈循环写完 AGENTS.md 后怎么知道它有没有效果最直接的验证方法是开一个新对话让 AI 做一个需要项目上下文的任务看它是否需要你额外解释。如果它能直接按你的约定来说明配置生效了如果还需要你补充说明说明配置有遗漏。我通常会做三个测试。第一个是新建文件测试让 AI 在指定目录下创建一个新组件看它是否用了正确的命名、是否放了正确的位置、是否遵循了代码规范。第二个是修改测试让 AI 修改一个现有函数看它是否保持了原有的风格、是否更新了相关测试。第三个是查询测试问 AI 某个功能在哪里实现、某个约定是什么看它能否从 AGENTS.md 中找到答案。根据测试结果把遗漏的约定补进去把表述不清的地方改清楚。这个过程重复两三轮AGENTS.md 就基本稳定了。反馈循环的建立也很重要。建议在团队中指定一个人负责维护 AGENTS.md其他人发现 AI 理解偏差时向这个人反馈。或者更简单的方式是谁发现遗漏谁就补把 AGENTS.md 当成代码一样对待发现问题就提 PR 修改。4. 常见问题与排查技巧实录4.1 AGENTS.md 写了但 AI 不遵守怎么办这是最常见的问题。你明明写了“组件文件用 PascalCase”AI 还是给你生成了 camelCase 的文件名。遇到这种情况先别急着怀疑方案本身按下面的顺序排查。首先检查文件位置。AGENTS.md 必须放在项目根目录有些工具只认根目录下的文件放在子目录里不生效。其次检查文件名。不同工具对配置文件的命名要求不同有的认 AGENTS.md有的认 .ai-config有的认其他名字。确认你用的工具支持哪种命名。然后检查内容表述。如果规则写得太模糊AI 可能理解不了。比如“遵循项目风格”这种表述AI 根本不知道项目风格是什么。改成具体的规则比如“组件文件用 PascalCase 命名如UserProfile.tsx”。还有一个可能是规则之间有冲突。比如你在一处写了“所有文件用 camelCase”在另一处写了“组件文件用 PascalCase”AI 就不知道该听哪个。检查一遍有没有互相矛盾的规则有的话统一掉。如果以上都没问题那可能是工具本身对 AGENTS.md 的支持不够好。有些工具只是把文件内容当作普通上下文不会特别强调。这种情况下你可以在对话开始时手动提醒一句“请参考 AGENTS.md 中的约定”效果会好很多。4.2 项目太大导致 AGENTS.md 写不下怎么办大型项目的约定确实很多一份 AGENTS.md 可能装不下。这时候需要分层处理。核心约定放在根目录的 AGENTS.md 里比如技术栈、目录结构、代码规范这些全局性的信息。模块特定的约定放在各模块目录下的子配置文件中比如src/features/payment/AGENTS.md里写支付模块特有的约定。AI 工具在读取时会先读根目录的再读当前工作目录的形成层级化的上下文。另一种做法是用引用。根目录的 AGENTS.md 只写概览和索引详细内容放在docs/下的各个文件里用链接引用。AI 在需要时可以通过读取链接指向的文件来获取详细信息。不过这种方式依赖工具是否支持读取引用文件不是所有工具都支持。还有一种做法是精简。很多约定其实可以合并或省略。比如“函数不超过 50 行”和“嵌套不超过 3 层”可以合并成“保持函数简洁避免过深嵌套”。虽然精确度降低了但 AI 仍然能理解大意而且节省了篇幅。4.3 多人协作时 AGENTS.md 冲突怎么处理团队协作中每个人对项目的理解不同写出来的 AGENTS.md 可能有冲突。处理这个问题的关键是建立明确的维护流程。建议指定一个“配置负责人”由他来审核所有对 AGENTS.md 的修改。其他人发现需要补充的约定时向负责人提建议由负责人统一写入。这样可以避免多人同时修改导致的冲突和风格不一致。如果团队规模较大可以采用“提案-讨论-合并”的流程。任何人想修改 AGENTS.md先提一个提案说明改什么、为什么改团队讨论达成一致后再合并。这个流程看起来繁琐但能保证配置的质量和一致性。另一个实用技巧是把 AGENTS.md 的修改和代码修改绑定。当你提交一个 PR 时如果这个 PR 引入了新的约定或改变了现有约定就必须同时更新 AGENTS.md。这样配置和代码始终保持同步不会出现配置滞后于代码的情况。4.4 常见问题速查表问题现象可能原因排查方法解决方案AI 不遵守约定文件位置不对确认在项目根目录移到根目录AI 不遵守约定文件名不被支持查看工具文档改用支持的命名AI 不遵守约定规则表述模糊检查是否具体可执行改成具体规则AI 不遵守约定规则互相冲突搜索矛盾表述统一规则配置太长信息过多统计字数分层或精简多人冲突缺乏维护流程检查修改记录指定负责人配置过时未随代码更新对比代码现状建立同步机制4.5 几个我踩过的坑第一个坑是把 AGENTS.md 写成了 README。一开始我写了很多项目背景、业务介绍、用户画像结果 AI 对这些不感兴趣它需要的是技术约定。后来我把业务介绍压缩到三句话把省下来的篇幅用来写代码规范效果立刻好了很多。第二个坑是规则写得太细。我曾经把 ESLint 的规则逐条抄进 AGENTS.md写了上百条。结果 AI 根本记不住反而把重要的几条也忽略了。后来我只保留最关键的十几条其他的让 AI 参考 ESLint 配置就行。第三个坑是忘了更新。项目从 React 17 升级到 18 后我忘了更新 AGENTS.md 里的版本号结果 AI 一直按 17 的写法生成代码。后来我养成了习惯每次升级依赖时顺手检查一遍 AGENTS.md。第四个坑是过度依赖 AGENTS.md。有一段时间我觉得只要写好了配置AI 就能完全自主工作。实际上配置只能解决“知道什么”的问题不能解决“判断什么”的问题。复杂的架构决策、业务逻辑取舍还是需要人来把关。AGENTS.md 是辅助工具不是替代品。5. 进阶玩法让 Memory 工程真正产生复利5.1 把 AGENTS.md 和任务管理系统打通AGENTS.md 解决的是“AI 知道什么”的问题但“AI 该做什么”是另一个问题。如果你用任务管理工具比如看板、issue 跟踪器可以把任务信息和 AGENTS.md 结合起来。具体做法是在 AGENTS.md 里说明任务管理工具的用法比如“当前迭代的任务在tasks/current.md中”、“每个任务的详细描述在tasks/目录下”。然后 AI 在处理任务时会先读 AGENTS.md 了解项目约定再读任务文件了解具体要求最后动手写代码。这样做的效果是你只需要告诉 AI“做任务 #123”它就能自己找到任务描述、理解项目约定、完成代码编写。整个过程不需要你反复解释上下文效率提升非常明显。5.2 用 AGENTS.md 驱动代码审查AGENTS.md 里的约定不仅可以用来指导 AI 写代码还可以用来审查代码。你可以让 AI 对照 AGENTS.md 检查一段代码是否符合规范它会逐条核对指出不符合的地方。这个用法在代码审查时特别有用。人工审查容易遗漏细节而且不同审查者的标准不一致。用 AI 对照 AGENTS.md 审查标准统一、覆盖全面而且速度很快。当然AI 审查不能完全替代人工审查复杂的逻辑问题、架构问题还是需要人来判断。但基础的规范检查交给 AI能省下不少时间。5.3 建立项目知识的持续积累机制AGENTS.md 不是一次性的工作而是持续积累的过程。每次项目有新的约定、新的决策、新的踩坑经验都应该及时补充进去。时间长了AGENTS.md 就成了项目的知识库新人加入时读一遍就能快速上手。我建议在团队中建立这样的习惯每次解决一个棘手问题后花五分钟想想“这个经验要不要写进 AGENTS.md”。如果是通用的、可复用的经验就写进去如果是一次性的、特定场景的就放在 issue 或文档里。另一个技巧是定期回顾。每个月花半小时翻一遍 AGENTS.md看看有没有过时的内容、有没有可以合并的条目、有没有需要补充的新约定。这个习惯能让配置始终保持活力不会变成一堆无人维护的死文档。5.4 从 AGENTS.md 到更广泛的 Memory 体系AGENTS.md 只是 Memory 工程的一个起点。随着实践深入你可以扩展出更完整的体系。比如会话记忆把每次重要对话的结论记录下来放在memory/sessions/目录下AI 在需要时可以回溯之前的决策。决策日志记录每个重要技术决策的背景、选项、理由放在memory/decisions/下避免重复讨论已经决定过的事情。知识图谱把项目中的概念、模块、依赖关系整理成结构化的数据AI 在回答问题时可以查询这个图谱。这些扩展不是必须的取决于项目的复杂度和团队的需求。但方向是明确的让 AI 对项目的理解越来越深、越来越准最终达到“像团队老成员一样熟悉项目”的程度。我在实际使用中体会最深的一点是Memory 工程的价值不在于技术多复杂而在于坚持。写一份 AGENTS.md 不难难的是持续维护、持续迭代。那些真正从这套方案中获益的团队都是把它当成项目基础设施来对待的而不是当成一次性的任务。你投入的每一分钟都会在后续的开发中通过减少重复解释、减少返工、减少沟通成本而加倍回报。 
长河君 · 2026/10/18 20:56:48 · 阅读 1.2k 从无状态到有状态：AGENTS.md 如何重塑 AI 编程记忆工程
1. 从无状态到有状态AI 编程范式转换的底层逻辑1.1 为什么无状态模型是当前 AI 编程的最大瓶颈用过 AI 辅助编程的人都有一个共同感受每次开新对话就像换了一个失忆的搭档。你昨天刚跟它讲清楚项目用的是什么框架、目录结构怎么组织、命名规范是什么今天开个新窗口它又变回一张白纸你得从头再讲一遍。这不是模型不够聪明而是当前主流大模型 API 的调用方式决定的——每次请求都是独立的模型本身不保存任何跨会话的状态。这个特性在简单场景下问题不大比如你只是让它写一个排序算法、解释一段正则表达式一次对话就能搞定。但一旦进入真实项目开发问题就暴露了。一个中型项目动辄几十个模块、上百个文件涉及特定的架构约定、错误处理模式、日志规范、测试策略。你每次让 AI 帮你写一个新模块都得把相关的上下文重新喂一遍token 消耗巨大不说还经常因为上下文窗口限制而丢三落四。我自己的体验是在一个前端项目里让 AI 帮忙写一个表单组件它默认用了受控组件写法但我们项目统一用的是非受控加 ref 的方案。我没提它就按自己的习惯来。等我发现不对再纠正它改了但下一个组件它又忘了。这种反复纠正的成本累积起来非常可观。所以核心矛盾在于AI 编程的效率瓶颈已经从“模型能力不足”转移到了“上下文管理低效”。模型本身能写出高质量代码但它不知道你的项目长什么样、有什么约定、之前做过什么决策。每次都要靠人肉去补全这些信息本质上是在用人的记忆力弥补模型的失忆。1.2 Memory 工程要解决的核心问题到底是什么Memory 工程这个词听起来很玄但拆开看其实很朴素让 AI 在多次交互之间保持对项目上下文的一致认知。它要解决的不是“让模型更聪明”而是“让模型更懂你”。具体来说Memory 工程要处理三类信息。第一类是静态约定比如项目的技术栈、目录结构、代码风格、命名规范这些在项目生命周期内基本不变。第二类是动态状态比如当前正在开发哪个功能、上次对话中做了什么决策、有哪些待办事项这些会随着开发进度变化。第三类是历史决策记录比如为什么选了这个方案而不是那个、踩过哪些坑、有哪些已知问题这些是项目演进过程中积累的隐性知识。传统做法是把这些信息塞进每次请求的 prompt 里但这样做有几个致命问题。一是 token 成本随信息量线性增长二是上下文窗口有硬上限三是信息多了之后模型反而抓不住重点容易“迷失在中间”。所以 Memory 工程的核心挑战不是“能不能存”而是“怎么存、怎么取、怎么让模型在需要的时候恰好看到需要的信息”。这就引出了声明式配置的思路。与其每次动态拼接上下文不如把项目的核心约定写成一个结构化的配置文件让 AI 在每次对话开始时自动加载。这个配置文件就是 AGENTS.md 这类方案的雏形。1.3 声明式配置为什么比命令式拼接更适合 AI 编程命令式拼接的思路是每次请求前用代码动态组装上下文把相关的文件内容、历史记录、约定说明拼成一个长字符串塞给模型。这种方式灵活但脆弱因为拼接逻辑本身需要维护而且很难保证每次都能拼出正确的上下文。声明式配置的思路是把“AI 需要知道什么”写成一个静态文件放在项目根目录AI 工具在启动时自动读取。这个文件用自然语言描述项目的关键信息不需要写代码来解析模型自己就能理解。打个比方命令式拼接像是你每次出门前都要手动检查钱包、钥匙、手机带没带声明式配置像是你在门口贴了一张清单出门前看一眼就行。前者依赖你的记忆力和执行力后者依赖清单本身的完整性。对于 AI 编程来说清单的维护成本远低于每次手动拼接而且不容易遗漏。更重要的是声明式配置让“项目知识”变成了一个可版本控制的文件。你可以把它提交到 Git 仓库团队成员共享同一份配置新人加入时 AI 也能立刻获得项目上下文。这就把原本散落在各人脑子里的隐性知识变成了团队共有的显性资产。2. AGENTS.md 的核心设计一份文件如何承载项目记忆2.1 AGENTS.md 应该包含哪些内容AGENTS.md 不是随便写写就行的它的内容质量直接决定了 AI 对项目的理解程度。根据我的实践经验一份有效的 AGENTS.md 至少应该覆盖以下几个维度。项目概览是必须放在最前面的。用三五句话说明这个项目是做什么的、面向什么用户、核心功能有哪些。这部分不需要太详细目的是让 AI 建立一个大致的认知框架知道自己在什么语境下工作。技术栈与工具链要列清楚。用什么语言、什么框架、什么构建工具、什么测试框架、什么包管理器。这些信息看起来基础但 AI 如果不知道就会按自己的默认习惯来。比如你不说用的是 pnpm它可能给你生成 npm 的命令你不说用的是 Vitest它可能给你写 Jest 的测试。目录结构说明是很多人容易忽略但极其重要的一部分。不需要列出每个文件但要说明主要目录的职责。比如src/components放通用组件、src/features放业务模块、src/lib放工具函数。这样 AI 在新建文件时就知道该放哪里而不是随便找个地方塞进去。代码规范与约定要写得具体。不要只说“遵循 ESLint 规则”而要说明关键约定比如“组件文件用 PascalCase 命名”、“工具函数用 camelCase”、“常量用 UPPER_SNAKE_CASE”、“每个导出函数必须有 JSDoc 注释”。越具体AI 越不容易跑偏。常用命令要列出来。开发服务器怎么启动、测试怎么跑、构建怎么执行、代码检查怎么做。这些命令 AI 在需要验证自己的改动时会用到提前告诉它能省很多来回。已知问题与注意事项是加分项。比如“这个模块依赖一个尚未稳定的第三方库升级时需谨慎”、“这个目录下的文件不要手动修改由代码生成”、“测试环境需要先启动本地数据库”。这些信息能帮 AI 避开很多坑。2.2 怎么写才能让 AI 真正读懂写 AGENTS.md 最大的误区是把它写成给人看的文档。人看文档可以跳读、可以脑补、可以根据经验填补空白但 AI 不行。AI 会逐字逐句地理解你写的内容你写得模糊它就理解得模糊。第一个原则是具体优于抽象。不要写“代码要整洁”要写“函数不超过 50 行参数不超过 4 个嵌套层级不超过 3 层”。不要写“遵循项目风格”要写“参考src/utils/format.ts中的写法”。具体的规则 AI 能执行抽象的规则 AI 只能猜。第二个原则是正面描述优于负面禁止。尽量告诉 AI“应该怎么做”而不是“不要怎么做”。因为负面指令需要 AI 先理解什么是不该做的再推导出该做什么多了一步推理容易出错。比如与其说“不要用 any 类型”不如说“所有变量和函数返回值必须有明确的类型标注”。第三个原则是结构化优于流水账。用标题分层、用列表罗列、用代码块展示示例。AI 对结构化信息的解析能力远强于大段散文。一份好的 AGENTS.md 应该像一份精心组织的 checklist而不是一篇随笔。第四个原则是控制篇幅。AGENTS.md 不是越长越好。太长了会占用宝贵的上下文窗口而且模型在长文本中容易丢失重点。我的经验是控制在 2000 字以内把最关键的信息写进去次要信息可以放在单独的文档里按需引用。2.3 一个可参考的 AGENTS.md 模板结构下面是我在实际项目中反复打磨出来的一个模板结构你可以直接拿去改。# 项目名称 ## 项目概览 一句话说明项目定位两三句话补充核心功能和目标用户。 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 状态管理Zustand - 样式Tailwind CSS - 测试Vitest Testing Library - 包管理pnpm ## 目录结构 - src/components/通用 UI 组件每个组件一个目录 - src/features/业务功能模块按领域划分 - src/lib/工具函数和第三方库封装 - src/hooks/自定义 React Hooks - src/types/全局类型定义 ## 代码规范 - 组件文件用 PascalCase工具文件用 camelCase - 每个导出函数必须有 JSDoc 注释 - 优先使用函数式组件和 Hooks - 样式统一用 Tailwind 类名不写独立 CSS 文件 - 所有异步操作必须有错误处理 ## 常用命令 - 开发pnpm dev - 测试pnpm test - 构建pnpm build - 检查pnpm lint ## 注意事项 - src/generated/ 下的文件由代码生成不要手动修改 - 新增依赖前先确认是否已有替代方案 - 提交前必须通过 lint 和测试这个模板的好处是信息密度高、结构清晰、AI 容易解析。你可以根据项目实际情况增删条目但建议保持这个骨架。3. 实操落地从零搭建一套 Memory 工程工作流3.1 环境准备与工具选型要落地这套方案你需要一个支持读取项目配置文件的 AI 编程工具。目前主流的选择有几类一类是 IDE 插件形态的比如在 VS Code 里运行的 AI 助手一类是命令行形态的比如在终端里交互的 AI 工具还有一类是独立编辑器形态的比如专门为 AI 编程设计的编辑器。选型的核心考量是是否支持自动读取项目根目录的配置文件。如果不支持你就得每次手动把配置内容粘贴到对话里那就失去了声明式配置的意义。我建议优先选择那些明确支持 AGENTS.md 或类似机制的方案这样配置一次就能长期生效。除了 AI 工具本身你还需要一个版本控制工具来管理 AGENTS.md 的变更。Git 是标配没什么好说的。建议把 AGENTS.md 放在项目根目录和 README.md 平级这样既显眼又符合惯例。另外建议准备一个docs/目录用来存放更详细的文档。AGENTS.md 只放最核心的约定详细的架构说明、API 文档、部署流程可以放在docs/下在 AGENTS.md 里用链接引用。这样既保持了 AGENTS.md 的精简又不会丢失重要信息。3.2 第一步梳理项目现状并提取关键约定在写 AGENTS.md 之前先花半小时把项目现状梳理一遍。这一步很多人会跳过直接开始写结果写出来的东西要么遗漏关键信息要么包含大量无关内容。梳理的方法是打开项目根目录从入口文件开始沿着目录树走一遍。每看到一个目录问自己三个问题这个目录是干什么的AI 在什么情况下会往这里加文件加文件时有什么约定把答案记下来。然后看配置文件。package.json里的 scripts 和 dependencies、tsconfig.json里的编译选项、.eslintrc里的规则、vite.config.ts里的构建配置。这些文件里的信息很多可以直接提炼到 AGENTS.md 里。接着看代码风格。随便打开几个代表性文件观察命名习惯、注释风格、错误处理方式、测试写法。把这些观察总结成几条明确的规则。最后回忆一下过去踩过的坑。有没有因为 AI 不知道某个约定而写错代码的情况有没有某个模块特别容易出问题把这些经验也写进去。3.3 第二步编写并迭代 AGENTS.md第一版 AGENTS.md 不需要追求完美先把能想到的都写进去然后在实际使用中迭代。我的经验是第一版写完后用 AI 做几个真实任务观察它在哪些地方理解错了、哪些地方需要你额外解释。每次纠正后把对应的约定补充到 AGENTS.md 里。迭代的频率建议是项目初期每周更新一次稳定后每月更新一次。每次更新不需要大改补充几条规则、修正几处表述就行。关键是保持这个习惯让 AGENTS.md 始终反映项目的最新状态。有一个技巧是当你发现自己在对话中反复向 AI 解释同一个东西时就说明这个东西应该写进 AGENTS.md 了。比如你第三次告诉 AI“这个项目的 API 请求都要走src/lib/api.ts里的封装”那就别再口头说了写进配置文件。另一个技巧是让 AI 帮你写 AGENTS.md。你可以把项目结构贴给 AI让它根据观察生成一份初稿然后你再修改。这样能省不少力气而且 AI 可能会发现一些你忽略的细节。3.4 第三步验证配置效果并建立反馈循环写完 AGENTS.md 后怎么知道它有没有效果最直接的验证方法是开一个新对话让 AI 做一个需要项目上下文的任务看它是否需要你额外解释。如果它能直接按你的约定来说明配置生效了如果还需要你补充说明说明配置有遗漏。我通常会做三个测试。第一个是新建文件测试让 AI 在指定目录下创建一个新组件看它是否用了正确的命名、是否放了正确的位置、是否遵循了代码规范。第二个是修改测试让 AI 修改一个现有函数看它是否保持了原有的风格、是否更新了相关测试。第三个是查询测试问 AI 某个功能在哪里实现、某个约定是什么看它能否从 AGENTS.md 中找到答案。根据测试结果把遗漏的约定补进去把表述不清的地方改清楚。这个过程重复两三轮AGENTS.md 就基本稳定了。反馈循环的建立也很重要。建议在团队中指定一个人负责维护 AGENTS.md其他人发现 AI 理解偏差时向这个人反馈。或者更简单的方式是谁发现遗漏谁就补把 AGENTS.md 当成代码一样对待发现问题就提 PR 修改。4. 常见问题与排查技巧实录4.1 AGENTS.md 写了但 AI 不遵守怎么办这是最常见的问题。你明明写了“组件文件用 PascalCase”AI 还是给你生成了 camelCase 的文件名。遇到这种情况先别急着怀疑方案本身按下面的顺序排查。首先检查文件位置。AGENTS.md 必须放在项目根目录有些工具只认根目录下的文件放在子目录里不生效。其次检查文件名。不同工具对配置文件的命名要求不同有的认 AGENTS.md有的认 .ai-config有的认其他名字。确认你用的工具支持哪种命名。然后检查内容表述。如果规则写得太模糊AI 可能理解不了。比如“遵循项目风格”这种表述AI 根本不知道项目风格是什么。改成具体的规则比如“组件文件用 PascalCase 命名如UserProfile.tsx”。还有一个可能是规则之间有冲突。比如你在一处写了“所有文件用 camelCase”在另一处写了“组件文件用 PascalCase”AI 就不知道该听哪个。检查一遍有没有互相矛盾的规则有的话统一掉。如果以上都没问题那可能是工具本身对 AGENTS.md 的支持不够好。有些工具只是把文件内容当作普通上下文不会特别强调。这种情况下你可以在对话开始时手动提醒一句“请参考 AGENTS.md 中的约定”效果会好很多。4.2 项目太大导致 AGENTS.md 写不下怎么办大型项目的约定确实很多一份 AGENTS.md 可能装不下。这时候需要分层处理。核心约定放在根目录的 AGENTS.md 里比如技术栈、目录结构、代码规范这些全局性的信息。模块特定的约定放在各模块目录下的子配置文件中比如src/features/payment/AGENTS.md里写支付模块特有的约定。AI 工具在读取时会先读根目录的再读当前工作目录的形成层级化的上下文。另一种做法是用引用。根目录的 AGENTS.md 只写概览和索引详细内容放在docs/下的各个文件里用链接引用。AI 在需要时可以通过读取链接指向的文件来获取详细信息。不过这种方式依赖工具是否支持读取引用文件不是所有工具都支持。还有一种做法是精简。很多约定其实可以合并或省略。比如“函数不超过 50 行”和“嵌套不超过 3 层”可以合并成“保持函数简洁避免过深嵌套”。虽然精确度降低了但 AI 仍然能理解大意而且节省了篇幅。4.3 多人协作时 AGENTS.md 冲突怎么处理团队协作中每个人对项目的理解不同写出来的 AGENTS.md 可能有冲突。处理这个问题的关键是建立明确的维护流程。建议指定一个“配置负责人”由他来审核所有对 AGENTS.md 的修改。其他人发现需要补充的约定时向负责人提建议由负责人统一写入。这样可以避免多人同时修改导致的冲突和风格不一致。如果团队规模较大可以采用“提案-讨论-合并”的流程。任何人想修改 AGENTS.md先提一个提案说明改什么、为什么改团队讨论达成一致后再合并。这个流程看起来繁琐但能保证配置的质量和一致性。另一个实用技巧是把 AGENTS.md 的修改和代码修改绑定。当你提交一个 PR 时如果这个 PR 引入了新的约定或改变了现有约定就必须同时更新 AGENTS.md。这样配置和代码始终保持同步不会出现配置滞后于代码的情况。4.4 常见问题速查表问题现象可能原因排查方法解决方案AI 不遵守约定文件位置不对确认在项目根目录移到根目录AI 不遵守约定文件名不被支持查看工具文档改用支持的命名AI 不遵守约定规则表述模糊检查是否具体可执行改成具体规则AI 不遵守约定规则互相冲突搜索矛盾表述统一规则配置太长信息过多统计字数分层或精简多人冲突缺乏维护流程检查修改记录指定负责人配置过时未随代码更新对比代码现状建立同步机制4.5 几个我踩过的坑第一个坑是把 AGENTS.md 写成了 README。一开始我写了很多项目背景、业务介绍、用户画像结果 AI 对这些不感兴趣它需要的是技术约定。后来我把业务介绍压缩到三句话把省下来的篇幅用来写代码规范效果立刻好了很多。第二个坑是规则写得太细。我曾经把 ESLint 的规则逐条抄进 AGENTS.md写了上百条。结果 AI 根本记不住反而把重要的几条也忽略了。后来我只保留最关键的十几条其他的让 AI 参考 ESLint 配置就行。第三个坑是忘了更新。项目从 React 17 升级到 18 后我忘了更新 AGENTS.md 里的版本号结果 AI 一直按 17 的写法生成代码。后来我养成了习惯每次升级依赖时顺手检查一遍 AGENTS.md。第四个坑是过度依赖 AGENTS.md。有一段时间我觉得只要写好了配置AI 就能完全自主工作。实际上配置只能解决“知道什么”的问题不能解决“判断什么”的问题。复杂的架构决策、业务逻辑取舍还是需要人来把关。AGENTS.md 是辅助工具不是替代品。5. 进阶玩法让 Memory 工程真正产生复利5.1 把 AGENTS.md 和任务管理系统打通AGENTS.md 解决的是“AI 知道什么”的问题但“AI 该做什么”是另一个问题。如果你用任务管理工具比如看板、issue 跟踪器可以把任务信息和 AGENTS.md 结合起来。具体做法是在 AGENTS.md 里说明任务管理工具的用法比如“当前迭代的任务在tasks/current.md中”、“每个任务的详细描述在tasks/目录下”。然后 AI 在处理任务时会先读 AGENTS.md 了解项目约定再读任务文件了解具体要求最后动手写代码。这样做的效果是你只需要告诉 AI“做任务 #123”它就能自己找到任务描述、理解项目约定、完成代码编写。整个过程不需要你反复解释上下文效率提升非常明显。5.2 用 AGENTS.md 驱动代码审查AGENTS.md 里的约定不仅可以用来指导 AI 写代码还可以用来审查代码。你可以让 AI 对照 AGENTS.md 检查一段代码是否符合规范它会逐条核对指出不符合的地方。这个用法在代码审查时特别有用。人工审查容易遗漏细节而且不同审查者的标准不一致。用 AI 对照 AGENTS.md 审查标准统一、覆盖全面而且速度很快。当然AI 审查不能完全替代人工审查复杂的逻辑问题、架构问题还是需要人来判断。但基础的规范检查交给 AI能省下不少时间。5.3 建立项目知识的持续积累机制AGENTS.md 不是一次性的工作而是持续积累的过程。每次项目有新的约定、新的决策、新的踩坑经验都应该及时补充进去。时间长了AGENTS.md 就成了项目的知识库新人加入时读一遍就能快速上手。我建议在团队中建立这样的习惯每次解决一个棘手问题后花五分钟想想“这个经验要不要写进 AGENTS.md”。如果是通用的、可复用的经验就写进去如果是一次性的、特定场景的就放在 issue 或文档里。另一个技巧是定期回顾。每个月花半小时翻一遍 AGENTS.md看看有没有过时的内容、有没有可以合并的条目、有没有需要补充的新约定。这个习惯能让配置始终保持活力不会变成一堆无人维护的死文档。5.4 从 AGENTS.md 到更广泛的 Memory 体系AGENTS.md 只是 Memory 工程的一个起点。随着实践深入你可以扩展出更完整的体系。比如会话记忆把每次重要对话的结论记录下来放在memory/sessions/目录下AI 在需要时可以回溯之前的决策。决策日志记录每个重要技术决策的背景、选项、理由放在memory/decisions/下避免重复讨论已经决定过的事情。知识图谱把项目中的概念、模块、依赖关系整理成结构化的数据AI 在回答问题时可以查询这个图谱。这些扩展不是必须的取决于项目的复杂度和团队的需求。但方向是明确的让 AI 对项目的理解越来越深、越来越准最终达到“像团队老成员一样熟悉项目”的程度。我在实际使用中体会最深的一点是Memory 工程的价值不在于技术多复杂而在于坚持。写一份 AGENTS.md 不难难的是持续维护、持续迭代。那些真正从这套方案中获益的团队都是把它当成项目基础设施来对待的而不是当成一次性的任务。你投入的每一分钟都会在后续的开发中通过减少重复解释、减少返工、减少沟通成本而加倍回报。