AGENTS.md 不生效？从读取路径、覆盖规则到内容截断逐步排查

你已经在 AGENTS.md 写了“使用 pnpm”“不修改生成文件”或“完成后运行测试”，Codex 却仍做了相反的事。先别继续往文件里加规则：没有加载到这份文件，与加载了但执行偏离，需要不同的排查方法。

本文以官方说明中的 Codex CLI 指令发现机制为主。先用一个只读任务找出加载路径，再定位覆盖、截断和会话更新问题。需要从头写规则时，查看AGENTS.md 中文指南与最小模板。

先做一次只读验证，不靠“它说读过了”判断

在出现问题的项目目录中，开启一次新的 CLI 会话，并提出下面的任务：

不修改任何文件，不安装依赖，不运行构建或测试。先说明当前工作目录，再列出本次任务适用的 AGENTS.md、AGENTS.override.md 与已配置的替代规则文件。逐项说明路径和适用范围，引用与包管理器、禁止修改目录、验收命令有关的原文。区分启动时已加载的规则与本次主动读取的文件；无法确定的项目直接说明。

预期结果： 路径与你的实际仓库一致，引用的规则确实存在，当前子目录规则也被纳入判断。仅复述“我会遵守规则”，不足以证明加载正确。

模型列出的来源可帮助排查，但不属于完整的底层加载日志。重要规则应结合下面的发现顺序核对；之后再用小范围任务观察是否执行。

验证结果	下一步
完全没有提到你写的文件	检查启动目录、文件名和配置目录
提到了另一个同名文件	检查实际仓库、worktree 与 `CODEX_HOME`
读到了文件，但规则内容不同	检查 override、子目录覆盖与旧会话
文件开头的规则出现，后面的没有	检查合并指令长度
来源和规则都正确，行动仍偏离	转到“已加载但没有照做”一节

1. 启动目录是否就在规则的作用范围里？

在 CLI 启动前确认目录。macOS/Linux 使用 pwd；PowerShell 使用 Get-Location。如果是 Git 仓库，可以再用下面的只读命令确认根目录：

git rev-parse --show-toplevel

官方的项目发现路径是从项目根目录向下走到当前工作目录，而不是搜索所有子目录。每个目录最多选一份规则文件。

例如，仓库是下面的结构：

my-project/
  AGENTS.md
  frontend/
    AGENTS.md
  backend/
    AGENTS.md

从 frontend 启动时，会沿这条路径考虑根目录和前端规则；不能因为后端文件存在，就认定后端规则也已加入启动时的指令链。从错误的同名仓库或 worktree 启动，也会得到不同的规则。

处理方法： 进入真正需要工作的目录，再重新启动 CLI。也可明确指定启动目录：

codex --cd /path/to/my-project/frontend

将示例路径替换为实际路径。重新运行只读验证，确认根目录和适用的子目录来源，而不只是检查文件“在不在”。

2. 文件名、位置与内容是否正确？

先检查以下三项：

文件名确实是 AGENTS.md，没有变成 AGENTS.md.txt。跨系统时也保持大小写一致，避免依赖本机文件系统的宽松匹配。
文件位于发现路径上，而不是只放在 docs/、备份目录或一个本次没有进入的子目录。
文件有实际内容。空文件不会提供项目规则。

普通 Markdown 标题和列表即可，不需要为了加载而增加 YAML 头或特殊 JSON 格式。如果仓库使用 TEAM_GUIDE.md 等其他名字，必须通过 project_doc_fallback_filenames 配置替代文件名，不能假定 Codex 会自动识别任意命名。

验证结果： 新会话的只读核对能引用这份文件的独有规则。此时再检查覆盖，而不是继续换文件格式。

3. AGENTS.override.md 或子目录规则是否覆盖了预期？

官方说明的查找顺序是：

在 Codex 配置目录中，优先考虑 AGENTS.override.md，否则考虑 AGENTS.md；这一层只使用第一份非空文件。
在项目根目录到当前目录的每一层，依次检查 AGENTS.override.md、AGENTS.md 和配置的替代文件名；每层最多选一份。
按根目录到子目录合并。更接近当前工作目录的规则可以覆盖前面较宽泛的指导。

因此，同一目录中的 override 与普通文件，不是“两份都会读”。例如根目录要求 npm，当前子目录规则要求 pnpm，这应先按局部约定检查，而不是直接认定根文件没有生效。

