文档越厚,AI 越记不住——给项目文档重构的正确姿势

几轮迭代下来，项目根目录长出一套文档系统。AGENTS.md 从几十行膨胀到几百行，context/ 目录塞了 15 个 Markdown，.cursor/rules 列了 30 条行为约束。每个文档都言之有物——架构决策、踩坑记录、命名规范、API 约定——全是真刀真枪积累出来的。你要问这些文档有没有用，有用。你要问 AI 有没有读进去——它翻到后面就开始走神了。

问题是，文档越厚，AI 越记不住。之前约定好的命名规则开始被忽略，精心编写的架构约束像从来没被读过。遇到这种场景，第一反应是再加几条规则——然后情况更差。给 AI 更多信息，它反而记住的更少。你亲手验证过有效的规则，在新对话里被 AI 当空气——不是它忘了，是从没读到过。

本文的方法论适用于任何支持项目级指令的 AI 编程工具（如 Cursor、TRAE、Windsurf 等）。AGENTS.md 是跨工具通用标准；文中以 .cursor/rules 指代 Cursor 的规则文件机制，其他工具（如 TRAE 的规则配置）用法相似。

三个信号

•AI 开始忽略 AGENTS.md 后半部分的内容？ 明明在文件后半部分写了”所有 API 路由统一用 kebab-case”，AI 却用 camelCase 写了一个新接口。你 @ 它看那一行，它”恍然大悟”——但在下一次对话里又忘了。•AI 反复犯已经”约定好”的错误？ 在规则文件里写了”不要用 any 类型”，这周第三次用了 any。去检查规则文件——规则还在，就是没被遵守。•新需求来了，不知道该改哪个文件？ 改 AGENTS.md 怕它越来越长，改规则文件怕它变成第二个 AGENTS.md，新开一个 context/xxx.md 怕它淹没在 15 个文件里再也不会被读到。

三条中了两条以上，说明已经落入了经典的恶性循环。

为什么文档越多，AI 越记不住？

上下文窗口是 AI 同时能”看到”的内容上限。主流大模型通常是 200K tokens（部分模型已逐渐支持到 100 万 tokens）。听起来很大，翻译成实际场景：每次对话开始，IDE 自动注入 AGENTS.md、规则文件、当前打开文件、相关代码片段——加起来轻松吃掉 20K-30K tokens。AGENTS.md 有 8,000 tokens 的话，加上 15 个 context/ 文件被引用，上下文里有效信息的比例直线下降。

顺便说一句：200K tokens 如果塞满纯中文，大约相当于一整本《活着》的字数。你让 AI 在每次对话开头先读完一本书再开始干活——它能”读完”，但用来理解你的指令和写好代码的精力已经耗掉大半了。

学术界管这叫”Lost in the Middle”效应——研究发现 LLM 对输入信息的利用率呈 U 形曲线：开头记得最牢，结尾次之，中间显著下滑。更令人意外的是，中间位置的信息利用率有时甚至低于不提供任何上下文时的表现——给了信息反而比不给更差。你写在 AGENTS.md 中间的规则，被 AI 遵守的概率远低于开头和末尾那几条。

拿”AI 像高智商实习生”这个类比想一下：

第一，聪明但缺乏组织记忆。给一份几百页的入职手册，和给一份一页纸的”先看这个”地图，效果天差地别。几百页手册翻过前面一截就开始跳读，中间往后翻了跟没翻一样。AGENTS.md 内容堆到几百行后 AI 开始跳读中间部分，同一回事。

第二，不会主动说”我记不住了”。信息量超出处理能力时，实习生不会举手说”这部分我没记住”——他会根据记住的部分硬着头皮继续干活。AI 也一样：接近上下文限制时，它开始过早结束工作、避免启动新任务。多个模型在接近上下文限制时都表现出了这种焦虑行为。不是偷懒，是真的记不住更多了。

这就转起了一个死循环：写了一个好规则 → AI 遵守了一次 → 加了更多规则 → 上下文被挤占 → AI 开始忽略规则 → 以为规则不够细 → 加了更详细的规则 → AI 表现更差。每加一条规则，实际上在挤占 AI 做正事的 token 预算。入职必读手册从一页纸变成了一本书——它读不完，但还在往里面加章节。

