Codex AGENTS.md 内容被截断怎么办？project_doc_max_bytes、嵌套规则和加载验证
Codex 明明发现了 AGENTS.md，却只遵守前半部分规则，后面的测试命令、目录边界或代码审查要求像是没有看到，这种情况很可能与项目说明总大小有关。Codex 会从全局目录到项目根目录，再沿着当前工作目录逐层组合说明文件；组合内容达到 `project_doc_max_bytes` 限制后，后续内容可能无法进入首轮指令。解决问题不能只把限制调大，还要检查加载顺序、嵌套文件和规则密度，确认关键要求是否真的到达当前会话。
一、先判断是截断还是规则冲突
被截断的典型表现是：文件前面的规则稳定生效，越靠后的内容越容易消失；换到更浅的目录后情况改变；删掉一段长说明后，原本失效的尾部规则又出现。规则冲突则不同，Codex 可能同时读到了两条相反要求，最终采用离当前目录更近的那一条。
不要仅凭一次回答判断。启动一个全新会话，让 Codex 按来源顺序概括当前指令，并特别复述你怀疑缺失的规则。如果它能复述却执行不一致，应继续检查任务表述和优先级；如果完全看不到某一段，再查大小限制和发现路径。
二、理解 project_doc_max_bytes 的范围
`project_doc_max_bytes` 限制的是组合进首轮项目说明的字节数，不是单个文件的字符数。中文在 UTF-8 中通常占多个字节，因此看起来不算很长的中文说明，也可能比同样字符数的英文文件更早达到限制。默认值面向精炼规则，不适合把整套架构文档、接口说明和会议纪要全部塞进 AGENTS.md。
这个限制还会覆盖从项目根到当前目录收集到的多层文件。全局 AGENTS.md、仓库根文件、子目录说明加在一起计算时，某个文件单独看没有超限，组合后仍可能截断。排查时要看完整链条，而不是只统计当前文件。
三、确认 Codex 实际从哪里开始搜索
项目根通常由 Git 根目录等标记决定。若你从错误目录启动，Codex 可能把另一个位置当成根，加载链条也会变化。先查看当前工作目录和识别到的项目根，再列出从根到当前目录之间存在的 `AGENTS.override.md`、`AGENTS.md` 和配置的备用文件名。
如果找不到项目根，Codex 可能只检查当前目录。反过来，在大型 monorepo 的深层目录启动，会组合多层规则。不要假设打开了同一个仓库就一定得到同一套说明，启动目录本身就是加载结果的一部分。
四、掌握 AGENTS.override.md 的覆盖关系
在同一目录层级，`AGENTS.override.md` 的优先级高于普通 `AGENTS.md`，并且只采用第一个非空候选。有人为了临时调试创建 override 后忘记删除，之后再改普通文件自然看不到效果。全局 Codex 目录下也可能存在 override，影响所有项目。
逐层检查时要记录文件名和内容大小。不要同时保留含义相反的规则，再指望模型自行判断哪个是“最新”。临时覆盖应有明确用途和删除时间，团队共享仓库不宜把个人机器上的全局 override 当作隐形前提。
五、合理提高 project_doc_max_bytes
如果项目确实需要更多规则，可以在正确的 `config.toml` 层设置更高的 `project_doc_max_bytes`，然后重新启动 Codex。配置只在新运行或新 TUI 会话建立说明链时生效，旧会话不会自动重新读取全部项目说明。修改后应再次让 Codex 列出来源并复述关键项。
提高上限不是越大越好。说明过长会占用上下文，让真正的任务、代码和测试输出获得更少空间。先删除重复背景、过时流程和可以通过链接按需读取的资料，再考虑从 32 KiB 调到更合适的值。规则文件应像工作协议，而不是知识库全文。
如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成项目规则配置、代码修改和测试审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg
六、把规则拆到真正相关的子目录
嵌套规则最适合解决 monorepo 中不同模块要求不同的问题。仓库根只写通用命令、提交约定和安全边界；前端目录写前端测试与样式规则；支付服务目录写该服务专属的验证和禁改区域。Codex 从根向当前目录合并，越靠近工作目录的规则越具体。
拆分不是把一份长文件机械切成十份。每个子目录只保留对该范围有意义的内容，否则从深层目录启动时仍会把所有段落组合起来。通用规则只出现一次，局部差异放在最近层级，既能减少字节，也能降低冲突。
七、备用文件名配置要谨慎
`project_doc_fallback_filenames` 可以让 Codex 在没有 AGENTS.md 时读取团队已有的说明文件，例如 `TEAM_GUIDE.md`。它是按顺序检查的备用列表，不是把所有文件都无条件追加。文件名拼写、大小写和所在层级不正确，都会造成“看起来有文件但没有加载”。
不要把 README.md 之类内容庞杂的文件随意设为备用说明。README 可能包含安装介绍、徽章和大量示例，很快吃掉字节额度。更稳妥的做法是建立短而明确的工程规则文件，再从中指向需要按需阅读的文档。
八、验证时要使用新会话和明确问题
Codex 通常在每次运行开始时建立说明链，因此修改文件后应新开会话。让它回答三个问题：加载了哪些说明文件、各自适用哪个目录、当前任务必须执行哪些测试。再给一个只读任务，观察它是否主动提到关键边界。
若需要进一步审计，可以启用本地 TUI 日志或查看最近会话记录，但不要把包含密钥的内容发到公共位置。验证重点是来源、顺序和结果，不是要求模型逐字打印全部内部指令。关键规则能被准确复述并在小任务中执行，才算加载成功。
九、把高优先级规则放在清晰位置
即使没有达到字节上限，冗长说明也会降低执行稳定性。把不可违反的安全边界、必跑测试和禁止修改目录放在对应文件的显眼位置，用短句写清条件和动作。背景解释可以放到独立文档，需要时再让 Codex 读取。
避免使用模糊表达，例如“尽量保证质量”“适当测试”。改成可验证的要求：修改某目录后运行哪个命令，失败时停止什么动作，提交前检查哪些文件。规则越具体，越容易区分是没有加载，还是执行结果不符合要求。
十、形成一套可复查的说明结构
团队可以定期统计各层说明文件大小，清理重复内容，并为关键目录做加载测试。新增规则时说明归属层级，避免所有人都往根文件末尾追加。项目升级、测试命令变更或目录迁移后，也要同步更新规则。
最终排查顺序应是：确认工作目录与项目根，列出说明链，检查 override，统计组合字节，精简或拆分规则，必要时调整 `project_doc_max_bytes`，新开会话验证。这样处理后，AGENTS.md 不仅能被读取，还能保持短、准、可执行，不会随着项目增长变成一份无人敢改的长文档。