处理方法： 对照真实的文件树，找出实际被选中的文件，以及发生冲突的具体一句话。先阅读 override 的用途，不要为了排查直接删掉团队规则。确认是过期覆盖后，再由维护者修正对应规则。

验证结果： 同一个小任务的适用规则能解释清楚；包管理器、禁止目录和验收命令不再互相冲突。

4. 编辑的是不是当前进程使用的 CODEX_HOME？

全局规则默认位于 ~/.codex，但 CODEX_HOME 可以指定其他配置目录。IDE、终端、容器或不同系统用户的进程环境也可能不同。

macOS/Linux 可只检查目录变量：

printenv CODEX_HOME

PowerShell：

$env:CODEX_HOME

没有输出通常表示变量未设置，应按默认配置目录检查；有输出时，到那个目录核对全局规则和配置。这里检查的是路径，不需要读取或分享 auth.json。

处理方法： 保持你原本需要使用的配置目录，在对应目录维护规则。不要为了让一份全局文件生效而随意切换 profile、复制凭据或覆盖整套配置。

验证结果： 重新启动后的来源核对，与当前配置目录及仓库规则一致。

5. 指令是不是被长度上限截断了？

官方文档说明，合并的项目指导受到 project_doc_max_bytes 限制，默认是 32 KiB。这是字节限制，不能把它简单理解为“32,000 个中文字符”，也不能只看某一份文件的长度。

如果规则文件很多，前面的内容被加载、后面重要约定没有出现，先检查发现路径上的合并内容。把关键规则放在容易核对的位置，删除过期和重复约定，将专属要求放进真正适用的子目录。拆分目录的同时仍需确认本次发现路径，不能只拆文件而不核对作用域。

确实需要更大容量时，可在实际使用的配置中调整，例如：

project_doc_max_bytes = 65536

这只是配置示例，表示 64 KiB，不建议将“不断增大上限”作为第一步。先让规则简短、明确且互不冲突，再评估容量。

验证结果： 新会话能引用原来缺失的关键规则；同时检查前面的规则是否仍完整。不能只凭“没有警告”判断不存在截断。

6. 修改规则后，是否仍在使用旧会话？

官方说明，指令链在启动时建立，CLI 的 TUI 通常对应一次启动的会话。编辑文件后不要假设正在运行的会话已经自动更新了启动指导。

处理方法： 完成并保存当前工作，退出 CLI，再从目标目录重新启动，运行开头的只读核对。这是检查加载更新，不需要清空缓存目录或删除会话。

如果旧任务还要继续，可以先查看恢复上次会话的方法。恢复任务后仍应重新核对当前适用规则，不依赖旧对话里曾经说过的约定。

验证结果： 新会话引用的是修改后的规则。若仍引用旧内容，回到目录、配置目录和 override 检查。

规则确实加载了，但 Codex 还是没有照做怎么办？

这时要检查规则能否转化成明确行动，以及本次任务有没有更新或冲突的要求。

例如“保证代码质量”难以验证；“修改 TypeScript 后运行 npm run check，失败时说明原因”才有可观察的结果。规则里写了一个仓库不存在的命令，也不能通过继续强调“必须执行”修好。

选择一个低风险的小任务，明确允许修改的范围、适用规则和验收标准，检查实际 diff 与命令结果。不要仅以它是否生成 .ts 文件作为加载证明：任务本身就可能要求 TypeScript。

能引用正确规则，但行动错误：指出违反的具体条目，要求解释冲突并修正；检查改动和验证记录。
规则互相矛盾：由项目维护者统一约定，再从新会话复测。
验收命令不可用：先修正仓库事实，或说明环境限制，不伪称测试通过。

更多规则设计方法见AGENTS.md 中文指南。本文聚焦已经写好规则后的加载和执行排障，不再复制一份通用模板。

排查完成检查表

结束前确认：工作目录正确、文件名和内容有效、override 与子目录关系已解释、当前配置目录正确、关键规则没有超出长度限制、重新启动后能核对新规则。

然后检查一个实际小任务的行为。“来源正确”与“行动正确”都通过，才说明你要解决的问题已经得到验证。

仍有问题时，提供版本、脱敏后的目录层级、规则文件名、与故障有关的少量规则和复现步骤；不需要提供完整项目或认证文件。其他环境问题可参考Codex 常见故障排查。