AGENTS.md 层级与覆写验证

返回 Codex 教学总目录

目标与准备

AGENTS.md 保存对工作的指示，config.toml 保存应用设定；两者不是同一个覆写机制。这次用回复标记与必须保留的共同要求观察规则，不提高沙盒权限，也不要求模型执行未知命令。能复述某个档案，仍不等于它在启动时自动载入，所以要同时看实际回复行为与工作目录。

先看载入顺序

全域规则预设位于使用者目录的 .codex；若已有 CODEX_HOME，则以其指向位置为准。专案规则从辨识到的根目录往目前工作目录走，不会一次遍历所有兄弟资料夹。每一层依档名优先检查 AGENTS.override.md，再找 AGENTS.md，最后才是已设定的备援档名；同层最多取一份。较深层的指示可覆写前面冲突项目，没有冲突的共同要求仍保留。

步骤一：建立独立规则实验室

在自己的练习位置建立新的 codex-rules-lab，里面再建 ui 与 data 子资料夹。先不要建立 override。用编辑器开启这个新资料夹，在整合终端机确认位置：PowerShell 用 Get-Location，macOS／Linux 用 pwd。确认没有同名既有专案后，在这个新资料夹执行下列 Git 初始化；它只用来让练习有明确专案根目录，不需要提交或连接远端。

git init
git rev-parse --show-toplevel

在根目录新增 AGENTS.md，贴入第一份完整内容。ROOT-LAB 是方便观察的回复前缀，KEEP-DATA 则是各子目录都应保留的共同要求。这些标记只服务练习，正式规则应改写成实际测试、资料保留与交付要求。

# Root practice instructions

- Start the final answer with ROOT-LAB.
- Include KEEP-DATA in the final answer.
- Do not change any files for the rule-discovery exercise.
- Report checks that were actually performed separately from unverified claims.

在 ui/AGENTS.md 放第二份完整内容，在 data/README.md 放下面的资料说明。README 刻意不是 AGENTS 档，没有另外设定备援档名时，不应只因为同为 Markdown 就加入启动指示。先检查每份档名大小写与副档名，避免 Windows 编辑器默默补上 .txt。

# UI practice instructions

- Start the final answer with UI-LAB instead of ROOT-LAB.
- Include UI-BASE in the final answer.

# Data notes

This folder describes fictional practice data.
DATA-NOTE is a document marker, not a required answer prefix.

步骤二：从两个目录各启动一次

在实验室根目录的系统终端机先执行第一个启动命令；它把这次 CLI 限制为唯读。进入 Codex 后送出下方自然语言要求，不另外贴规则内容或指定应有前缀。预期回复从 ROOT-LAB 开始并包含 KEEP-DATA。再用 /exit 回到系统终端机，不要用 resume 接续刚才任务，改执行第二个命令从 ui 开全新工作阶段。

codex --cd . --sandbox read-only

Without changing files, report the current working directory and the project instruction sources already available to this session. Follow the active response-format instructions. Do not search unrelated sibling folders just to collect more rules. Distinguish known loaded instructions from files you have not inspected.

codex --cd ui --sandbox read-only

在 ui 工作阶段送出完全相同要求。预期前缀改成 UI-LAB，仍有 KEEP-DATA，并增加 UI-BASE。这代表子目录覆写前缀，根目录不冲突的要求仍在。若它只能在你要求手动读档后才说出规则，请把「手动读到」和「启动已载入」分开记录；模型自述不是载入日志，不要把不确定的状态标成成功。

步骤三：加入同层 override 再比较

退出 ui 工作阶段，保留 ui/AGENTS.md，再新增 ui/AGENTS.override.md，内容如下。回实验室根目录，重新执行 codex --cd ui --sandbox read-only，送出同一个要求。预期 UI-OVERRIDE 与 KEEP-DATA，这次不应因同层 AGENTS.md 而加入 UI-BASE。override 取代的是同一层候选，不是把根目录与所有全域要求全部清空。

# UI override practice

- Start the final answer with UI-OVERRIDE instead of ROOT-LAB.
- Include OVERRIDE-ACTIVE in the final answer.

多做一个边界检查：保留 override 备份后清空、储存并开新工作阶段，记录实际载入结果。本机 codex-cli 0.154.0-alpha.6.2 的诊断输入显示，空 override 不提供内容，但也没有接著载入同层 AGENTS.md，只留下根目录规则；不要把空档当作可靠的停用方法。要恢复 ui 规则，将 override 改名为不在备援清单内的 override.saved.md，再开全新工作阶段确认 UI-LAB、UI-BASE、KEEP-DATA。不要删除全域档或整个设定目录。

用一张观察表分开载入与遵循

每次新启动都填下面栏位，分别记 ROOT-LAB、UI-LAB、UI-OVERRIDE、空 override 与改名还原。不要把期望值先写进「实际回复」。例如诊断输入包含 ui override，但回复没有 OVERRIDE-ACTIVE，只能说来源已出现在输入、回复格式未通过；不能因此说档案没载入，也不能把模型自述当成诊断输入证据。私人的完整输入可能含其他规则，只保存本练习需要的摘要。

Case: [root / UI / override / empty override / renamed restoration]
CLI version and start directory: [actual values]
New session: [yes / no / unverified]
Instruction-file state: [paths, nonempty/empty/renamed]
Expected markers: [prediction]
Instruction-source evidence: [observed input/log / model statement only / unavailable]
Actual answer markers: [observed values / no model run]
Conclusion: [discovery verified? response verified? remaining uncertainty]

失效排查与完成判准

完全没出现标记时，确认真正副档名、非空内容、Git 根目录与 --cd 位置；总是显示旧标记时，确认已退出并新启动，不是 resume 旧上下文；只有某段消失时，找同层 override、全域偏好或更高优先级的环境指示。不能把较深 AGENTS.md 当作越过组织政策、工具权限或使用者要求的通行证。若有冲突，先说明来源，再调整自己可控制的规则。

文件很长时还要考虑合计大小上限，官方预设是 32 KiB，计算的是位元组，不是中文字数。先保留必要规则，把长设计和范例移到普通文件并在需要时明确读取；不要以为切成大量兄弟目录就会自动载入全部内容。备援档名和上限属设定项，留到设定教学处理，改完同样要重启验证。

完成时保存根目录、ui、override、空 override、改名还原五种情况的启动位置、档案状态与实际标记。共同的 KEEP-DATA 应持续保留，移除 override 后可回到原 ui 行为。上述本机证据使用 debug prompt-input 检查真正组成的输入，没有送出模型请求，也未声称模型一定遵从。官方来源与实际版本差异都要记录；回复行为需由新工作阶段另行验证。接著看规则与文件分工，把容易膨胀的 AGENTS.md 改成可维护的入口。

返回 Codex 教学总目录

阅读完整文字说明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教程
• Codex