问题找到了。但解决它需要的不是”写得更少”这么简单。这背后有一个被忽略的底层设计原则，在交互设计领域已经发展了四十多年。1983 年，IBM 研究员 John Carroll 发现了一个反直觉的结论：在学习阶段把高级功能藏起来，只留最基本的界面，用户后续使用高级功能的成功率反而更高。2006 年，可用性专家 Jakob Nielsen 将这一发现正式命名为”渐进式披露”（Progressive Disclosure）——先展示最核心的信息降低门槛，在需要时再按需展开细节。2025 年，Anthropic 将这一原则引入 AI 领域：Claude Skills 不是一次性加载所有技能说明书，而是先扫描 100 字的元数据判断相关性，判定相关后才加载完整指令，参考文件只在真正需要时读取。

这个原则恰好回答了我们现在面临的问题：不是文档太多，而是所有文档都在同一层——AI 没有”翻开目录看一眼就够了”的选择，被迫每顿饭都吃满汉全席。接下来要做的三步，本质上就是把项目文档从”一股脑堆给 AI”变成”渐进式披露给 AI”：第一层给地图，第二层装护栏，第三层放参考书——AI 每次只需从第一层出发，按路径向下探索。这就是为什么”画地图”比”写说明书”管用。

第一层：地图（AGENTS.md）  项目是什么（一句话）  技术栈（一行）  最重要的 3 条铁律  去哪找更多信息 →  按需向下探索    ├── 第二层：护栏（rules/）    │     规则 1：触发条件 + 约束内容    │     规则 2：触发条件 + 约束内容    │     规则 3：触发条件 + 约束内容    │    └── 第三层：参考书（references/）          架构决策记录          API 设计详细说明          术语表 / 项目纵览

核心逻辑：AI 每次对话自动加载第一层（地图），遇到特定任务时触发第二层（护栏），需要深入了解时手动引用第三层（参考书）。三层各司其职，AI 不会在一开始就被不必要的信息淹没。

第一步：一个大文件还是多个小文件？

这是第一个决策。两条路：

方案 A：一个大文件。 把所有约定塞进 AGENTS.md——技术栈、架构决策、命名规范、API 设计原则、踩坑记录。好处是 AI 理论上能看到一切，坏处是实际只会看前面一部分和末尾，中间是盲区。OpenAI Codex 团队在自己的实践中确认了这一点：一个大型 AGENTS.md 是”明确的失败模式”——它会变成陈旧规则的坟场，而且极难维护。

方案 B：多个小文件。 AGENTS.md 拆成 architecture.md、naming-convention.md、api-guidelines.md，加上 rules/ 规则目录。好处是轻量——AI 只加载需要的文件，坏处是 AI 可能不知道该读哪个、什么时候读。

实际用下来，走的是中间路线：AGENTS.md 当地图，不写说明书。

具体做法：

1.AGENTS.md 控制在 200-300 行，核心功能是告诉 AI 去哪找信息。重点是信息精炼，不数行数。不写技术细节，只写指针和高层原则。2.按使用频率和约束类型分拆到三个层级：

做完这一步，AGENTS.md 从几百行瘦身到 200-300 行。每次打开新对话，AI 直接加载一个轻量的地图，而不是一本打开就困的手册。

一个容易踩的坑：把 AGENTS.md 的内容平移复制到子文件然后删掉 AGENTS.md——我试过，效果很差。先确定各子文件的用途——architecture-decisions.md 和 glossary.md 和 rules/ 的边界必须清晰。边界模糊的文件系统比一个大文件更糟：AI 会在三个文件之间来回引用却找不到答案。记住命名即触发开关：glossary.md 明确告诉 AI”这是词典，遇到生词时打开”；architecture-decisions.md 告诉 AI”这是历史决策记录，理解架构时查阅”。一个含糊的 CONTEXT.md 等于什么都没告诉 AI——它不知道什么时候该读，最终什么都不会主动读。

Next.js 官方的实验数据显示：将压缩索引嵌入 AGENTS.md 作为被动上下文的通过率是 100%，而依赖 Skills 动态检索仅为 53%。无决策点、持续可用的被动上下文，可靠性远超”AI 判断要不要加载”的主动检索。

第二步：哪种加载方式代价最小？

