AGENTS.md vs CLAUDE.md: which one gets read

AGENTS.md is an open format for the file a coding agent reads before it touches your repository. Plain markdown, no required fields, no schema. Its site claims over 60,000 open-source projects using it, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation, which matters mainly in that it is not one vendor's file.

The list of tools that read it is long and includes most of the ones people actually use: OpenAI Codex, Cursor, Jules, Gemini CLI, GitHub Copilot's coding agent, Devin, Windsurf, Zed, Aider, goose, opencode, Warp, Amp, Factory, Junie, RooCode, Augment Code. CLAUDE.md is Claude Code's own file, and it predates the format.

Since v2.1.277, Claude Code reads AGENTS.md on its own, with no import and no setting. So the framing of "which should I use" is usually wrong. The real question is what happens when a repository has both, and the answer has an edge on it.

The default behaviour is a fallback, not a merge. AGENTS.md is read only when there is no Claude-specific project file to read instead:

Three files count as "a Claude-specific project file", in the working directory or any directory above it: CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md. Any one of them present means AGENTS.md is skipped.

Three things do not count, and keep loading alongside AGENTS.md: your own ~/.claude/CLAUDE.md, an organisation's managed policy file, and everything in .claude/rules/. So personal preferences and path-scoped rules survive the switch. Only the project file is exclusive.

Also not read at all, whatever else is present: AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ directory. These get invented by analogy and then quietly do nothing.

Here is the failure worth knowing about, because it looks like a bug and is not one.

Your team standardised on AGENTS.md. It works. Then you want a couple of private notes that should not be committed: your local database URL, the test account you use. The documented place for those is CLAUDE.local.md, gitignored. You add it.

CLAUDE.local.md counts. From that moment Claude reads your four lines of personal notes and stops reading the team's AGENTS.md entirely. Nothing errors. The session just gets quietly worse, and it gets worse only for you, on your machine, which is the hardest kind of problem to get anyone else to reproduce.

The fix is one setting, covered next. The general lesson is the one this whole cluster keeps arriving at: these files are context, loaded by rules you did not write, and "it stopped following my instructions" is very often "it stopped being given my instructions".

The behaviour is a setting with four values. /config exposes it as Project instructions, and it can also be written into ~/.claude/settings.json:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

If you want private notes without losing the team file, claude-md-and-agents-md is the answer. It also will not double up: if your CLAUDE.md already imports AGENTS.md, the file is not read twice.

If Project instructions does not appear in /config at all, the session cannot load AGENTS.md. That happens on versions before v2.1.277, if the built-in agents-md plugin has been disabled in /plugin, and sometimes on the first session immediately after upgrading. Before v2.1.281 some sessions, such as those on Amazon Bedrock or with telemetry disabled, also read CLAUDE.md only.

An AGENTS.md read through the setting is not treated identically to a CLAUDE.md. Three differences, and the first is the one that catches teams:

• Hooks do not fire for it. They fire as usual for CLAUDE.md, for its @path imports, and for a symlink's target, but not for an AGENTS.md loaded through Project instructions.
• Directories added with --add-dir contribute their CLAUDE.md when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set. Their AGENTS.md does not load either way.
• For an @path import pointing outside the working directory, CLAUDE.md triggers an approval prompt. An AGENTS.md loads it silently, but only if you had already approved external imports for that project.

None of this is a reason to avoid AGENTS.md. It is a reason not to assume a migration is a rename.

If you are on a version or a session that cannot read AGENTS.md, or you have set claude-md, one file can still serve everything. Put the import at the top of CLAUDE.md and anything Claude-specific below it, since the imported file is read first:

@AGENTS.md

## Claude Code specifics
Use plan mode for changes under `src/billing/`.
Run `npx tsx scripts/check-payments.ts` before saying a billing change is done.

A symlink is the other option, ln -s AGENTS.md CLAUDE.md, and it has two sharp edges. The Edit and Write tools refuse to write through a symlink, so Claude is redirected to edit AGENTS.md instead, which is arguably correct but surprising. And on Windows, creating one needs Administrator rights or Developer Mode, and git checks a committed symlink out as a plain text file unless core.symlinks is on, which leaves the clone with a one-line CLAUDE.md containing the word AGENTS.md and no instructions at all. On any team with a Windows machine, prefer the import.

Coming the other way, /import copies another agent's configuration in, including MCP servers, commands, subagents and skills. And CLAUDE_CODE_NEW_INIT=1 claude then /init can build a CLAUDE.md from an existing AGENTS.md, .devin/rules/, .windsurf/rules/, .windsurfrules or .clinerules.

The format has no required fields, which is freeing until you stare at the empty file. The sections that recur across the projects using it well are the ones a new contributor would ask about on their first day:

# AGENTS.md

## Setup
- `pnpm install`, then `pnpm dev` on port 3000.
- Needs `DATABASE_URL` in `.env.local`. Copy `.env.example`.

## Testing
- `pnpm test` runs vitest. `pnpm test -t "<name>"` for one case.
- Fix type errors as well: `pnpm typecheck`. A green test run with red types
  is not a passing change.
- Add or update tests for what you change, even if nobody asked.

## Code style
- TypeScript strict. No `any`, no non-null `!`.
- Named exports only.
- Components under 200 lines. Extract a subcomponent in the same directory
  rather than growing one past that.

## Pull requests
- Title: `<area>: <what changed>`, imperative mood.
- Run `pnpm lint` and `pnpm test` before committing.

Two structural rules are worth more than the content. In a monorepo, put an AGENTS.md in each package: agents read the nearest one in the tree, and the closest file to the edited file wins. The OpenAI Codex repository reportedly ships 88 of them. And whatever any file says, an explicit instruction in the chat overrides all of it, which is the escape hatch to reach for before editing the file in frustration.

The writing itself is the same discipline as any other prompt. A line like "follow our conventions" costs tokens and changes nothing; naming the constraint in checkable form is what makes the difference. The CLAUDE.md post works through that swap line by line.

Every claim above is checkable inside a session, and checking takes ten seconds. /memory lists the instruction files Claude read, with paths. /context shows them under Memory files. When an AGENTS.md is picked up in an interactive session you also get a line saying so explicitly, naming the path.

Before v2.1.280, a directly-read AGENTS.md did not appear in either list, so on older versions ask Claude what the project instructions say instead of trusting the listing. claude --version settles which behaviour you have.

Do this first, every time, before rewriting a rule you think is being ignored. Most of the time the rule is fine and the file was never in the room.