agent-context-guide

Structure Codex instructions by creating a root AGENTS.md for core rules, adding nested AGENTS.md files in subdirectories for domain-specific guidelines, and optionally using AGENTS.override.md for exceptions to ensure scalable governance across large repositories.

A nested AGENTS.md file encapsulates domain-level rules and specific guidance within subdirectories, allowing large repositories to maintain clear separation of concerns between root governance and localized Codex instructions.

Keep background knowledge in a lightweight CONTEXT.md file or docs directory, while reserving AGENTS.md files strictly for governance rules and instruction architecture, linking supporting documents via references to optimize tokens.

Use an AGENTS.override.md file to define exceptions to the root and nested AGENTS.md governance rules, allowing specific domain contexts to bypass or modify general instructions without altering the core architecture.

This instruction architecture specifically targets large repositories needing scalable, domain-specific Codex guidance, so small projects with minimal domain contexts may find the layered root, nested, and override structure unnecessarily complex.

Optimize tokens by keeping AGENTS.md files focused on rules, moving background context to lightweight CONTEXT.md files, and using link references to supporting documents in the references directory instead of inlining extensive documentation.