AI 用 Codex、Claude Code 写代码的人，最近半年大概率都干过同一件事：发现 AI 不懂你的项目，于是往 AGENTS.md 里补规则。目录结构写进去，测试命令写进去，代码规范写进去，历史踩坑也写进去。文件从 20 行写到 200 行，越写越长。
然后发现，AI 反而越来越不听话了。
这不是你一个人的错觉。社区里专门有人写了篇文章叫《AGENTS.md 越写越长，Codex 反而越用越笨？》，戳的就是这个坑。知乎时间点也很微妙：就在 8 月 19 日，OpenAI 刚宣布开源 Codex 的底层核心框架（Codex Harness），“怎么把仓库整理得让 Agent 能用”这个话题，又被推到了讨论中心。微博
而 OpenAI 自己也公开复盘过：他们早期同样把大量规则堆进一个巨大的 AGENTS.md，效果并不好。官方的结论很直接——AGENTS.md 更像一个目录（table of contents），真正的系统事实应该放在结构化的 docs/ 里，而不是全塞进这一个文件。知乎
为什么“多写”反而是错的？三个原因，都跟模型的工作方式有关。
第一，上下文是稀缺资源。Agent 最该看的东西，是当前改动、相关模块、测试输出和调用链。结果这些信息还没进场，上下文窗口先被一份“大而全说明书”吃掉了。第二，制造伪重点。人写长文档会保留“历史上重要过”的内容，但对模型来说，旧规则、新规则、局部例外全在同一个提示空间里竞争权重，最后不是信息更充分，而是信息更混乱。第三，快速腐化。代码变了文档没同步，AGENTS.md 会变成仓库里“最像真相、又最可能偏离真相”的文件。
还有一个很硬的工程证据：Codex 发现 AGENTS.md 的顺序是“全局配置→仓库根目录→当前工作目录”，越靠近当前目录优先级越高，而且整条指令链默认有 32 KiB 的大小限制。知乎这个设计本身就说明了一切——AGENTS.md 从第一天起就不是知识仓库，是知识仓库的入口。
所以社区现在有个越来越共识的说法：AGENTS.md 不是项目内容，AGENTS.md 是项目路由。它该回答的不是“这个项目的一切”，而是“遇到什么事，去哪里查”。
那到底该写什么？把知乎上几篇高收藏的系列文章、K 神（Karpathy）流出的那份 65 行规则、还有 Reddit r/codex 的实战帖放在一起看，能提炼出的高 ROI 内容其实就几类：
一是可复制粘贴的精确命令。装依赖、起服务、跑测试，到底是 npm test 还是 pnpm test 还是某个埋在脚本里的别名，别让 AI 猜。二是测试约定。测试框架、Mock 策略、覆盖率要求。三是文件定位指南。不是架构论文，就是“什么东西在哪个目录”。四是 Git 约定。分支命名、Commit 格式、PR 规范。五是三级边界——什么能做，什么要先问，什么绝对不能碰。知乎K 神那 4 条规则解决的核心痛点就是 AI 修个小 bug 却顺手重构半个模块、把简单逻辑强行封装成多层结构，这一条对用过 AI 编程的人来说应该都很眼熟。知乎
还有一组数字值得记住：一份写得好的 AGENTS.md，大约能把 Agent 的任务成功率提升 4%，减少 35% 到 55% 的 bug；而一份糟糕的，比没有文件更差——有人做了测试，LLM 自动生成的 AGENTS.md 在 8 个测试场景里有 5 个表现不如空文件。知乎小红书上一篇高收藏的帖子还援引了今年的实证研究：详细到一定程度的 AGENTS.md，任务成功率反而开始下降。小红书这跟前面那 4% 并不矛盾——“写得好”和“写得多”，从来是两回事。也就是说，让 AI 自己给你生成一份“完美规范”然后直接交差，大概率是负优化。
当然也得说清楚这东西的适用边界，免得无脑跟风。已经有实践者观察到：AGENTS.md 的收益跟模型强相关。指令遵循能力强的旗舰模型，写不写差别没那么大；中等规模、指令遵循好的模型收益最明显；而小模型理解不了抽象准则，写了也白写。知乎另外，如果你的仓库本来就被整理得很好，这套东西的边际收益也会小很多——它解决的主要是“知识散落在聊天记录和资深同事脑子里”的团队。
如果你现在的 AGENTS.md 已经很长了，最不值得做的就是继续往里补。更值得做的是四件事：
第一，把 AGENTS.md 砍回 100 行以内，只留路由和最高层约定，细节指向具体文件，让 Agent 按需展开——社区管这个叫 progressive disclosure。小红书第二，把真正影响判断的知识搬进结构化的 docs/：架构边界、核心概念、关键约束、验证方式，给它们固定的地址。第三，给那些“看起来丑但不能动”的代码写决策记录。有些模块丑是因为历史数据兼容，有些接口别扭是因为外部系统已绑定，这些信息不写下来，AI 一定会反复重蹈覆辙——它可以叫 ADR，也可以只是带日期、带结论、带替代方案的 decision log。第四，写一个 bootstrap 脚本，让 Agent 进仓库后能通过一个稳定入口完成装依赖、起服务、初始化、跑测试。只要环境还靠猜，AI 就永远停留在“摸索进场”阶段。
最后给一个自检问题，判断你的仓库对 AI（以及对新人）友不友好：如果今天来一个非常勤奋的新同事，只给他仓库本身，他能不能在短时间内找到关键事实、理解边界、跑通验证、避开旧坑？
答案是否定的话，AI 表现不稳定往往不是 prompt 不够强，而是仓库还没被整理成一张可用的地图。下一阶段 AI 编程真正的分水岭，可能不是谁的提示词更长，而是谁先把自己的代码库整理明白。这篇可以先收藏，下次对着仓库改造时逐条对照。
