If you are running OpenAI's Codex CLI, your carefully crafted CLAUDE.md files are essentially invisible to the agent. A new deep-dive published on DEV.to by Eli Alvarado clarifies that Codex exclusively reads AGENTS.md files to determine project stack, commands, and safety constraints. The guide emphasizes that while other AI coding tools like Cursor and Claude Code have their own configuration ecosystems, Codex operates on a distinct, hierarchical instruction model that many developers are currently misunderstanding.

The Instruction Chain Mechanics

Codex constructs its context by building an instruction chain once per run in the TUI or once per session. It begins with global defaults located at ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md, which serve as personal preferences rather than repository rules. From there, it scans from the repository root down to the current working directory, prioritizing AGENTS.override.md over AGENTS.md in each folder. This creates a concatenation effect where closer files override broader guidance, but the total combined project instructions are capped at approximately 32 KiB by default. Empty files are skipped, and the system explicitly ignores CLAUDE.md and .cursor/rules/*.mdc files, meaning any rules not mirrored into the AGENTS.md format are lost to the agent.

Template and Best Practices

The guide provides a minimal copy-paste template designed to be pasted directly into the repository root. It stresses brevity and specificity, noting that a short, precise file is followed strictly, whereas a 600-line essay gets skimmed. The template includes sections for Project details, Commands, Hard rules, Workflow, and Definition of Done. Key hard rules suggested include never printing secrets, never disabling tests to force a pass, and keeping diffs small. The workflow section mandates that the agent restate the goal, list files to touch, make small changes, and report verification status, ensuring the agent doesn't expand scope unexpectedly.

Interoperability with Other Tools

For teams using multiple AI agents, the recommended architecture is to write AGENTS.md as the shared source of truth. Claude Code users can create a thin CLAUDE.md file that imports the main instructions using the @AGENTS.md syntax. Cursor users should maintain path-scoped rules in .cursor/rules/*.mdc for specific needs like authentication or Row Level Security (RLS) in Supabase. The guide also points to free, MIT-licensed resources in the eli-alvarado/agentkit-drawer repo, including agent-guardrails.md for injection defense and nextjs-supabase-rls.mdc for framework-specific rules, allowing developers to mix and match components as needed.

Key Takeaways

  • Codex CLI does not read CLAUDE.md or Cursor .mdc files; it only reads AGENTS.md and AGENTS.override.md.
  • Instructions are concatenated from root to cwd, with closer files overriding broader ones, capped at 32 KiB.
  • Global defaults live in ~/.codex/, while project rules belong in the repository root.
  • Brevity is critical; short, specific instructions are followed, while long essays are skimmed.
  • Shared rules should be in AGENTS.md, with other tools importing or mirroring these instructions.

The Bottom Line

Stop assuming your AI agents are reading the same rulebook. Codex is a different beast that demands its own specific AGENTS.md format, and ignoring this distinction is why your agent keeps breaking production secrets or skipping tests.