文件拆好了。但拆完之后问题只解决了一半：这些拆出来的文件，哪些是 AI 每次对话都要看的，哪些是碰到了才需要看的？把不该常驻的东西塞进 AGENTS.md，等于瘦身没瘦对地方——上下文照样被挤占，只是换了个文件挤而已。

三种上下文注入方式，恰好对应了渐进式披露的三层架构：

没有”最佳方案”，只有”正确分配”。把什么东西放进哪个通道，比选哪个通道更重要。实际分配方式：

AGENTS.md（被动上下文）——放”每次都需要的身份信息”：项目是什么（一句话）、技术栈（一行）、文件结构约定（3-5 条）、代码风格铁律（2-3 条）。信息量小但价值密度高，每次加载的开销不到 500 tokens，保证 AI 在任何对话中都不会搞错项目的基本调性。

规则文件（按需加载，Cursor 中是 .cursor/rules）——放”踩过坑才写进去的约束”：不是”建议使用 TypeScript 严格模式”，而是”在第 3 次看到 any 类型后写入：禁止使用 any，用 unknown 替代”。每条规则背后有一个真实的 bug 或返工。规则触发关键词精确匹配：比如写完 类型安全的 API 请求 规则，触发词设为 fetch, api, request, axios——只在 AI 写请求代码时才加载这条规则，不会在写组件时占用 token。

手动粘贴（临时注入）——放”一次性的项目背景”：比如”这个 Sprint 在重构支付模块，已有的 payment-service.md 里有完整的架构说明，需要时我会 @ 你”。不要把背景提前全灌进去——需要时再喂。

另外一个坑：很多人把术语表、关系描述放进 AGENTS.md 的被动上下文中，每次对话都加载。术语表的价值是”冲突发生时查阅”，不是”每次都用得上”。把它放到 references/ 目录，文件名叫 glossary.md——AI 遇到术语冲突或理解歧义时会自主查阅，省下的 token 够 AI 多写 300 行代码。一个好的文件名本身就是一种元数据：glossary.md 明确告诉 AI 它的边界是”术语定义”，不会有人在里面塞架构决策或 API 约定；而叫 CONTEXT.md 的文件迟早会变成什么都往里扔的杂物抽屉。

这三种方式的比例分配调了好几轮才找到感觉。一开始把太多东西塞进被动上下文，每次新对话 AI 的回复都很短、急着问”还有什么需要帮助”——不是不配合，是喂了太多那一刻根本不需要知道的东西。后来定了一个规矩：往 AGENTS.md 里加任何一行之前，先问一句——这条信息每次对话都必须知道吗？答案不坚决的，不放。

第三步：新需求来了，改哪个文件？

做完前两步，文档系统从”一本大书”变成了”地图 + 工具箱”。但还有一个问题——这个系统会重新膨胀吗？

两个维护方向：

预填坑： 在项目初期把能想到的所有规则都写进去——”将来可能会遇到 X 问题，所以先写一条规定”。好处是看起来周全，坏处是 80% 的规则永远不会被触发（但每次都会消耗 token 预算），而且预判的规则往往不准。

让坑先出现： 只在 AI 真实犯错后才将错误沉淀为规则。AI 在同一类问题上连续搞砸 2 次以上，才写入规则文件。

选了后者。理由简单——没栽过跟头的规则是猜测：它看起来有用，实际上在消耗 token 预算却没有防御任何真实的错误。预填的规则就像没生过病的疫苗，打了可能白打，还可能有副作用。

具体触发规则：

•AI 在同一类问题上连续犯错 2 次以上 → 写入规则文件。 比如 AI 第三次给 React 组件写了默认导出，而项目统一用命名导出——三次返工证明了这条规则值那 200 tokens 的加载成本。•技术栈或架构发生变更 → 更新 AGENTS.md。 等到 AI 在新旧架构之间反复横跳再改，已经白踩了好几个坑了。比如从 REST 切到 tRPC，AGENTS.md 里的”API 设计原则”要同步更新。•一个规则文件超过 2 周没触发过 → 归档或删除。 规则不是越积越多，是动态演化的。两周没触发的规则，要么问题已经被修好了（检查一下是不是已经不再是问题了），要么触发词写太窄（调整触发条件）。•AGENTS.md 超过 300 行 → 立即审计。 不是删内容，是把该移到子文件的内容移出去。审计时问三个问题：这段信息每次对话都要用吗？（是→留在 AGENTS.md，否→移出）、有没有跟其他规则重复？（有→合并）、最后一次被用到是什么时候？（超过一个月→考虑删除）。

