AGENTS.md 越写越长，Codex 反而越用越笨?

很多团队一用 Codex，就会立刻掉进同一个坑里。

模型不够懂项目？

那就继续往 AGENTS.md 里补。

目录写进去，测试命令写进去，代码规范写进去，部署注意事项写进去，历史坑点也写进去。

最后，一个原本想让模型“更懂项目”的文件，被硬生生写成了一本项目说明书。

问题是，这套做法看起来努力，结果却常常是反的。

AGENTS.md 越长，Codex 越容易失焦。

规则越多，模型越容易抓不住重点。

写到最后，团队得到的不是一个更聪明的 Agent，而是一个背着沉重包袱上路的 Agent。

这就是为什么我越来越认同一个判断：

别再把 AGENTS.md 写成说明书了。

它应该是一张地图。

不是模型不行，是仓库太乱

很多人一看 Codex 发挥不稳定，第一反应是模型还不够强。

但 OpenAI 最近公开总结过他们自己的经验：他们早期也试过把大量规则堆进一个大的 AGENTS.md 文件里，结果并不好 [1]。

原因其实很简单。

上下文是稀缺资源。一个超长 AGENTS.md，会挤掉本该留给当前任务、关键代码、测试输出和相关文档的位置。更糟的是，当所有内容都被写成“重要规则”时，Agent 反而更难判断什么才是眼前最重要的信息。

这不是模型的问题。

这是仓库组织方式的问题。

说得再直一点：

很多团队不是不会用 Agent。

而是把仓库整理得根本不适合 Agent 用。

“大说明书思维”，本身就是错的

很多人默认有一个朴素逻辑：

模型懂得不够多，那就补更多背景。

这个逻辑放在聊天场景里，也许还勉强成立。

但放到代码 Agent 场景里，往往正好相反。

因为 Agent 真正需要的，从来不是一份越来越厚的总说明，而是三种能力：

• • 快速定位

• • 快速验证

• • 快速排除无关信息

而一个庞大的 AGENTS.md，恰恰会同时破坏这三件事。

第一，它浪费上下文。

Agent 最该看的，本来应该是当前改动、相关模块、测试反馈、调用链和局部文档。结果这些信息还没进来，上下文先被一份“大而全说明书”吃掉了。

第二，它制造伪重点。

人类写长文档时，总会把“以前重要过的内容”也一起保留下来。可对模型来说，旧规则、新规则、局部例外、历史遗留都会在同一个提示空间里竞争权重。最后不是信息更充分，而是信息更混乱。

第三，它会迅速腐化。

代码变了，文档未必同步；流程变了，旧规则未必删除。时间一长，AGENTS.md 很容易变成仓库里最像真相、又最可能偏离真相的文件。

第四，它根本不利于维护。

OpenAI 在文章里提到，单一的大文件不利于 freshness、ownership、cross-links 这类机械检查 [1]。这句话非常关键。因为 Agent 时代真正可靠的知识，不应该只靠人脑记得更新，而应该尽可能变成可以被追踪、被校验、被维护的东西。

所以，问题不是 AGENTS.md 要不要写。

问题是，为什么总有人把它写成一本项目圣经。

AGENTS.md 不是知识库，它是路由层

这可能是这波 Codex 实践里最重要的认知转变。

OpenAI 现在给出的方向已经很清楚：AGENTS.md 更像一个 table of contents，真正的系统事实来源应该放在结构化的 docs/ 里，而不是都塞进 AGENTS.md [1]。

官方文档也给了同样的信号。Codex 会按“全局配置 -> 仓库根目录 -> 当前工作目录”的顺序去发现 AGENTS.md，而且越靠近当前目录的规则优先级越高；整条指令链默认还有 32 KiB 的大小限制 [2]。

这已经说明一件事：

AGENTS.md 从设计上就不是知识仓库。

它是知识仓库的入口。

它不是拿来装下一切的。

它是拿来决定“先看哪里”的。

如果一定要给它一个更直白的定义，那就是：

AGENTS.md 不是项目内容。

AGENTS.md 是项目路由。

真正该补的，不是更多规则，而是更清晰的分层

如果一个团队真想把 Codex 用顺，重点根本不该放在“继续往 AGENTS.md 里补什么”。

重点应该放在：

这个仓库有没有分层。

一个更靠谱的最小组合，其实只有四样东西：

• • AGENTS.md

• • docs/

• • decision records

• • bootstrap script

这四样东西，分别解决四个完全不同的问题。

第一件：AGENTS.md 只负责入口

一个好的 AGENTS.md 不该试图解释整个项目。

它只需要回答几个问题：

• • 这个仓库大致做什么

• • 核心目录分别负责什么

• • 改代码前优先看哪些文档

• • 哪些目录有局部规则覆盖

• • 哪些是硬约束，比如必须跑哪些测试、什么文件不要动、什么情况下要停下来确认

