AGENTS.md in Claude Code: it reads it on its own now, unless a CLAUDE.md exists

TL;DR With no CLAUDE.md around, Claude Code reads your AGENTS.md directly as of v2.1.277. Put a CLAUDE.md or a CLAUDE.local.md in that folder or any folder above it, and it reads those instead. To get both, set Project instructions to claude-md-and-agents-md in /config. Any @AGENTS.md import you already have keeps working and never loads the file twice.

For months, AGENTS.md was the file Cursor, Codex, Copilot and Gemini CLI read and Claude Code ignored. This tip used to show how to bridge the gap with an import or a symlink. As of v2.1.277 you don't need either: if your repo has an AGENTS.md and no CLAUDE.md, Claude Code loads it at startup.

There is one condition, and it's easy to trip over: the moment a CLAUDE.md or a CLAUDE.local.md shows up in your folder or anywhere above it, Claude Code stops reading AGENTS.md.

What it reads, case by case

I tested it on v2.1.281 with a repo whose AGENTS.md holds a codeword, asking Claude for the word without letting it open any files:

The second row is the one people miss. CLAUDE.local.md is where your personal, uncommitted project notes go. Create one in a repo that runs on AGENTS.md and you switch off the team's file for yourself alone, with nothing on screen to tell you.

What does not count for that check: your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and anything in .claude/rules/. Those keep loading alongside AGENTS.md.

How to choose what it reads

1. Check what loaded

According to the docs, an interactive session announces it in the conversation with a line like no CLAUDE.md found; AGENTS.md loaded: /path/AGENTS.md. If you don't see one, /context lists your Memory files.

2. Want both? Change it in /config

Open /config and find Project instructions:

The same setting fits in your ~/.claude/settings.json, under the built-in plugin that owns it:

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

It has no effect in project or local settings: this is your call, not the repo's.

3. Or join the two with an import

If your team already keeps a CLAUDE.md for the Claude-only bits, an @AGENTS.md on its first line is still how you keep one shared file:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

What to do with your old workaround

• A CLAUDE.md holding @AGENTS.md: leave it. Claude Code never reads an AGENTS.md twice. If that's all the file holds, you can delete it.
• A CLAUDE.md symlinked to AGENTS.md: same, the content goes in once.
• A CLAUDE.md that says "read AGENTS.md" in words: with that sentence, Claude only sees AGENTS.md if it decides to open it. Delete the file, or swap the sentence for the import.
• A SessionStart hook that prints AGENTS.md: remove it. It now adds a second copy to the context.

When it still won't read it

• On versions before v2.1.277, or if you disabled the agents-md plugin in /plugin.
• Sometimes in your first session after upgrading from v2.1.276 or earlier. It picks it up from the next one.
• Before v2.1.281, on Bedrock, Vertex or Foundry, behind a gateway, or with telemetry disabled.

In any of those cases, an @AGENTS.md inside a CLAUDE.md is what works.

Where it fits

• What's worth writing in that file, and what isn't: your CLAUDE.md is full of junk.
• Rules that only apply to part of the codebase belong in conditional rules under .claude/rules/, which keep loading alongside AGENTS.md.

Official docs: How Claude remembers your project · AGENTS.md

Requirements

• Claude Code v2.1.277 or later for it to read AGENTS.md on its own. I ran all five rows of the table on v2.1.281 with claude -p.