OpenAI writes down the AGENTS.md merge order, and agent config becomes auditable

OpenAI's Codex documentation now specifies exactly how the agent discovers, orders and merges AGENTS.md files before it does any work ^[1]. That converts a pile of per-repo prompt files into something a platform team can standardize, diff and review, because the resolution order is stated rather than inferred.

The chain is built once per run, which in the TUI usually means once per launched session ^[2]. First comes global scope: in the Codex home directory (`~/.codex` by default, or wherever `CODEX_HOME` points), Codex reads `AGENTS.override.md` if present, otherwise `AGENTS.md`, and takes only the first non-empty file at that level ^[3]. Then project scope: starting at the project root, typically the Git root, Codex walks down to the current working directory, and in each directory checks `AGENTS.override.md`, then `AGENTS.md`, then any names listed in `project_doc_fallback_filenames`, including at most one file per directory ^[4]. If no project root is found, only the current directory is checked ^[5]. The files are concatenated from the root down, joined by blank lines, so files nearer the working directory win by appearing later in the combined prompt ^[6]. Empty files are skipped, and Codex stops adding files once the combined size reaches `project_doc_max_bytes`, 32 KiB by default ^[7].

Three consequences matter more than the syntax. First, the working directory is part of your configuration. The walk terminates at the current directory ^[8], so instruction files in directories below wherever the session was launched never load ^[3]. The same repository therefore produces different instructions depending on where a developer or a CI job starts Codex.

Second, an override shadows locally, not globally. OpenAI's sample tree shows `services/payments/AGENTS.md` ignored because an `AGENTS.override.md` sits beside it ^[9], but the root file is still concatenated ahead of it ^[4]. Committing an override into a service directory permanently suppresses that directory's AGENTS.md, which is a different behavior from the documented use of a global `AGENTS.override.md` as a temporary override you delete to restore shared guidance ^[15].

Third, the byte cap has a direction. Thirty-two KiB is 32,768 bytes for the entire chain ^[1], and because files are added root-first until the limit is hit, what gets dropped on overflow is the most specific guidance, not the most general ^[2]. OpenAI's advice is to raise the limit or split instructions across nested directories when you reach the cap ^[10]. For a platform team, the first thing to budget is the global file, since every repository inherits it.

The documented verification step is worth wiring into onboarding: run Codex with `--cd` into the specialized directory and ask it to list the instruction sources it loaded, expecting the global file first, the repository root AGENTS.md second, and the nested override last ^[11]. For GitHub code review, rules go in a `## Code Review Rules` section of the AGENTS.md closest to the code they govern, with repository-wide checks at the root and service-specific checks nested ^[12]. OpenAI advises keeping those rules concise, stating the behavior to flag plus any safe path or exception, and leaving formatting and lint checks to CI ^[13]. Repos already using another filename, such as `TEAM_GUIDE.md`, can add it to the fallback list ^[14].

Watch two things: whether `AGENTS.override.md` starts appearing in committed trees, where its shadowing is permanent rather than temporary ^[15][4], and whether teams notice the 32 KiB ceiling only after their most specific rules quietly stop loading ^[2].