AGENTS.md vs CLAUDE.md: which one do you need?

AGENTS.md is an open format — described by its site as a README for agents — for the instructions a coding agent should follow in a repository. It has no required fields; it is plain markdown. Files can be nested in subfolders, and the one closest to the file being edited wins.

The convention began as joint work by OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

OpenAI Codex, Cursor and GitHub Copilot read AGENTS.md natively. Codex combines the files from the repo root down to the working folder, up to 32 KiB by default. Copilot uses the nearest AGENTS.md, and also accepts a single CLAUDE.md or GEMINI.md at the repo root.

Gemini CLI reads GEMINI.md by default and reads AGENTS.md once you add it to context.fileName in .gemini/settings.json. Aider reads it when configured to.

Claude Code reads CLAUDE.md. Recent versions also read AGENTS.md natively, but by default only when no CLAUDE.md exists; a project setting loads both.

Put the rules every agent should follow in AGENTS.md. Then create a CLAUDE.md whose first line is @AGENTS.md, which imports it, and add anything Claude-specific below that line. Every tool now reads the same rules, and there is one file to maintain.

Avoid a CLAUDE.md that only says, in words, to go read AGENTS.md — Anthropic's docs note that Claude may not open the file. Use the @ import, or a symlink.

Two copies of the same rules drift. One gets updated, the other doesn't, and two agents on the same repo start following different policies — the kind of failure that looks like one model getting worse rather than the instructions diverging.