夜雨聆风上周有个同事跑来找我，说他用 Codex 写了一下午代码，来回改了十几遍，最后还是自己手动重写的。他吐槽说："AI 写的代码总差点意思，好像懂了又好像没懂。"
我看了下他的项目目录——没有 AGENTS.md，没有架构文档，API 规范散落在三个不同的 Confluence 页面里，最近一次更新停在半年前。
这不是 Codex 的问题，是你没给它足够的上下文。
阿里巴巴技术团队做过一个统计：AI 编码的平均采纳率只有 30% 左右。但通过建立结构化的文档体系，这个数字能拉到 80%。差距就在文档。
而 Codex 从设计之初就内置了对 AGENTS.md 的支持——这个文件会在每次运行时自动加载，是 Codex 理解项目的第一入口。
先搞清楚：AGENTS.md 到底是什么
2025 年之前，AI 编程工具的配置文件各自为政：Copilot 用 .github/copilot-instructions.md，Cursor 用 .cursorrules，Claude Code 用 CLAUDE.md。同一个项目要维护好几份内容几乎一样的配置。
2025 年 5 月，AMP 团队提出 AGENT.md（单数），OpenAI 随后提出 AGENTS.md（复数）。最终 AMP 主动让步，行业迅速收敛到 AGENTS.md。
截至 2025 年底，GitHub 上已有超过 60,000 个开源项目采用 AGENTS.md。该标准现由 Agentic AI Foundation（AAIF）在 Linux Foundation 下维护，AAIF 由 OpenAI、Anthropic、Google、Microsoft、AWS 等共同创立。
AGENTS.md 已被主流AI编程工具采纳
数据来源：agentsmd.io 行业报告
一句话总结：AGENTS.md 是面向 AI 的项目说明书，放在仓库根目录，Codex 每次运行自动读取。
Codex 怎么读 AGENTS.md
这是 Codex 和其他 AI 工具最大的区别——分层发现机制。Codex 不是只读一个文件，而是从全局到项目到子目录，逐层构建指令链。
Codex 指令发现链：从全局到当前目录
数据来源：OpenAI Codex 官方文档
几个关键规则：
每层最多取一个文件。Codex 在每个目录先找 AGENTS.override.md，找不到再找 AGENTS.md。override 文件优先，适合做临时覆盖。
越靠近当前目录，优先级越高。合并时从根向下拼接，后出现的指令覆盖前面的。所以子目录的规则可以覆盖根目录的通用规则。
总大小上限 32 KiB。超过就截断。可以通过 project_doc_max_bytes 调大，但更好的做法是拆分到子目录。
支持自定义 fallback 文件名。在 ~/.codex/config.toml 里配 project_doc_fallback_filenames，就能让 Codex 识别你已有的 TEAM_GUIDE.md 等文件。
AGENTS.md 应该写什么
社区实践总结出六个核心方向，建议控制在 150 行以内。先看整体结构：
一个实际的 AGENTS.md 长什么样：
# AGENTS.md## 项目概述TypeScript monorepo，pnpm workspaces，React 电商平台。## 命令- 安装依赖: pnpm install- 启动开发: pnpm dev- 运行测试: pnpm test- 代码检查: pnpm lint## 代码风格- TypeScript strict 模式- 单引号，无分号- 函数式编程优先- 组件放 src/components## 安全- 禁止提交 API Key- 敏感配置用环境变量- 发版前跑 pnpm audit## 边界- 不要修改 legacy/ 目录- 改 config.yaml 需要确认
数据说话：有 AGENTS.md 到底提升多少
ambient-code 团队在 GitHub 上发布了一份超过 50 个权威来源的研究报告。数据很硬：
Codex 代码采纳率对比
数据来源：ambient-code 研究报告
有 AGENTS.md vs 无：多维效率提升
数据来源：ambient-code / 斯坦福大学 / 微软研究院
还有两个数字值得注意。微软的 ConfigGen 工具能自动生成 AGENTS.md，达到人工编写 89% 的有效性，时间从 45 分钟缩短到不到 2 分钟。GitHub 正在推动 CLAUDE.md、copilot-instructions.md 和 .cursorrules 的统一，同一份 AGENTS.md 适配多个 AI 工具的兼容性提升 23%。
阿里技术团队的实践也印证了这一点。他们通过建立分层文档体系（全局层、项目层、模块层、需求层），将 AI 代码采纳率从 30% 提升到 70%-80%。这跟 Codex 的分层发现机制正好对应——全局 ~/.codex/AGENTS.md、项目根 AGENTS.md、子目录 AGENTS.override.md。
他们总结的时间分配：30% 花在项目上下文文档，30% 在核心模块文档，20% 在功能实现，20% 在代码审查。60% 的时间在"写文档和设计"，真正编码只占 20%。
这和传统软件工程的规律一致：需求分析阶段发现问题的修复成本，远低于编码后发现问题的成本。AI 时代只是把这个规律放大了——因为 Codex 的"返工"比人类更快，但也更容易出错。
怎么建立 Codex 可更新的文档
文档最大的敌人不是写不好，而是写着写着就过时了。Codex 的解法是：让 Codex 自己来维护。
Codex 文档自动化更新流程
具体四步走：
第一步：创建全局 + 项目 AGENTS.md
先建全局文件，放跨项目通用偏好：
# ~/.codex/AGENTS.md## Working agreements- 修改 JS 文件后跑 npm test- 依赖安装优先用 pnpm- 加生产依赖前先确认
再建项目根目录的 AGENTS.md，放项目级规范。验证是否生效：
codex --ask-for-approval never \"Summarize the current instructions."
Codex 会回报它加载了哪些指令文件，从全局到项目按顺序列出。
第二步：用子目录 override 做模块级覆盖
在 services/payments/ 下放一个 AGENTS.override.md，写支付模块的特殊规则。Codex 从这个目录启动时，会自动加载全局 + 项目根 + 这个 override，后者优先级最高。
第三步：代码提交时触发文档更新
CI/CD 流水线中加入文档更新环节。开发者提交代码时，Codex 扫描变更内容，更新对应的 AGENTS.md 部分。比如新增了 API 接口，自动在文档中补充说明；修改了测试框架，自动更新测试命令。
第四步：定期校验文档与代码一致性
Codex 每次运行重建指令链，修改 AGENTS.md 后无需清缓存，重启即可生效。设置定时任务让 Codex 对比文档描述和代码实际状态，发现不一致就提醒。分层格式能减少 42%-58% 的上下文窗口消耗。
有 AGENTS.md vs 没有：真实的效率差距
用一个具体场景说明。假设你要在一个中型电商项目中新增一个"优惠券核销"功能，用 Codex 来开发：
| 30-40% | 70-80% | |
Codex 完成同一功能的时间分配对比
基于阿里技术团队实践数据估算
没有 AGENTS.md 时，你花在"解释上下文"和"返工修改"上的时间占了 40%。有了文档，这部分压缩到 15%。省下来的时间，全部回到了有效编码上。
已有 CLAUDE.md / .cursorrules 怎么迁移
很简单，改个名就行。或者用符号链接保持兼容：
# 直接改名mv CLAUDE.md AGENTS.mdmv .cursorrules AGENTS.md# 或用符号链接保持兼容ln -s AGENTS.md CLAUDE.mdln -s AGENTS.md .cursorrules
如果你的项目已经有 TEAM_GUIDE.md 等自定义文件名，在 Codex 配置里加 fallback：
# ~/.codex/config.tomlproject_doc_fallback_filenames = ["TEAM_GUIDE.md",".agents.md"]project_doc_max_bytes = 65536
Codex 在每个目录的查找顺序就变成：AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md。
写在最后
说句实话，Codex 的能力已经很强了，真正卡脖子的不是模型，是你给它什么上下文。
AGENTS.md 这个标准之所以能在半年内被 60,000 个项目采纳，不是因为它技术多复杂——它就是个 Markdown 文件。而是因为它解决了 AI 编程最根本的问题：上下文不对称。
最实际的建议：如果你现在还没有 AGENTS.md，先从仓库根目录建一个开始。把你项目的技术栈、构建命令、测试命令、不能碰的目录写进去。就这一个文件，就能让 Codex 的代码采纳率提升 21 个百分点。
然后用 codex --ask-for-approval never "Summarize the current instructions." 验证一下是否生效。
逐步补齐子目录的 override、测试策略、安全边界。不需要一次到位，但要从现在开始。
AGENTS.md 不是负担，是 Codex 的杠杆。
