Claude Code Finally Reads AGENTS.md (Here's Exactly How It Works)

AGENTS.md is an open, tool-agnostic spec for repo-level agent instructions: plain markdown, no required schema, no frontmatter, just the same kind of "here's how this codebase works" notes you'd leave for a new teammate. It came out of a joint effort between the teams behind OpenAI Codex, Cursor, Amp, Google Jules, and Factory, who each needed the same file and didn't want five competing names for it.

It's now stewarded by the Agentic AI Foundation under the Linux Foundation, and it's read natively by Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed, Factory, Jules, Devin, and RooCode, across more than 60,000 repositories. Claude Code was the conspicuous exception.

Claude Code v2.1.277, released September 18, 2026, added native support for reading AGENTS.md. A repository already set up for other coding agents now works with Claude Code without adding a CLAUDE.md, a symlink, or an import.

That's the headline, and it's accurate. What it leaves out is that "supports AGENTS.md" doesn't mean "merges AGENTS.md with CLAUDE.md," and it doesn't mean "works identically everywhere." Both of those caught people off guard in the first few days.

By default, Claude reads one or the other, not both:

Any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or anywhere above it counts against reading AGENTS.md directly. Your ~/.claude/CLAUDE.md, your org's managed CLAUDE.md, and .claude/rules/ files don't count, and keep loading alongside AGENTS.md either way.

You can change the default behavior with /config → Project instructions:

A few gotchas worth knowing before you assume it's working:

• It's not available everywhere. No AGENTS.md support on Amazon Bedrock, Vertex AI, or Microsoft Foundry, and none if your session has telemetry disabled — those sessions read CLAUDE.md only, silently, and Project instructions won't even show up in /config.
• Your first session after upgrading doesn't get it either. Claude reads AGENTS.md starting from your next session, not the one where you just updated.
• A CLAUDE.local.md you kept for personal notes blocks it. If your team's shared file is AGENTS.md but you keep a local CLAUDE.local.md for your own uncommitted preferences, that file alone stops Claude from reading AGENTS.md — unless you explicitly set claude-md-and-agents-md.

Even when Claude is reading your AGENTS.md, it isn't treated quite like a native CLAUDE.md:

• It doesn't show up in /memory or the Memory files list in /context. To confirm it loaded, look for the no CLAUDE.md found; AGENTS.md loaded: ... line at session start.
• InstructionsLoaded hooks don't fire for it (they do fire for an AGENTS.md that a CLAUDE.md imports or symlinks to).
• @path imports inside it skip the external-import approval prompt, since you already approved the setup.
• --add-dir combined with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD won't pick up that directory's AGENTS.md.

None of this is a dealbreaker, but "Claude Code now reads AGENTS.md" and "AGENTS.md now behaves exactly like CLAUDE.md" are different claims, and a lot of the launch coverage blurred them.

• Only use Claude Code? Nothing changes. Keep your CLAUDE.md exactly as it is.
• Already maintain an AGENTS.md for other tools, and want Claude Code to just use it? Make sure you're on v2.1.277 or later, delete any CLAUDE.md-as-symlink workaround, and it should load on your next session. Confirm with the "AGENTS.md loaded" line.
• Want one shared file, but need a couple of Claude-specific instructions on top? This is the pattern Anthropic recommends — a tiny CLAUDE.md that imports the shared file, then adds its own notes below:

@AGENTS.md

Use plan mode for changes under src/billing/.

  Claude reads the imported file first, then the rest. If you don't need Claude-specific content at all, a symlink works too (`ln -s AGENTS.md CLAUDE.md`), but skip it if anyone on the team is on Windows — that needs Administrator privileges or Developer Mode, and an unconfigured Git checkout will turn a committed symlink into a one-line text file.
- **Want both files loaded together, every time, no exceptions?** Set **Project instructions** to `claude-md-and-agents-md` via `/config`, or bake it into `~/.claude/settings.json`:

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

• On Bedrock, Vertex, Foundry, or with telemetry off? You don't get direct AGENTS.md reading at all right now. The @AGENTS.md import pattern above is your only path to a shared file in those environments.

The real story isn't that Claude Code gained some new capability — it's that it stopped being the reason your team maintained a fifth instructions file. If you're already juggling Codex, Cursor, or Gemini CLI alongside Claude Code, this is a genuine, if overdue, quality-of-life fix.

Just don't assume it's a drop-in replacement for CLAUDE.md on day one. The fallback-not-merge default, the hook gaps, and the missing platform support are the kind of details that bite you a week later when a teammate swears their instructions are loading and /context says otherwise. Read the precedence table twice before you delete anything.