Only if one of them is a pointer. Two files with the same content drift within weeks, and the one being read is rarely the one that was updated. Put the substance in AGENTS.md and make CLAUDE.md a single line pointing at it.

Which should hold the content?

AGENTS.md, in most repositories. It is read by more tools, so the content is useful to more of the people and agents that open your project. The exception is a repository where everyone uses Claude Code and always will — then the extra file is ceremony.

Does Claude Code read AGENTS.md?

Point it there rather than relying on it. One line in CLAUDE.md — "See AGENTS.md, it is the source of truth for this repository" — works regardless of what any tool supports this month, and costs nothing to keep correct.

What about .cursorrules and copilot-instructions.md?

Same treatment. Each tool wants its own filename, and each of those files can be one line pointing at AGENTS.md. That is the problem AGENTS.md was created to solve — repositories accumulating four instruction files that slowly disagree.

Do these files replace a README?

No. A README is for people deciding whether to use the project. These are for whoever — human or agent — is about to change it. The audiences barely overlap, and merging them makes both worse.

AGENTS.md vs CLAUDE.md

They do the same job for different audiences. Both are plain Markdown telling whoever is about to change your repository how it works — CLAUDE.md is read by Claude Code, AGENTS.md is a vendor-neutral convention several tools read. The interesting question is not which is better but whether to keep both, and the answer is: only if one of them is a pointer.

The short version

	`AGENTS.md`	`CLAUDE.md`
Read by	Several tools, by convention	Claude Code
Format	Plain Markdown, no required sections	Plain Markdown, no required sections
Location	Repository root	Root, subdirectory, or `~/.claude/`
Nesting	One file	Files nest and combine
Personal version	—	`CLAUDE.local.md`, gitignored
Good contents	Identical: commands, conventions, boundaries, traps

That last row is the point. The two files are not competing formats with different capabilities — they are the same document addressed to different readers. Anyone comparing them feature by feature will find almost nothing to compare.

Why there are two at all

Coding agents each arrived with their own filename. Claude Code reads CLAUDE.md, Cursor read .cursorrules, GitHub Copilot reads .github/copilot-instructions.md, and several others invented their own. Every one of those files said roughly the same thing.

Repositories ended up with three or four of them, written at different times, drifting apart. The one a human had open was rarely the one the tool was reading. AGENTS.md is the convergence on a single neutral name — not a better format, just one file instead of four.

Keep one, point the rest at it

Put the substance in AGENTS.md and make every other instruction file one line:

A CLAUDE.md that cannot go stale — edit it and take it

Markdown

Result

Open the full editor Runs in this tab — nothing is uploaded.

A pointer cannot drift. A copy will, and the failure is silent: nothing breaks, the agent simply follows an instruction you replaced two months ago. The maintenance cost of the second file drops to zero, and there is still exactly one place to make a change.

Which file holds the content is mostly about who opens your repository. AGENTS.md is the default, because more tools read it. CLAUDE.md is the reasonable choice in a repository where everyone uses Claude Code and always will — there, the second file is ceremony.

The one thing CLAUDE.md does that AGENTS.md does not

It nests. A CLAUDE.md can sit in a subdirectory and apply to work inside it, combining with the one at the root rather than replacing it, and ~/.claude/CLAUDE.md applies to every project you personally open.

In a monorepo that is genuinely useful: shared rules at the top, package-specific rules beside each package. If that is your layout, the content may well belong in CLAUDE.md files with AGENTS.md pointing at the root one — the opposite of the usual advice, for a real reason.

There is also CLAUDE.local.md for the things that are yours rather than the project's: a scratch path, a preference, a workaround nobody else needs. Gitignore it.

What belongs in whichever file you pick

The contents are the same either way, and worth more thought than the filename:

Commands, with a line saying what each is for. npm run check could be a linter, a type check or a deploy gate, and guessing wrong wastes a cycle.
Conventions that are house style rather than accident — named exports only, errors returned rather than thrown, tests beside the file they test.
Boundaries. The generated directory. The dependency that needs asking about. The public API with a deprecation path.
The traps. The file that looks dead and is load-bearing, the dev server that proxies to real data, the migration that cannot be undone. This is the most valuable section and the one most often left empty, because the traps are invisible to whoever already knows them.

Be specific rather than emphatic. "Write good tests" is a sentiment; "every bug fix gets a regression test that fails before the fix" is checkable. And a file where four rules are marked critical reads as a file with no priorities.

Neither one replaces a README

A README is for someone deciding whether to use the project. These files are for whoever is about to change it. The audiences barely overlap — one wants to know what it does, the other wants to know which directory not to touch — and merging them makes both worse.

Common questions

What is the difference between AGENTS.md and CLAUDE.md?: Audience, not format. Both are plain Markdown describing how to work in a repository. CLAUDE.md is read by Claude Code; AGENTS.md is a vendor-neutral convention that several tools read. Neither has required sections, and the contents of a good one are nearly identical.
Should I have both?: Only if one of them is a pointer. Two files with the same content drift within weeks, and the one being read is rarely the one that was updated. Put the substance in AGENTS.md and make CLAUDE.md a single line pointing at it.
Which should hold the content?: AGENTS.md, in most repositories. It is read by more tools, so the content is useful to more of the people and agents that open your project. The exception is a repository where everyone uses Claude Code and always will — then the extra file is ceremony.
Does Claude Code read AGENTS.md?: Point it there rather than relying on it. One line in CLAUDE.md — "See AGENTS.md, it is the source of truth for this repository" — works regardless of what any tool supports this month, and costs nothing to keep correct.
What about .cursorrules and copilot-instructions.md?: Same treatment. Each tool wants its own filename, and each of those files can be one line pointing at AGENTS.md. That is the problem AGENTS.md was created to solve — repositories accumulating four instruction files that slowly disagree.
Do these files replace a README?: No. A README is for people deciding whether to use the project. These are for whoever — human or agent — is about to change it. The audiences barely overlap, and merging them makes both worse.