AGENTS.md scopes and overrides

Back to the Codex learning hub

Goal and preparation

AGENTS.md holds work instructions; config.toml holds application settings with a different precedence mechanism. Observe reply markers and an inherited requirement without changing sandbox permissions or running unknown commands. Being able to quote a file does not prove startup discovery; compare behavior and working directory too.

Understand the discovery order

Global guidance normally lives in the user's .codex directory, or the existing CODEX_HOME location. Project discovery walks from the recognized root to the current directory, not through all sibling folders. Each level checks AGENTS.override.md before AGENTS.md, then configured fallback names, taking at most one file. Deeper guidance overrides conflicting earlier items while compatible requirements remain.

Step 1: Create an isolated rule lab

Create a new codex-rules-lab with ui and data subfolders, initially without an override. Open it in your editor and verify the terminal location with Get-Location in PowerShell or pwd on macOS/Linux. After confirming this is a new lab, initialize Git below to define its project root. No commit or remote connection is required.

git init
git rev-parse --show-toplevel

Create root AGENTS.md with the complete sample below. ROOT-LAB is an observable reply prefix; KEEP-DATA is a compatible requirement retained across subdirectories. These markers serve the experiment. Real rules should express actual tests, data preservation and delivery requirements.

# 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.

Put the second sample in ui/AGENTS.md and the data note in data/README.md. README is deliberately not an AGENTS file; without an applicable fallback-name configuration, Markdown alone does not make it startup guidance. Check exact capitalization and extensions, including accidental .txt suffixes.

# 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.

Step 2: Start once from each directory

From the lab-root terminal, run the first read-only CLI launch. Inside Codex, send the natural-language prompt below without pasting rules or prescribing a prefix. Expect ROOT-LAB and KEEP-DATA. Use /exit to return to the shell, then start a fresh ui session with the second launch command, rather than resuming the earlier task.

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

Send the identical request in ui. Expect UI-LAB, KEEP-DATA and UI-BASE: the nested prefix overrides the root prefix while compatible root instructions remain. If the model can report rules only after being asked to read them manually, distinguish that from startup discovery. A model's self-report is not a loading log; retain uncertainty where evidence is insufficient.

Step 3: Add a same-level override and compare

Exit ui, retain ui/AGENTS.md and add ui/AGENTS.override.md below. From the lab root, relaunch codex --cd ui --sandbox read-only and send the same request. Expect UI-OVERRIDE and KEEP-DATA, without UI-BASE inherited from the replaced same-level file. The override replaces that level's candidate, not every root or global instruction.

# UI override practice

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

For a boundary case, back up the override, empty it, save and start fresh, then record the actual discovery. Local diagnostic inputs from codex-cli 0.154.0-alpha.6.2 contain no override body but also do not load same-level AGENTS.md; root instructions remain. Do not rely on an empty file to disable an override. Rename it to override.saved.md, outside the configured fallback list, then start fresh and verify UI-LAB, UI-BASE and KEEP-DATA. Keep global files and the settings directory intact.

Separate discovery from compliance in one record

Fill in the fields for each fresh start: root, UI, override, empty override and renamed restoration. Keep expectations out of the observed-answer field. If diagnostic input contains the UI override but the answer omits OVERRIDE-ACTIVE, discovery is evidenced but response compliance failed. That does not prove a missing file; a model's claim is not diagnostic-input evidence either. Retain only a practice summary of private input that may contain other rules.

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]

Diagnose failures and confirm completion

For missing markers, check actual extensions, nonempty content, Git root and --cd. For stale markers, confirm a fresh launch rather than resume. For one missing requirement, inspect same-level overrides, global preferences and higher-priority environment instructions. A deeper AGENTS.md does not bypass organization policy, tool permissions or user requests. Identify the conflicting source before changing rules you control.

Long guidance may hit the documented 32 KiB default combined limit, measured in bytes rather than characters. Keep essential rules and move long designs/examples into ordinary documents read when needed. Splitting content among sibling directories does not automatically load it all. Fallback names and the limit are settings covered in configuration, with restart verification after changes.

Retain launch directory, file state and observed markers for root, ui, override, empty-override and renamed-override cases. KEEP-DATA should remain, and removing the override should restore ui behavior. Local evidence uses debug prompt-input to inspect actual constructed inputs without a model request or compliance claim. Record documented and version-specific behavior; verify response behavior separately in fresh sessions. Continue with rules and context files to keep AGENTS.md maintainable.

Back to the Codex learning hub

Read the full description

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

• AI tools
• Tutorials
• Codex