审计节奏建议每 2-4 周做一次，5 分钟扫一遍。比不审计导致的每天多花 10 分钟跟 AI 反复解释，划算得多。

怎么知道改对了？

三个验证动作：

1.AGENTS.md 行数检查：打开文件，看一眼行号。超过 300 行说明审计没做透，回头检查哪个段落不该在被动上下文中。2.新对话盲测：开一个全新对话，不贴任何额外上下文，直接让 AI 写一个项目中典型的组件或接口。观察两件事：它有没有遵守 AGENTS.md 里的核心约定（命名规范、文件结构），有没有触犯规则文件里的约束。如果犯了，多半是规则文件的触发词写窄了，不是规则本身有问题——先检查触发词。3.上下文预算感知：注意一个现象——AI 是否在任务进行到一半时开始”收尾”。如果回复明显变短、开始说”还有什么要我帮忙的吗”这类句式，说明上下文已经接近饱和。此时检查：是不是 AGENTS.md 里塞了不该塞的东西，或者对话本身太长需要 checkpoint。

做完这三项验证，差异应该是明显的：AI 不再”健忘”，因为不重要的信息不再挤占重要的信息。

三个最常见的坑，以及一个能省你半天时间的技巧

误区一：”文档写得越详细，AI 表现越好。” 把 AGENTS.md 当项目 Wiki 写，恨不得把业务需求文档也塞进去。AGENTS.md 不是新同事的入职培训材料——新同事可以花一周慢慢读，AI 必须在 3 秒内”读完”。地图告诉你往哪走能找到答案，不是把答案全印在地图上。

误区二：”规则文件里条目越多越安全。” 护栏的价值不在数量，在每条护栏都护着一个真实的悬崖边。一条没用的护栏不仅浪费 token，还稀释了其他护栏的权重——AI 面对 30 条规则时的遵守意愿，远低于面对 5 条。

误区三：”开了新对话，AI 就彻底忘了我的项目——所以必须把一切都塞进 AGENTS.md。” AI 的”健忘”不是 bug，是设计。每次新对话它只从文件读信息，不保留上一轮的对话记忆。这个特性反过来用很省事：需要 AI 每次都知道的信息放 AGENTS.md；只需要在特定场景知道的信息放子文件；上一轮对话的临时上下文不要试图”固化”——总结成 1-2 句话的决策记录足够，别把整个对话历史变成文档。

实用技巧： 如果你的 IDE 支持计划模式（如 Cursor 的 Shift+Tab Plan Mode），让 AI 先输出执行计划——在计划中可以看到它读取了哪些规则文件。如果关键规则没有被加载，说明触发词需要调整。相当于免费对规则系统做了一次健康检查。

这件事背后有一个更通用的原则：信息系统的价值从来不取决于你塞了多少东西进去，而是取决于取东西的速度。图书馆不是因为藏书多才有用，是因为有检索系统。你的项目文档也一样——不是在比谁写的厚，是在比 AI 能不能在三秒内定位到它当下最需要的那一条。

手上这套文档管理框架现在完整了。回到开头那个困境：打开 AGENTS.md，几百行内容，AI 只读了前半截。现在知道怎么办了——不是删内容，是给内容找到对的位置。核心信息守住 AGENTS.md 这一张地图，约束收进规则文件当护栏，参考文档放进 references/，文件名叫得清清楚楚：architecture-decisions.md 只放架构决策，glossary.md 只放术语定义，api-design.md 只放 API 约定。AI 在需要时会自己去找，因为它终于知道什么东西在哪里。

文档系统的目标不是让 AI 一次性的知道一切，而是让 AI 在需要的时候知道该去哪找。把这件事做对了，打开 IDE 的时候少了一股隐约的烦躁——因为你知道它这次大概不会又搞错了。

感谢读到这里。有收获的话，帮我点赞、转发给需要的朋友❤️ 我们下篇文章见～

文 | AI & 芦苇Z