AGENTS.md vs CLAUDE.md: Which One to Write

Write AGENTS.md. Both files hold the same thing, a set of project instructions an agent reads before it touches your code. The difference is the audience. CLAUDE.md is read by Claude Code. AGENTS.md is read by more than 25 tools, Claude Code among them.

If Claude Code is the only agent you will ever run, CLAUDE.md alone is fine. The moment a second agent enters the picture, AGENTS.md is the file that both of them see.

The difference is who reads them

	CLAUDE.md	AGENTS.md
Read by	Claude Code	25+ agent tools, Claude Code included
Scope	One tool	Any agent you run
Contents	Project instructions	Project instructions
Where it lives	Repository root, and nested	Repository root, and nested

The tools that read AGENTS.md include Codex, Gemini CLI, Cursor, Aider, goose, Zed, Jules, and GitHub Copilot’s coding agent. The format describes itself as a README for agents: one predictable place for the context an agent needs.

Nothing about the content changes between the two. Both cover what the project is, the setup and build commands, how to run the tests, the code style, and the commit and PR rules.

Run both without keeping two copies

The trap is writing the same instructions twice. Two files drift, and the one you forget is the one your agent reads.

Put the instructions in AGENTS.md, then have CLAUDE.md import it:

# CLAUDE.md

Project-specific notes for Claude Code go here.

@AGENTS.md

One source of truth, and CLAUDE.md stays useful for the few things that really are Claude Code specific. This site’s own repository is set up that way.

Which one to write

Three situations cover almost everyone:

• Only Claude Code, and no plans to change. CLAUDE.md on its own. You lose nothing.
• More than one agent, or you expect to. AGENTS.md as the real file, with the CLAUDE.md import above.
• An existing CLAUDE.md you want to convert. Rename it to AGENTS.md, then create a CLAUDE.md containing the import line. Nothing else moves.

The second case is the common one, and it is worth choosing early. Converting later is a two-minute job, but only if you remember the first file exists.

Both files nest in a monorepo

AGENTS.md files nest, and so does the decision. Put one at the repository root for shared rules, then another inside a package or app directory for rules that only apply there.

The closest file to the code being edited wins, so a subdirectory can override the root without repeating it. A frontend package can carry its own style rules while the root file keeps the build commands everyone needs.

What to put in either file

The content question is the same whichever filename you choose. Start from a template rather than a blank file. The CLAUDE.md templates in the library cover general projects, React, Python, API and backend, full-stack, CLI tools, data science, and a minimal version. Every one of them works as an AGENTS.md if you rename it, because the content is identical.

For the longer version on what belongs inside, see CLAUDE.md best practices and how to write a CLAUDE.md file. The advice applies to both filenames.

One thing that catches people out

An instruction file is context, and context is not enforcement. An agent reads AGENTS.md and is more likely to follow it. An agent does not obey it the way code obeys a linter.

So the file is worth keeping short and specific. A 400-line AGENTS.md competes with itself for attention, and the rule you care about most is somewhere in the middle of it. CLAUDE.md best practices goes into what that means in practice.

The short version

Write AGENTS.md. Add a CLAUDE.md that imports it if you use Claude Code. Keep one copy of the instructions, keep it short, and nest a second file only where a subdirectory genuinely needs different rules.

If you want the wider picture of how these sit alongside skills and the rest of the config surface, every Claude Code config file explained covers the full set.