# Does Claude Code read AGENTS.md?

> Source: <https://gethrbr.com/blog/does-claude-code-read-agents-md>
> Published: 2026-10-06 00:00:00+00:00

Blog

# Does Claude Code read AGENTS.md?

Published: October 6, 2026

Yes. Claude Code reads `AGENTS.md` since v2.1.277, and since v2.1.281 it does so in every session, Bedrock, Vertex and telemetry-off included. By default it reads `AGENTS.md` only when the project has no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` from the working directory up, and two common moves create one without telling you.

Checked on 2026-10-05 against Claude Code 2.1.289, and again on 2026-10-06 against 2.1.291, using the [memory docs](https://code.claude.com/docs/en/memory#agents-md), the [changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md), the plugin's own [README](https://github.com/anthropics/claude-code/blob/main/mods/agents-md/README.md) and the open issues linked below. Answers written before September say no. Answers written in the week after launch say it needs telemetry on. Both were right when they were written.

## Which version of Claude Code supports AGENTS.md?

| Version | Published | What changed | 
|---|---|---|
| 2.1.277 | 2026-09-18 | “In a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.” The mode is a row in `/config` . Sessions without fetched feature flags (telemetry off, Bedrock, Vertex, Foundry, gateways) still skipped it. | 
| 2.1.281 | 2026-09-23 | “Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled.” | 

It closed a long wait. The feature request, [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235), was opened in August 2025 and had over 5,000 thumbs up when it was closed on 2026-08-17. If you are on 2.1.277 to 2.1.280 and run with telemetry off or through a cloud provider, update; that is the whole fix.

## What are the instructionFiles modes?

The support ships as a built-in plugin, `agents-md`, with one option, `instructionFiles`. It takes four values.

| Mode | What Claude Code loads | When to pick it | 
|---|---|---|
| `claude-md` | `CLAUDE.md` files only, exactly as before 2.1.277. | You want no change in behaviour. | 
| `claude-md-or-agents-md` | The default. `CLAUDE.md` files, or`AGENTS.md` files when the project has none. | A repo set up for Codex or Cursor that never had a CLAUDE.md. | 
| `claude-md-and-agents-md` | Both. In each directory the `CLAUDE.md` files come first and the`AGENTS.md` after. A file already imported or symlinked is not read twice. | Shared rules in AGENTS.md plus Claude-only notes in CLAUDE.md. Also the fix for both traps below. | 
| `managed-only` | Only the organization's managed `CLAUDE.md` and auto memory at launch. Project, local and user files and every`AGENTS.md` are dropped. | Reviewing an untrusted repo, or a locked-down fleet. | 

The option was first keyed `projectInstructions`, with the values `claude`, `agents-fallback`, `both` and `none`. The README says a value stored under the old key is still honoured for now, and the transcript says how it was read.

## Where do I set it?

In a session, `/config` and the row called **Project instructions**. By hand, in `~/.claude/settings.json`, a `--settings` file, or managed settings. The docs now give the plugin's ID as `cc-plugin-agents-md@builtin`. Before v2.1.285 it was `agents-md@builtin`, and 2.1.285 and later read either:

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

A project's `.claude/settings.json` is not read for this option, and neither is `.claude/settings.local.json`. You cannot commit the mode to a repo and have every teammate pick it up. Each person sets it for themselves, or an admin sets it in managed settings. A change applies from the next message you send.

## What happens if both AGENTS.md and CLAUDE.md exist?

Under the default, Claude Code reads your `CLAUDE.md` files and ignores `AGENTS.md`. The check is narrower than it sounds.

- **These count** and switch`AGENTS.md` off: a`CLAUDE.md` ,`.claude/CLAUDE.md` or`CLAUDE.local.md` in the working directory or any directory above it.
- **These do not count** and load alongside`AGENTS.md` : your`~/.claude/CLAUDE.md` , the organization's managed`CLAUDE.md` , and`.claude/rules/` files.
- **Never read** :`AGENTS.local.md` ,`AGENTS.override.md` (a Codex convention), and anything under`.agents/` .

## Why is Claude Code ignoring my AGENTS.md?

Since 2.1.281 the answer is almost always a file that counts as a `CLAUDE.md`. Two ways to get one are easy to miss, and neither prints a warning.

**A `CLAUDE.local.md`.** It is the personal, gitignored file. Add one to keep your own notes in a repo that runs on `AGENTS.md`, and Claude stops reading `AGENTS.md` for you, and only for you. [anthropics/claude-code#96117](https://github.com/anthropics/claude-code/issues/96117) reproduces it five runs out of five, including a `CLAUDE.local.md` in a subdirectory switching off the root's `AGENTS.md`. The memory docs now say so in a note.

**Running `/init`.** It writes a `CLAUDE.md` even when the project keeps its instructions in `AGENTS.md`, and under the default mode that new file takes over. The command a new teammate runs to set up is the one that drops the shared rules. [anthropics/claude-code#97004](https://github.com/anthropics/claude-code/issues/97004) was still open on 2026-10-05, and the `/init` prompt in 2.1.286 still targets `CLAUDE.md`.

The fix for both is the same: set the mode to `claude-md-and-agents-md`, or put `@AGENTS.md` at the top of the `CLAUDE.md`. The rarer causes:

- You are on a version before 2.1.277, or on 2.1.277 to 2.1.280 with telemetry off or a cloud provider.
- It is the first session after upgrading from 2.1.276 or earlier. The docs say Claude reads AGENTS.md from the next session on.
- The built-in `agents-md` plugin is turned off in`/plugin` .

The quickest tell: if `/config` has no **Project instructions** row, this session cannot load `AGENTS.md` at all. Past that, the sources disagree. The memory docs say a loaded file shows a line such as `no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md` in the conversation, and that `/memory` lists it. The plugin's README, changed on 2026-09-30, says the line goes to the debug log and that `/memory` does not know `AGENTS.md` files. If you see neither, run `claude --debug`, or ask Claude what its project instructions say.

## How did you use AGENTS.md with Claude Code before?

Four workarounds were common. The docs now say what to do with each.

- **A `CLAUDE.md` containing `@AGENTS.md`** . Keep it if the` CLAUDE.md` holds anything else. The import never causes a double read, whatever the mode, and it keeps a later`CLAUDE.local.md` or`/init` from switching the shared file off.
- **A `CLAUDE.md` symlinked to `AGENTS.md`** . Harmless; Claude reads the content once. On Windows clones Git checks the link out as a one-line text file unless`core.symlinks` is on.
- **A `SessionStart` hook that prints `AGENTS.md`** . Remove it. With native support it adds a second copy.
- **A `CLAUDE.md` that says “read AGENTS.md”** . Replace the sentence with an import. In words, Claude only sees the file if it decides to open it.

For a team, the one-line import is still the setup that survives what each person adds to their own checkout:

```
# CLAUDE.md
@AGENTS.md

