AGENTS.md vs CLAUDE.md: What Each Agent Reads

Claude Code does not read AGENTS.md. It reads CLAUDE.md, and the widely repeated claim that it picks up AGENTS.md as a fallback is wrong. That single error is behind a lot of confused debugging, because the failure is silent: you write a careful AGENTS.md, Claude Code starts, nothing complains, and your instructions were simply never loaded.

Both files solve the same problem, which is giving a coding agent standing context about your repository so you stop repeating yourself. They differ in who reads them.

What AGENTS.md is

AGENTS.md is an open format published at agents.md, described by its authors as a README for agents. It is plain Markdown with no required fields, placed at the root of a repository. In a monorepo you can nest them in subpackages, and the closest file to the code being worked on wins.

The content is what you would tell a competent new contributor on day one: what the project is, how to build and test it, the code style you enforce in review, security considerations, and the commit or pull request conventions.

Its case rests on adoption rather than design. The format is deliberately unremarkable, and by its own count it is used by more than 60,000 open-source projects, with native support across most of the well-known coding agents. For a public repository, that reach is the argument. You write one file and a contributor arriving with Cursor, Codex or Copilot gets the same briefing.

What CLAUDE.md is

CLAUDE.md is Claude Code's equivalent and it behaves the same way in practice: Markdown at the repository root, loaded into context at the start of a session, with nested files supported for monorepos. Personal preferences can live in a user-level file, while project instructions live in the repository and get committed.

There is no meaningful format difference. The difference is the filename and which tool bothers to look for it.

The bridge

Because Claude Code will not read AGENTS.md on its own, you need to connect them, and there are two approaches that work.

Import it. Put a single line at the top of CLAUDE.md:

@AGENTS.md

Claude Code resolves the import and pulls the file in. This is the approach I would default to. It leaves both files present, it works on every platform, and it survives a clone by anyone on any operating system. It also leaves room for Claude-specific instructions underneath the import, which is usually what you end up wanting.

Symlink it. Point CLAUDE.md at AGENTS.md:

ln -s AGENTS.md CLAUDE.md

This guarantees the two never drift, because there is only one file. The cost is that symlinks in a Git repository are a reliable source of trouble for Windows contributors, and some tooling will quietly dereference or break them. Use it on a team where everyone is on macOS or Linux; avoid it on a mixed team.

What I would not do is maintain two files by hand and trust yourself to keep them in sync. They will drift, the drift will be silent, and you will debug the consequences weeks later.

What belongs in the file, and what does not

The format imposes nothing, which means most of these files fail on content rather than syntax. Three failure modes cover nearly all of it.

Too long. A file that runs to several hundred lines is loaded in full, every session, and competes for attention with the task. Agents skim long context the way people do. If yours has grown past a page or two, the excess is usually procedure, which belongs in a skill rather than in always-on context.

Aspirational rather than descriptive. Writing "we always maintain 90% test coverage" when the repository sits at 40% does not raise coverage. It teaches the agent a false fact about the codebase and it will write code and claims on that basis. Describe what is true and what you enforce, not what you wish were true.

A second copy of the README. The README is for humans evaluating the project. This file is for an agent about to change it. Overlap is fine, duplication is waste. The useful content is the operational detail a README usually omits: the test command that works, the one directory that is generated and must not be edited by hand, the migration step people forget.

Things worth including that people leave out: the exact build and test commands, including the flags that matter; which directories are generated; the traps that have caught contributors before; and how to verify a change locally before opening a pull request.

Never put secrets, API keys or credentials in either file. They are committed, they are read into context every session, and they will end up in places you did not plan for.

Where SKILL.md fits, and why it is not a competitor

A common muddle is treating SKILL.md as a third option in the same contest. It is a different layer.

CLAUDE.md and AGENTS.md are always-on context. Every line you put in them is loaded at the start of every session and is paid for in tokens every turn, whether or not it is relevant to the task in front of you.

Skills are loaded on demand. A skill sits in ~/.claude/skills/<name>/SKILL.md or in a project's .claude/skills/, and Claude pulls in its instructions when the task matches its description. That makes skills the right home for procedures that are long, detailed and only occasionally relevant: a deployment runbook, a review checklist, a house style guide for public copy.

The practical rule I use: if it applies to every task in the repository, it belongs in the always-on file. If it applies to one kind of task, it belongs in a skill. A CLAUDE.md that has grown to several hundred lines is usually a sign that three or four skills are trying to escape from it.

If you want to build those, the skill-creator skill scaffolds the structure, and superpowers is a good example of how a larger skill collection is organized.

A setup that survives a mixed-tool team

Teams rarely standardize on one agent, and they should not have to. The arrangement that has held up:

Write the real content once, in AGENTS.md at the repository root. Keep it short enough that people read it, which in practice means build and test commands, the conventions you enforce in review, and the handful of traps a newcomer falls into.

Add a CLAUDE.md whose first line is @AGENTS.md, followed by anything specific to Claude Code.

Move long procedures out of both files and into skills.

In a monorepo, put a small nested file in each package for the things that are specific to that package, and let the root file carry everything shared.

Then verify it, because this is the step people skip. Start a session and ask the agent to state a rule that exists only in your config file. If it cannot, the file is not being read, and no amount of rewriting the rule will fix a loading problem.

The thing to remember

The files are interchangeable in content and not interchangeable in filename. Claude Code reads CLAUDE.md. Most other agents read AGENTS.md. Pick AGENTS.md as the source of truth because more tools read it, then import it from CLAUDE.md with one line so Claude Code sees it too.

For how skills behave across other agents, see our look at whether Claude skills work in Codex, Cursor and Gemini CLI. For the distinction between skills, MCP servers and plugins, we covered that here. Our full list for developers covers the agents themselves.

FAQ

Does Claude Code read AGENTS.md as a fallback? No. Claude Code loads CLAUDE.md. The fallback claim circulates widely and is incorrect. Connect the two with an @AGENTS.md import on the first line of CLAUDE.md, or with a symlink.

Which file should be the source of truth? AGENTS.md, in most cases, because far more agents read it natively. Keep CLAUDE.md as a thin wrapper that imports it and adds anything Claude-specific.

Should I commit these files? Commit the project-level ones. That is the point: a contributor clones the repository and their agent is briefed. Keep personal preferences in your user-level config instead, where they will not be imposed on teammates.

Do nested files replace the root file or add to it? They layer. The file closest to the code takes precedence for conflicts, while the root file continues to supply shared context. Put package-specific instructions in the nested file and leave everything common at the root.

Is a symlink safe? On macOS and Linux, yes, and it removes drift entirely. On a team with Windows contributors it is a frequent source of breakage, so prefer the import line there.