---
title: "Claude Code Finally Reads AGENTS.md (Here's Exactly How It Works)"
description: "Claude Code was the last major holdout still insisting on its own CLAUDE.md. That changed on September 18th. Here's what AGENTS.md actually is, the precedence rules the headlines skipped, and what to do about your own setup."
date: "2026-09-20"
tags: [ai, claude-code, agents-md, developer-tools, coding-agents]
sources:
  - title: "How Claude remembers your project — AGENTS.md"
    url: "https://code.claude.com/docs/en/memory#agents-md"
  - title: "AGENTS.md — official spec"
    url: "https://agents.md/"
  - title: "Feature Request: Support AGENTS.md — anthropics/claude-code#6235"
    url: "https://github.com/anthropics/claude-code/issues/6235"
  - title: "Claude Code adds AGENTS.md fallback for repositories shared across coding agents"
    url: "https://runtimewire.com/article/claude-code-adds-agents-md-support"
---
If you work across more than one AI coding tool, you already know the tax: a `CLAUDE.md` for Claude Code, a `.cursorrules` for Cursor, a `GEMINI.md` for Gemini, maybe a `.windsurfrules` on top of that. Same instructions, four files, four places to forget an update.

`AGENTS.md` was supposed to end that, and every major coding agent except one had already adopted it. As of September 18th, that's no longer true. Here's what actually shipped, and the precedence rules that most of the coverage glossed over.

## What Is AGENTS.md, Actually {#what-is-agents-md}

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.

## What Changed in Claude Code {#what-changed}

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.

## How It Actually Works (Read This Part) {#how-it-works}

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

| Your repository has | Claude reads |
|---|---|
| An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `AGENTS.md` |
| An `AGENTS.md` *and* a `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `CLAUDE.md` files only |
| A `CLAUDE.md` that already imports `AGENTS.md` (`@AGENTS.md`) | Your `CLAUDE.md`, with `AGENTS.md` included through the import |

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**:

| Value | What loads |
|---|---|
| `claude-md-or-agents-md` | The default — CLAUDE.md, or AGENTS.md only when there's no CLAUDE.md |
| `claude-md-and-agents-md` | Both, every directory's CLAUDE.md first, then its AGENTS.md |
| `claude-md` | CLAUDE.md only, AGENTS.md ignored entirely |
| `managed-only` | Only your org's managed CLAUDE.md at launch |

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`.

## Where It Differs From CLAUDE.md {#the-differences}

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.

## What You Should Actually Do {#what-to-do}

- **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:

```markdown
@AGENTS.md

## Claude Code

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.

## Why This Matters {#why-it-matters}

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.

## TL;DR

| | Before Sept 18, 2026 | Now (v2.1.277+) |
|---|---|---|
| AGENTS.md support | None — CLAUDE.md only | Native, on by default |
| Default behavior with both files present | N/A | CLAUDE.md wins, AGENTS.md ignored |
| Want both loaded together | N/A | Set `claude-md-and-agents-md` in `/config` |
| Works on Bedrock/Vertex/Foundry | N/A | No — use `@AGENTS.md` import in a CLAUDE.md instead |
| Shows up in `/memory` or hooks | N/A | No, unless imported into a CLAUDE.md |

If you were maintaining a symlink or an import hack to fake this, you can probably delete it now. If you weren't, and you're not working across multiple agents, you can ignore this entire post.

---

**More posts:**
- [Claude Skills: What They Are, Why You Need Them, and How to Set Them Up](/blog/claude-skills-setup-guide-why-you-need-them)
- [My Actual Dev Setup: Google Antigravity + Claude Code](/blog/antigravity-claude-code-workflow-2026)
- [How I Made Claude Code Enforce OWASP Rules (So I Don't Have To)](/blog/claude-code-security-skills-owasp-accessibility)

---

*// hereshecodes.com*