社区这两天有个总结很到位：好的 AGENTS.md 应该是简洁的导航文件，采用 progressive disclosure。顶部只给高层上下文，细节不要堆在这里，而是指向具体文件，让 Agent 按需展开 [3]。

翻成大白话就是：

别在一个文件里堆知识。

要开始给知识修路。

第二件：docs/ 负责系统事实

很多团队最大的误区，是把 AGENTS.md 当成事实源。

这恰恰是最危险的做法。

对 Agent 来说，真正可复用、可维护、可追踪的知识，应该活在结构化文档里。OpenAI 在 Harness engineering 里说得很明确：知识库应该放在结构化的 docs/ 中，作为系统事实来源 [1]。

这意味着，真正会影响改动判断的内容，比如架构边界、核心概念、产品流程、关键约束、依赖参考、验证方式，都应该有固定住处。

而不是散落在聊天记录里。

更不是散落在一个越来越肥的 AGENTS.md 里。

只要“重要事实有稳定地址”这件事做到了，Agent 的工作方式就会完全不同。

它不是先吞下一坨背景。

而是沿着地图，逐层查证。

第三件：decision records 负责解释“为什么不能乱改”

这层东西特别容易被忽略。

但它恰恰最能决定 Agent 到底会不会踩坑。

因为模型最容易犯的错误，从来不是不会写代码。

而是会把一些“看起来更优雅”的方案直接改上去，却完全不知道原来的代码为什么不能随便动。

有些模块丑，是因为历史数据兼容。

有些接口别扭，是因为外部系统已经绑定。

有些实现没抽象，不是因为团队不会写，而是因为另一条路以前已经试过，而且在生产上踩过坑。

这些信息如果只存在于会议纪要、聊天记录和资深同事脑子里，Agent 就一定会反复重蹈覆辙。

所以，关键决策必须版本化地留在仓库里。

它可以叫 ADR，也可以叫 RFC，也可以只是带日期、带结论、带替代方案的 decision log。名字不重要，重要的是 Agent 能顺着这些记录，理解今天的代码为什么会长成这样 [1]。

第四件：bootstrap script 负责让 Agent 别靠猜

这是很多团队最容易轻视的一层。

但实际收益非常大。

社区最近那篇帖子里，把 bootstrap script 放在第一条，不是没有原因 [3]。

因为对 Agent 来说，最浪费时间的事情之一，就是猜环境。

猜怎么装依赖，猜服务怎么起，猜数据库怎么初始化，猜测试命令到底是 npm test、pnpm test、make test，还是某个埋在脚本里的别名。

只要这些事情还靠猜，Agent 就还停留在“摸索进场”阶段。

这时候谈什么高阶协作，都是空的。

一个好的 bootstrap script，本质上不是便利工具。

它是 Agent 的进场协议。

理想状态下，Agent 进入仓库后，应该可以通过一个稳定入口完成四件事：

• • 安装依赖

• • 初始化本地环境

• • 启动必要服务

• • 跑最小验证路径

这条链路一旦打通，Agent 才真正具备独立开工的条件。

一个问题，就能看出团队有没有进入下一阶段

判断一个团队是不是在认真建设 Agent 友好的仓库，其实只要问一个问题：

如果今天来一个非常勤奋的新同事，只给他仓库本身，他能不能在短时间内找到关键事实、理解边界、跑通验证、避开旧坑？

如果答案是否定的，那 Codex 表现不稳定，往往就不是 prompt 不够强，而是仓库本身还没有被整理成一个可探索的知识系统。

这也是为什么 AGENTS.md 2.0 值得重视。

它真正改变的不是一个文件。

它改变的是整个团队组织知识的方式。

不要再试图把所有知识压进一个巨型入口。

更好的做法，是把仓库整理成一套分层知识结构，再让 AGENTS.md 成为这套结构的路由层。

当仓库本身变得可导航，模型才不会一路都要人扶着走。

最后

如果一个团队现在的 AGENTS.md 已经很长了，最不值得做的事情，就是继续往里补。

更值得做的，反而是四件事：

• • 把 AGENTS.md 缩回入口页

• • 把真正重要的事实拆进 docs/

• • 把关键取舍补成版本化决策记录

• • 给仓库补一个一键 bootstrap script

真正让 Codex 变强的，很多时候不是更会写 prompt。

而是更会整理项目。

这可能才是下一阶段 AI 编程真正的分水岭。

不是谁的提示词更长。

而是谁先把自己的代码库，整理成了一张真正可用的地图。

参考来源

[1] OpenAI, Harness engineering: leveraging Codex in an agent-first worldhttps://openai.com/index/harness-engineering/

[2] OpenAI Developers, Custom instructions with AGENTS.mdhttps://developers.openai.com/codex/guides/agents-md

[3] Reddit r/codex, 3 things you can add to your repo today to make Codex more robust/effectivehttps://www.reddit.com/r/codex/comments/1rwmkpy/3_things_you_can_add_to_your_repo_today_to_make/