在 Codex CLI 里运行 `/status`，如果 Agents 项显示 none，很多人会立刻判断 AGENTS.md 没有被读取。这个结论不一定准确：有时是启动目录和项目根目录不同，有时是文件名、文件位置或覆盖层级不符合发现规则，也可能只是状态显示与实际上下文没有同步。排查时应先确认 Codex 从哪里启动、沿哪条目录链寻找规则，再验证规则是否真的进入当前会话。

一、先确认是“没发现”还是“没遵守”

AGENTS.md 没有被发现，与文件已经加载但规则写得不够明确，是两类问题。前者通常表现为 `/status` 没有列出文件、让 Codex说明项目规则时答不出来；后者则可能能复述规则，却在复杂任务中执行不稳定。不要只凭一次行为就认定加载失败。

可以先写一条低风险、容易验证的临时规则，例如要求在开始修改前列出测试命令名称。重新打开一个新会话后给出小任务，看 Codex 是否遵守。不要放入“输出秘密口令”之类会污染正式内容的测试语句，验证结束后及时删除临时规则。

二、核对当前目录和项目根目录

Codex 会从当前工作目录向上寻找项目边界和配置。你以为终端位于仓库根目录，实际可能停在父目录、符号链接目录或另一个 worktree。先用系统命令确认当前绝对路径，再检查该路径是否属于预期 Git 仓库。多仓库工作区尤其容易把一个目录的规则误认为会自动作用于所有仓库。

如果通过快捷方式、IDE 终端或脚本启动 Codex，也要检查这些入口是否改变了工作目录。最稳妥的验证方法，是先明确切换到仓库根目录，再启动新的 Codex 会话。旧会话不会因为你在外部切换目录就自动重新计算整条规则链。

三、文件名、编码和实际扩展名要正确

文件应当真正命名为 `AGENTS.md`。Windows 资源管理器隐藏扩展名时，文件可能实际叫 `AGENTS.md.txt`；大小写敏感的文件系统还要注意字母形式。用命令列出目录内容，比只看编辑器标签更可靠。

文本应使用常见编码并具有读取权限。若文件来自网络盘、加密目录或容器挂载，当前进程可能只能看到占位文件。先用与 Codex 相同的用户身份读取文件，确认不是空文件，也没有被同步软件锁定。

四、理解全局、仓库和子目录的加载顺序

个人通用规则可以放在 Codex 主目录下，团队规则通常放在仓库中，子目录还可以有更具体的 AGENTS.md。越靠近当前工作目录的规则越具体，发生冲突时通常由更具体的规则覆盖上层说明。它不是把所有文件简单拼在一起后逐字执行。

因此，仓库根目录要求“修改后运行全部测试”，子目录文件却写成“只运行单元测试”，当前任务位于该子目录时就可能采用后者。排查时沿当前目录逐级向上列出所有 AGENTS.md，不要只检查你刚编辑的那一个。

五、检查 AGENTS.override.md 是否改变结果

覆盖文件适合临时替代同一层的常规规则，但也容易被遗忘。某个目录存在 AGENTS.override.md 时，可能让你对 AGENTS.md 的修改看起来完全不生效。查找时应同时搜索两种文件名，并记录各自所在层级。

不要把覆盖文件长期当作隐蔽开关。临时实验结束后，应把有效规则合并回正式文件或删除覆盖层。团队仓库中若确实需要覆盖，最好在文档中说明用途、责任人和移除条件。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成代码修改、测试和审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

六、规则文件修改后要新建会话验证

AGENTS.md 通常在会话启动和上下文构建阶段被读取。会话进行到一半才修改文件，当前上下文未必立即按新内容工作。排查时保存文件，退出当前会话，再从确定的目录启动新会话，这比连续追问“你看到了吗”更能说明问题。

如果必须在长任务中更新规则，应明确告诉 Codex重新读取对应文件，并对关键限制重新确认。不过正式团队流程仍建议把规则固定后再开始任务，避免一个会话前后使用两套标准。

七、让规则短、具体、可执行

加载成功不等于每句话都能稳定执行。像“写出高质量代码”“注意安全”太宽泛，模型很难据此选择具体动作。更有效的写法是列出允许修改的目录、常用测试命令、格式化命令、禁止提交的文件以及验收步骤。

规则过长时，重要限制容易被大量背景说明淹没。把架构介绍放到单独文档，在 AGENTS.md 中只保留任务必须知道的入口和链接。相互矛盾的要求要删掉，不要同时写“任何时候都先询问”和“自动完成所有修改”。

八、用实际行为而不是状态栏单点验收

`/status` 是有用线索，但最终应通过行为确认。让 Codex读取一个受规则约束的文件、说明将运行哪些验证、完成一个极小改动并展示结果。若行为正确而状态仍显示 none，保留版本号、启动目录和最小复现，再判断是否属于界面显示问题。

若行为也不正确，就按目录、文件名、覆盖文件、会话刷新和规则冲突的顺序逐项排查。每次只改变一个变量，避免同时移动文件、更新客户端和重写内容，否则无法知道哪一步真正有效。

九、团队环境建立固定验收清单

团队可以在仓库初始化文档中写明 AGENTS.md 的位置、允许的子目录覆盖方式和验证命令。新成员克隆项目后，先从仓库根目录启动 Codex，查看状态，再执行一个只读任务。这样能在真正修改代码前发现路径或权限问题。

最终清单应包含：当前绝对路径正确、项目根目录正确、文件名无隐藏扩展名、内容可读、没有意外 override、已重新建立会话、规则之间没有冲突，并且实际任务能体现关键约束。完成这些检查后，即使状态显示曾经异常，也能准确判断规则到底有没有进入工作流。