Originally published at https://rayastats.com/en/blog/claude-md-vs-agents-md Put the shared rules in AGENTS.md. By default, Claude Code reads that file directly from v2.1.277 when no CLAUDE.md, .claud
Markdown supported · ⌘↵ to post
Thanks, Adam. By default, from v2.1.277, Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or above it, so with one of them present there's nothing to rank. With @AGENTS.md at the top of CLAUDE.md, the shared lines load first, but the docs say Claude Code can follow either line when two contradict. Codex has a fixed order: at most one file per directory, AGENTS.md ahead of any name in project_doc_fallback_filenames, and the file closest to the working directory overrides the ones above it. So keep every shared rule in AGENTS.md and give CLAUDE.md only lines that don't contradict them.
Adam Lewis
Product Engineer/Architect navigating the AI revolution
Pin down precedence: when both files are in play under claude-md-and-agents-md, does a later AGENTS.md actually override an earlier CLAUDE.md line, or do the two just stack in context with no winner? Matters for anything you'd write as a rule. If Codex resolves conflicts and Claude Code only concatenates, then the shared file has to be written so the two never disagree in the first place. How are you handling a line you want in AGENTS.md that Claude Code would read as contradicting something in .claude/rules?