Claude Code Resolves AGENTS.md vs CLAUDE.md: Streamlining AI Agent Configuration
In this article
Bottom line: Claude Code now falls back to reading `AGENTS.md` when a repository has no `CLAUDE.md`, quietly resolving a format war that's been forking developer attention since OpenAI's Codex team pushed `AGENTS.md` as a cross-tool standard in 2025.
`CLAUDE.md` still takes precedence when both files exist, and it retains Claude-specific features `AGENTS.md` doesn't define.
But for any repository running Claude Code alongside Cursor, Codex, or Aider, this means one instruction file instead of two near-duplicate ones.
Teams that had been maintaining symlinks or copy-paste scripts to keep both files in sync can finally delete that tooling.
For far too long, many of us—myself included—have been juggling near-identical `CLAUDE.md` and `AGENTS.md` files in our
AGENTS.md is an open, cross-tool standard maintained by the Agentic AI Foundation, designed to provide a single context file for various AI coding tools like OpenAI Codex, Gemini CLI, and Cursor. CLAUDE.md, on the other hand, is Claude Code's native context file, loaded automatically at the start of every session to define its operating parameters and workflows. If you are primarily working with Claude Code, you should use CLAUDE.md as it is Claude Code's native context file and is loaded automatically at the start of every session. Claude Code reads CLAUDE.md and not AGENTS.md directly. The recommended approach to avoid duplication when using both files is to create a symlink where AGENTS.md points to CLAUDE.md (e.g., `ln -s CLAUDE.md AGENTS.md`). Alternatively, you can use the `@AGENTS.md` import syntax within your CLAUDE.md file to pull in the content of AGENTS.md, allowing you to add Claude-specific instructions below the import. CLAUDE.md should contain operational rules, workflows, routing logic, quality standards, hard constraints, and delegation patterns that apply to every Claude Code session. It's also a good place for project-specific instructions, architecture decisions, naming conventions, and build/test commands that you would otherwise re-explain frequently.Common Questions
What is the primary difference between AGENTS.md and CLAUDE.md?
Which file should I use if I am primarily working with Claude Code?
How can I maintain both AGENTS.md and CLAUDE.md without duplicating information, especially if using multiple AI tools?
What kind of information should I include in my CLAUDE.md file?
Read Next
