File Hierarchy & Resolution

AGENTS.md is not one file — it is a hierarchy. Codex merges multiple AGENTS.md files at startup, each scoped to a different level: global (your personal defaults at ~/.codex/AGENTS.md), repository root (./AGENTS.md), and directory-scoped (./src/AGENTS.md, ./src/api/AGENTS.md, etc.). Higher-scoped files provide baseline rules; lower-scoped files refine them for specific modules. When rules conflict, deeper scope wins within a layer, and AGENTS.override.md files take precedence over same-level AGENTS.md files.

Understanding the merge order is critical for teams. A developer who sets global rules in ~/.codex/AGENTS.md will have those rules apply to every project — but any repo-level or directory-level AGENTS.md will override them for that specific context. This means you can set personal preferences globally (editor style, preferred test framework, naming conventions) while respecting project-specific rules checked into the repository.

# Resolution order (lowest to highest priority)

~/.codex/AGENTS.md             # Personal global defaults
./AGENTS.md                     # Repo root — team-shared rules
./src/AGENTS.md                 # Directory-scoped — module rules
./src/api/AGENTS.md             # Deeper directory — API-specific
./AGENTS.override.md            # Override (same-level, higher priority)
./src/AGENTS.override.md        # Override at directory level

# Fallback recognition
./CLAUDE.md                     # Recognized as fallback
./COPILOT.md                    # Recognized as fallback

1. Audit your hierarchy Run `find . -name "AGENTS.md" -o -name "AGENTS.override.md" -o -name "CLAUDE.md"` to see every config file Codex will load.
2. Map the merge For each file found, note its scope level. Check for conflicting rules across levels — the deepest scope wins.
3. Test with /status Start a Codex session in a subdirectory and run /status to confirm which rules are active. Move between directories to verify scoping.