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 不仅能被读取还能保持短、准、可执行不会随着项目增长变成一份无人敢改的长文档。
)
