Claude Code now reads AGENTS.md: how to use it and when your CLAUDE.md blocks it

Claude Code
, , , ,
1

Claude Code now reads AGENTS.md natively: starting with version 2.1.277, if your project has no CLAUDE.md, it loads AGENTS.md as project instructions, without imports or symlinks. The key detail is that “has no”: a CLAUDE.md — or even a private CLAUDE.local.md — in your working directory or any parent directory is enough for Claude to ignore AGENTS.md by default.

If your repository already feeds Codex, Cursor or Amp with a shared AGENTS.md, this is the change that lets you delete that single-line CLAUDE.md you only kept for Claude. Here’s exactly how it works, how to change the default behavior, and which old workarounds you can remove.

What is AGENTS.md?

AGENTS.md is a Markdown file at the root of your repository with the instructions a code agent needs to work on that project: build and test commands, conventions, structure. Unlike CLAUDE.md, it doesn’t belong to any one tool: Codex, Amp and Cursor already read it, which is why it became the shared format for teams using multiple agents at once.

Claude Code, Anthropic’s terminal agent, had its own instruction file — CLAUDE.md — and until now ignored AGENTS.md unless you manually imported it. If you’re not using it yet, start with our guide Claude Code: what it is, why it matters, and how to get started.

How do I use AGENTS.md with Claude Code?

You don’t have to do anything: update to version 2.1.277 or later, and if your project has no CLAUDE.md, Claude Code reads your AGENTS.md automatically. The changelog entry from September 18, 2026 sums it up in one line: “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under ‘Project instructions’ in /config (not yet on Bedrock, Vertex or Foundry).”

Under the hood, it’s a built-in plugin called agents-md, and Anthropic published its code in the Claude Code repository, at mods/agents-md. An AGENTS.md loaded this way is treated as a project instruction file: same place in context and same treatment as a CLAUDE.md.

In practice, Claude reads it at these times:

  • When starting a session, it loads each AGENTS.md and .claude/AGENTS.md from your working directory and parent directories. In an interactive session you’ll see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
  • While working in subdirectories, it loads the AGENTS.md from that subdirectory when it opens a file there with the Read tool, as long as the subdirectory has no CLAUDE.md of its own.
  • Within each AGENTS.md, @path imports are expanded and claudeMdExcludes patterns are applied, just like with CLAUDE.md.

What it does not read: AGENTS.local.md, AGENTS.override.md or anything inside a .agents/ directory. So if you were expecting Claude to also pick up .agents/skills, it won’t; that was one of the first complaints in the Hacker News thread.

AGENTS.md or CLAUDE.md: which does Claude Code read?

By default CLAUDE.md wins and AGENTS.md is ignored completely. The official documentation summarizes it this way:

Your repository has Claude reads
An AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your working directory or parent directories Your AGENTS.md
An AGENTS.md and a CLAUDE.md or CLAUDE.local.md in your working directory or parent directories Only your CLAUDE.md files
A CLAUDE.md that already imports AGENTS.md Your CLAUDE.md, with AGENTS.md included via the import

What matters is which files count for that check:

  • Count (block AGENTS.md): CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any parent directory.
  • Don’t count (load alongside AGENTS.md): your personal ~/.claude/CLAUDE.md, your organization’s managed CLAUDE.md, and files in .claude/rules/.

That second list is good news: your personal global instructions still work in a repository that only has AGENTS.md.

The catch is CLAUDE.local.md. It’s the file you create for personal notes that don’t get pushed to the repository, and because it counts, adding one to a project that depends on AGENTS.md makes Claude stop reading AGENTS.md for you, without warning, while your teammates still get it. If you want both, change the setting in the next section.

How do I make Claude Code read both CLAUDE.md and AGENTS.md?

Open /config in a Claude Code session and change Project instructions to claude-md-and-agents-md. There are four possible values:

Value What Claude reads
claude-md-or-agents-md Your CLAUDE.md files, or your AGENTS.md when there’s no CLAUDE.md or CLAUDE.local.md in your working directory or parent directories. Default value.
claude-md-and-agents-md Both. In each directory, first CLAUDE.md then AGENTS.md. An AGENTS.md that your CLAUDE.md already imports or symlinks to is not loaded twice.
claude-md Only CLAUDE.md: the previous behavior.
managed-only Only the CLAUDE.md managed by your organization and automatic memory on startup.