# Claude-only notes go below the import
```

## Is AGENTS.md treated exactly like CLAUDE.md?

Almost. Per the docs, an `AGENTS.md` read through the setting does not fire `InstructionsLoaded` hooks, does not load from `--add-dir` directories, and loads an `@` import from outside the working directory only if you already approved external imports for that project. A nested one attaches when Claude opens a file in that directory with the Read tool, or, since v2.1.290, when a file under it is @-mentioned, as long as the directory has no `CLAUDE.md` of its own. For most repos none of this matters. For a monorepo with per-package files, it is worth a test.

## One file for every agent. Who keeps it true?

Native support settles where the instructions live. Claude Code, Codex, Cursor, Copilot and Antigravity CLI can now all read one `AGENTS.md`; the comparison is in [AGENTS.md vs CLAUDE.md](https://gethrbr.com/blog/agents-md-vs-claude-md). It does not settle who writes the file, or when a line in it stops being true.

Take one decision. In `#eng-payments` the team agrees that webhook handlers acknowledge with a 200 and enqueue, and never do the work inline. That line reaches `AGENTS.md` only if someone remembers to open a pull request. When the queue is replaced next quarter, the line stays until someone remembers to delete it.

Harbor is built for that gap. It reads where the team already decides: Slack, pull request review threads, docs. A person approves what it finds, or you let policy approve the routine ones; you set the gate. Each agent gets the facts that apply to its task on the first turn, and Harbor counts how often each one was served and how often an answer cited it, so a line that is served and never cited shows up. `harbor init` installs the hooks for Claude Code, Codex and Cursor in one pass. The [quickstart](https://gethrbr.com/docs/quickstart) takes a few minutes.

Related: whether to [commit CLAUDE.md and the .claude folder](https://gethrbr.com/blog/should-you-commit-claude-md), and [how long the file should be](https://gethrbr.com/blog/how-long-should-claude-md-be) once every agent is reading it.

## Questions

### Why is Claude Code ignoring my AGENTS.md?

Almost always because a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it, which switches AGENTS.md off under the default mode. A personal CLAUDE.local.md and running /init both create one without a warning. On 2.1.277 to 2.1.280, telemetry off or a cloud provider such as Bedrock also skipped it; 2.1.281 fixed that.

### Does Claude Code read AGENTS.md on Bedrock or Vertex?

Yes, since v2.1.281, published 2026-09-23. Before that, sessions on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways or with telemetry disabled read CLAUDE.md files only.

### Can I set instructionFiles in the project .claude/settings.json?

No. Claude Code reads the option only from ~/.claude/settings.json, a --settings file, or managed settings. Project and local settings files are ignored for it, so each person or an admin has to set it.

### Do I still need a CLAUDE.md with @AGENTS.md?

On a team, it is still the safest setup. The import never makes Claude read the file twice, and it keeps AGENTS.md loading when someone adds a CLAUDE.local.md or runs /init, both of which switch the default fallback off.

### How do I load both CLAUDE.md and AGENTS.md in Claude Code?

Set Project instructions in /config to claude-md-and-agents-md, or set pluginConfigs cc-plugin-agents-md@builtin options instructionFiles (agents-md@builtin before v2.1.285) to that value in your user settings. Each directory's CLAUDE.md files load first and its AGENTS.md after them.