Codex截断AGENTS.md规则实测，OpenAI自家仓库5473字节测试规范被丢弃

Codex 在启动时会沿项目目录层级向上拼接 AGENTS.md 文件内容作为上下文指令，但其默认预算仅为 32 KiB（32,768 字节）。一旦总长度超限，系统将从根目录开始依次读取并扣减预算，后续文件若余额不足则被截断或跳过——而这一过程仅在日志中留下一条 warning，用户界面完全无提示。

该机制已在多个本地测试与真实仓库中得到验证。以 OpenAI 官方维护的 openai-agents-python 仓库为例，其 AGENTS.md 总长为 38,241 字节，远超 32 KiB 上限。根据 codex-rs/core/src/agents_md.rs 中的实现逻辑，文件读取顺序为根目录 → 子目录，预算逐层消耗。最终结果是：指令文本在「Implement the」处被截断，后续约 5,473 字节内容（包括「Testing & Automated Checks」「GitHub-ready Output」及「Pull Request & Commit Guidelines」等关键开发规范）从未进入 agent 的上下文。

这一问题并非理论推测。开发者 Sertan Helvacı 于 10 月 20 日发表文章《How Big Can AGENTS.md and CLAUDE.md Get?》，首次系统梳理了 Codex 与 Claude Code 在指令文件处理上的差异。随后，有研究者通过源码分析与本地 CLI 实测（Codex CLI 0.162.1、Claude Code 2.1.304）进一步确认：Codex 的 project_doc_max_bytes 配置项默认值即为 32768，且读取逻辑采用“贪心式”预算分配——先加载的文件优先占用全部额度，后加载的文件可能连一个字节都读不到。

三层目录实测案例更具说服力：在一个模拟 git 项目中，根目录 AGENTS.md（29,981 字节）完整载入后剩余预算仅 2,787 字节；子目录 svc/AGENTS.md（3,936 字节）被截断至前 2,787 字节；最深的 svc/api/AGENTS.md（75 字节）因预算归零被完全跳过。三份合计 33,992 字节，超出上限 1,224 字节，恰好对应被截掉的部分。

值得注意的是，Codex 的设计与 Claude Code 形成鲜明对比。后者对单个 CLAUDE.md 文件支持最大 4 MiB 整体读入，超限则整份跳过；自 v2.1.277 起虽也兼容 AGENTS.md，但只要路径中存在 CLAUDE.md 或 CLAUDE.local.md，AGENTS.md 即被忽略。更关键的是，Claude Code 引入了明确的优先级规则：同一目录下，CLAUDE.local.md > CLAUDE.md > AGENTS.md；跨目录时，越靠近当前工作目录的文件优先级越高——这与 Codex “根目录优先”的逻辑相反。

这种差异直接影响开发体验。例如，在 svc/api 目录下编写新模块时，开发者可能专为此路径撰写一份 AGENTS.md，明确要求「必须通过单元测试」「输出需符合 JSON Schema」等约束。但在 Codex 下，若根目录已有大体积文档，该子目录规则将彻底失效，agent 仍按旧规则生成代码，导致后续 CI 失败或人工返工。

官方文档对此描述模糊：称“合计达到上限后停止添加文件”，却未说明跨界文件会被截半；同时声称“越近的文件 override earlier guidance”，实际行为却是子目录文件最先被丢弃。这种文档与实现的偏差，加剧了用户的误判风险。

需要强调的是，全局配置 ~/.codex/AGENTS.md 不计入 32 KiB 项目预算，它作为用户级指令单独注入。但项目级规则才是影响具体代码生成的核心依据，尤其在大型协作仓库中，子目录特化规则往往承载最关键的上下文约束。

当前行业对 AI 编程工具的依赖日益加深，而指令文件实质是嵌入上下文的“隐性 API”。当文件超过 30 KB，首要动作应是确认工具实际加载了多少内容，而非仅讨论文案是否精炼。OpenAI 自身仓库的案例极具警示意义：连自家团队编写的测试与提交规范都未能被 agent 看到，说明该问题已非边缘场景，而是影响工程落地的关键缺陷。

相比之下，Claude Code 的策略更贴近实际开发流：通过局部覆盖机制（如 CLAUDE.local.md）保障当前工作区的指令有效性，并避免因根目录文档膨胀导致深层规则失效。这也反映出不同团队对“上下文可控性”的理解差异——前者倾向集中管理，后者更重视局部自治。

值得补充的是，近期开源 AI 编程工具 OpenCode 遭遇安全事件（10 月 20 日披露），其 Console 平台约 1.4% 用户的第三方 API 密钥泄露，引发社区对 AI 工具链安全性的广泛质疑。尽管该事件与 Codex 的截断机制无直接关联，但它共同指向一个深层问题：当前 AI 编程代理的底层设计仍存在大量“黑盒”环节——从指令加载逻辑到密钥管理，从上下文截断策略到防御模型拒答行为，用户难以感知系统内部状态，更无法有效干预。

在 AI 编程走向工程化落地的阶段，此类细节缺陷的代价正在放大。当 agent 依据不完整的上下文生成代码，不仅降低效率，更可能引入隐蔽错误。修复方向明确：要么提升默认预算阈值（如增至 64 KiB 或支持动态扩展），要么改用优先级驱动的加载策略（当前目录优先），并强制在 UI 层面反馈截断位置与缺失内容摘要。否则，随着项目规模增长，AGENTS.md 的实用性将持续衰减，最终沦为形式化文档。

目前尚无官方更新计划公布。对于重度使用者，临时规避方案包括：压缩根目录文档、拆分规则至 CLAUDE.local.md（若使用 Claude Code）、或在 /config 中显式设置 project_doc_max_bytes 为更高值（需自行编译修改）。