One shared core
Put commands, architecture, boundaries, and completion checks in AGENTS.md. Keep the bridge CLAUDE.md short.
Official-source decision guide · checked September 1, 2026
AGENTS.md vs CLAUDE.md: choose the file your tools actually read.
Answer two questions, get a concrete repository setup, then copy the bridge, convert an existing file, or check both for drift. No repository content leaves your browser.
Your setup
Use both names, one shared body
Keep shared rules in AGENTS.md and import them from CLAUDE.md.
This follows Anthropic’s documented bridge for repositories that already use AGENTS.md, while leaving room for Claude-specific additions.
CLAUDE.md
@AGENTS.md # Claude Code Add only Claude Code-specific instructions here. Keep shared repository commands, architecture, constraints, and validation rules in AGENTS.md.
Direct comparison
Same job, different loaders.
Both files are ordinary Markdown. The important difference is which tool discovers the filename, how it layers narrower instructions, and which tool-specific features surround it.
| Question | AGENTS.md for Codex | CLAUDE.md for Claude Code |
|---|---|---|
| Native reader | Codex reads AGENTS.md before work begins. | Claude Code reads CLAUDE.md at session start. |
| Repository scope | Root guidance plus one instruction file per directory down to the working directory. | Root and ancestor files load at launch; nested files load when Claude reads that subtree. |
| More specific rules | Closer files appear later in Codex’s combined instructions and override broader guidance. | Closer CLAUDE.md files are appended later; .claude/rules can be limited by file paths. |
| Composition | Split guidance across nested AGENTS.md or AGENTS.override.md files. | Import another file with @path, including @AGENTS.md. |
| Best fit | Codex-first or multi-agent repositories that want a neutral shared instruction layer. | Claude Code-only guidance or Claude-specific additions, rules, and local preferences. |
Tool-specific edges
Add Claude-only imports or rules below the bridge. Use nested AGENTS.md files where Codex work needs narrower repository guidance.
Make drift observable
If two bodies must remain separate, compare commands and guardrails after either file changes instead of trusting manual review.
Primary documentation
Facts checked against the tools’ current docs.
OpenAI documents Codex’s AGENTS.md discovery and root-to-working-directory precedence. Anthropic documents CLAUDE.md loading, @ imports, and the recommended @AGENTS.md bridge.
AGENTS.md vs CLAUDE.md FAQ
Does Claude Code read AGENTS.md directly?
No. Claude Code’s official documentation says it reads CLAUDE.md, not AGENTS.md. For a repository that already uses AGENTS.md, Anthropic recommends importing it from CLAUDE.md with @AGENTS.md.
Does Codex read CLAUDE.md?
Not by default. Codex discovers AGENTS.override.md, AGENTS.md, and any fallback filenames you explicitly configure. Use AGENTS.md for repository guidance you want Codex to load automatically.
Should a repository keep both files?
Keep both filenames when the team uses both Codex and Claude Code, but avoid duplicating the shared body. Put shared rules in AGENTS.md and import them from a short CLAUDE.md, then add only Claude-specific guidance below the import.
How do I prevent AGENTS.md and CLAUDE.md from drifting?
Prefer one shared source. If separate files are necessary, compare their commands and guardrails whenever either changes. Repo Agent Kit’s private checker can compare both files entirely in the browser.