You can also set it in a settings file, under the built-in plugin ID in pluginConfigs:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```Works in `~/.claude/settings.json`, in a file passed with `--settings`, or in your organization's managed settings. It's **ignored** in the project's `.claude/settings.json` and in local settings, so you can't upload it to the repository for your entire team. The change applies from your next message and in every new session.

For most teams mixing tools, `claude-md-and-agents-md` is the setting you really want: shared rules in `AGENTS.md`, Claude-specific extras in `CLAUDE.md`, and nothing duplicated.

## Why Doesn't Claude Code Read My AGENTS.md?

Almost always because there's a `CLAUDE.md` somewhere in your path. The documentation checklist, in order:

1. Look for a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in your working directory or any parent directory (excluding `~/.claude/CLAUDE.md`). If it exists, Claude reads it instead of `AGENTS.md`, unless you switch to `claude-md-and-agents-md`.
2. Run `claude --version` and confirm you have version 2.1.277 or later.
3. Check if your session is one that doesn't support the feature (next section).
4. Open `/config` and verify that **Project instructions** is not set to `claude-md` or `managed-only`. If the setting doesn't appear, your session doesn't support it.

One more thing that'll confuse you: when Claude reads `AGENTS.md` directly, it **doesn't appear** in `/context` or `/memory`. Look for the line `AGENTS.md loaded` at the start of the session, or just ask Claude what his project instructions say.

## Does AGENTS.md Work on Bedrock, Vertex, or Without Telemetry?

Not yet. According to the documentation as of September 19, 2026, Claude Code only reads `CLAUDE.md` in these cases:

- You're using a version earlier than 2.1.277.
- Your session doesn't download feature flags from Anthropic: for example on Amazon Bedrock or another external provider, or with telemetry disabled. (The changelog mentions Bedrock, Vertex, and Foundry.)
- It's your **first session** after installing or updating. Claude reads `AGENTS.md` starting from the next one.
- You disabled the built-in `agents-md` plugin in `/plugin`.

In any of those cases, keep a `CLAUDE.md` alongside your `AGENTS.md` with the import:

```markdown
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude reads the imported file first, then anything you add below it.

Can I delete the symlink or the @AGENTS.md from my CLAUDE.md?

In most cases, yes. The documentation covers every common setup:

  • A CLAUDE.md that only contains @AGENTS.md: you can leave it; Claude never reads AGENTS.md twice, regardless of the setting. Delete it if it has nothing else, except if some of your sessions run on Bedrock, Vertex, or without telemetry.
  • A CLAUDE.md that asks Claude in words to read AGENTS.md: delete it, or replace the phrase with a real @AGENTS.md import. A phrase only works if Claude decides to open the file.
  • A CLAUDE.md that is a symlink to AGENTS.md: nothing breaks; delete it if you want. If anyone on your team uses Windows, remove it: Git checks out a versioned symlink as plain text, unless core.symlinks is enabled.
  • A SessionStart hook that prints AGENTS.md: remove it. Now that Claude reads the file directly, the hook adds a second copy to your context.

If you’re coming from Cursor, we cover the complete migration in How to Switch from Cursor to Claude Code Without Losing Your Project Context.

Why Did Anthropic Take So Long to Support AGENTS.md?

The GitHub issue #6235, “Feature Request: Support AGENTS.md”, asked for exactly this and pointed out that Codex, Amp, Cursor, and others were standardizing on that file. [VERIFY: opening date / number of reactions] The commenters themselves describe it as the most upvoted issue in the repository.

It ended up closed, but not with a solution—instead with a response from Boris Cherny that referred to the two workarounds: a CLAUDE.md with @AGENTS.md or a symlink. The thread didn’t take it well. The most repeated objection: the import is trivial for a single file at the root, but a monorepo with dozens of nested AGENTS.md files would need a filler CLAUDE.md next to each one.

Version 2.1.277 is the real solution that closure never delivered. The reaction on Hacker News was mostly relief with a touch of reproach: “Time to delete the symlinks” alongside “it’s the absolute bare minimum”.

Grego’s reading: this was never about a filename

Two lines of fallback logic took over a year, and no one in that GitHub thread believed it was an engineering problem. A CLAUDE.md in a public repository is a small billboard: every developer who clones it sees what tool the team uses. AGENTS.md is neutral ground: Codex, Cursor, and Amp already read it.

Native support is Anthropic acknowledging that neutral ground is where team configuration is going to live. But notice the shape of the concession: CLAUDE.md still wins by default, the setting can’t be versioned at the project level, and .agents/ is still ignored. It’s interoperability on Claude’s terms.

For a CTO, the practical conclusion is simpler than the politics: if your teams combine code agents, adopt AGENTS.md as the source of truth now and treat each tool’s own file as an optional layer on top. All major tools already read it. The file your repository depends on shouldn’t carry a vendor’s name.

For another angle on this same fight over configuration between tools, see how Codex went in the opposite direction and started importing Claude Code’s configuration: One Command and Codex Brings All Your Config from Cursor and Claude Code—Here’s How Import Works.