Codex reads AGENTS.md before work and can combine instructions from global and nested project locations. Keep each layer concise and put narrow rules near the code they affect.
1. Create a global baseline only if useful
Put cross-repository preferences in ~/.codex/AGENTS.md: preferred package manager, general testing discipline or approval expectations. Avoid project-specific paths.
2. Add repository agreements
At the repository root, document install/test commands, architectural boundaries, generated files and the definition of done for common changes.
3. Use nested instructions for special areas
Place a closer AGENTS.md or supported override near a subsystem that has different tooling or constraints. The more local instruction should be the more specific one.
4. Keep the total instruction chain small
Long instruction chains dilute important rules and can hit configured size limits. Link to documentation when detail is reference material rather than an instruction.
5. Ask Codex to summarize the active rules
Start a fresh session in a nested directory and ask which instructions apply. Confirm the merged behavior matches your intended hierarchy.
Before starting this task, summarize the AGENTS.md instruction chain that applies from global scope to the current directory. Highlight any local rule that overrides a broader rule.
Putting repository paths in global instructions; duplicating the same rule at every level; making nested files contradict each other accidentally; letting instructions grow beyond what a human can review.
Finish check
Codex can explain the active instruction hierarchy and follows the narrow local rule without losing the repository-wide baseline.