Codex AGENTS.md教程：项目规则、读取范围与生效检查

它解决什么、不解决什么

AGENTS.md 保存会在多个任务中重复使用的项目约定：项目用途、目录边界、真实命令和完成标准。它不能代替当前任务提示、config.toml、沙箱、操作系统权限、审批或人工验收。写“不要删除文件”也不是安全隔离保证。

• 长期项目规则放 AGENTS.md。
• 当前目标和范围写在本次任务提示。
• 模型、审批和沙箱设置放 config.toml 或命令行。
• 规则是否生效要用路径、diff、命令输出或页面检查证明。

读取范围与覆盖顺序

官方当前规则是：全局 CODEX_HOME 层先取 AGENTS.override.md，否则取 AGENTS.md；项目从 Git 根目录走到当前目录，每级按 override、AGENTS.md、fallback 文件名查找且最多取一个；规则从根到近处合并，近处规则后加入并可覆盖前面的约定。合并大小默认受 project_doc_max_bytes 的 32 KiB 限制。规则链在一次运行或 TUI 会话开始时建立。

创建一个无依赖练习副本

练习项目只有 index.html，没有 package.json、Node 或测试脚本，所以不编造 npm test。

probe="$(mktemp -d /tmp/codex-agents-probe.XXXXXX)"
cat > "$probe/index.html" <<'HTML'
<h1>第一次修改前</h1>
<p>这是一份可回滚的本地网页副本。</p>
HTML
cat > "$probe/AGENTS.md" <<'RULES'
# 练习项目规则
- 本次只允许修改 index.html。
- 修改后检查 git diff --check。
- 项目没有测试脚本，不要运行 npm test。
RULES
git -C "$probe" init -q
git -C "$probe" add index.html AGENTS.md
git -C "$probe" commit -qm "建立练习基线"

先读规则，再做一个小修改

先让 Codex 在只读会话中列出实际读取的 AGENTS.md 路径，再让它只改 h1。模型回复只是线索，真正的验收由你查看差异完成。

codex exec --ephemeral --sandbox read-only -C "$probe" "先不要修改。列出实际读取的 AGENTS.md 路径和可运行的检查命令。"
codex exec --ephemeral --sandbox workspace-write -C "$probe" "把 index.html 的 h1 改成‘规则已生效’，只修改这个文件；完成后说明实际检查。"
git -C "$probe" status --short
git -C "$probe" diff --name-only
git -C "$probe" diff --check

• 正常应只有 index.html 出现在差异中。
• git diff --check 没有输出表示没有空白错误，不等于页面一定正确。
• 未登录或无法联网时，Codex 任务会停在认证或网络阶段，应标为未验证。

检查子目录覆盖和实际作用

用 find、git rev-parse 和 pwd 确认规则文件、项目根和启动目录；如果创建子目录 override，从该目录启动下一次 Codex，再比较规则来源。

find "$probe" \( -name 'AGENTS.md' -o -name 'AGENTS.override.md' \) -print
git -C "$probe" rev-parse --show-toplevel
pwd

没生效时的检查顺序

先查目录和文件名，再查同层 override、规则覆盖范围、文件大小和 CODEX_HOME，最后重启一次运行。不要把“我已读取”当作验证成功。

• 确认启动目录在目标项目内，且不是另一个 Git 根。
• 确认文件不是 AGENTS.md.txt，也不是空文件。
• 确认同层 override 或 fallback 配置没有替换预期文件。
• 用 git diff --name-only、实际命令输出和页面检查核对效果。

修改或移除规则

先复制 AGENTS.md，编辑后看 diff；确认新运行已经读取，再删除备份。移除练习规则时检查父目录和 CODEX_HOME 是否还有同名规则，不要直接删除真实项目或用户目录中的文件。

cp "$probe/AGENTS.md" "$probe/AGENTS.md.bak"
$EDITOR "$probe/AGENTS.md"
git -C "$probe" diff -- AGENTS.md
rm "$probe/AGENTS.md.bak"

和 config.toml 衔接

AGENTS.md 负责项目协作规则，config.toml 负责运行配置。需要配置来源、覆盖和只读探针时继续阅读Codex config.toml配置指南；需要权限边界时阅读权限与安全边界。官方 AGENTS.md 文档于 2026-09-22 核对；本轮（2026-09-23）本地 CLI 版本为 0.156.0，模型调用、App、IDE 和浏览器展示未在本轮完成验证。