# Claude Code AGENTS.md: When It's Read, vs CLAUDE.md, and How to Use Both (Tested)

> Claude Code reads AGENTS.md since 2.1.277, but only when no CLAUDE.md or CLAUDE.local.md sits in your project or above it. What I saw in seven folder setups, AGENTS.md vs CLAUDE.md, why Claude Code ignores your AGENTS.md, and how to make it read both.

By Tahir Nazir · Published 2026-11-21 · Updated 2026-11-21
Canonical: https://www.its-tahir.com/blog/claude-code-agents-md

**Yes, Claude Code reads `AGENTS.md`, since version 2.1.277. But by default it reads it only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or any folder above it. If one exists, Claude Code reads that and skips `AGENTS.md` without a warning. To have it read both, put `@AGENTS.md` at the top of your `CLAUDE.md`, or change **Project instructions** in `/config` from its default, `claude-md-or-agents-md`, to `claude-md-and-agents-md`.** I tested seven folder setups on Claude Code 2.1.302, and each behaved as Anthropic's docs describe.

| Your project has | Claude Code reads | To read both |
|---|---|---|
| `AGENTS.md` only | `AGENTS.md` | Nothing to do |
| `AGENTS.md` and `CLAUDE.md` | `CLAUDE.md` only | `@AGENTS.md` at the top of `CLAUDE.md` |
| `AGENTS.md` and `CLAUDE.local.md` | `CLAUDE.local.md` only | `/config` → Project instructions → `claude-md-and-agents-md` |
| `CLAUDE.md` that contains `@AGENTS.md` | Both, `AGENTS.md` first | Already done |
| `AGENTS.md` and your `~/.claude/CLAUDE.md` | Both: the user file doesn't count | Nothing to do |
| `AGENTS.local.md` or `.agents/AGENTS.md` | Neither | Rename to `AGENTS.md`, or import it |

*Last reviewed 21 November 2026, against Anthropic's memory docs and the Claude Code changelog to 2.1.330. I ran the tests on Claude Code 2.1.302 on Windows 11, with `claude -p`, Haiku 5.5 and default settings, in throwaway folders under my temp directory with no `CLAUDE.md` above them. Each run cost under a cent at list price.*

![Does Claude Code read AGENTS.md? My test on Claude Code 2.1.302, Windows 11: AGENTS.md only loads AGENTS.md; AGENTS.md plus CLAUDE.md loads CLAUDE.md only; AGENTS.md plus CLAUDE.local.md loads CLAUDE.local.md only; a CLAUDE.md containing @AGENTS.md loads both; Project instructions set to claude-md-and-agents-md loads both; AGENTS.md and .claude/AGENTS.md one folder up both load; AGENTS.local.md and .agents/AGENTS.md are not read.](https://www.its-tahir.com/blog/claude-code-agents-md/claude-code-agents-md-which-file-loads.svg)

*Seven folders, one codeword per file: what Claude Code could see in each.*

## Does Claude Code read AGENTS.md?

**Yes. Claude Code 2.1.277 and later reads `AGENTS.md` as your project instructions when you have no `CLAUDE.md` of your own.** The changelog entry for 2.1.277 says it in one line: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in `/config`". Before that release you had to import the file from a `CLAUDE.md`, so older guides that say Claude Code ignores `AGENTS.md` describe versions before 2.1.277.

Here's which files count for that "no `CLAUDE.md`" check, from [Anthropic's memory docs](https://code.claude.com/docs/en/memory):

- **Count, so Claude Code reads them instead of `AGENTS.md`:** a `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or any directory above it.
- **Don't count, and load alongside `AGENTS.md`:** your `~/.claude/CLAUDE.md`, your organization's managed `CLAUDE.md`, and `.claude/rules/` files.

That second list matters. My machine has a `~/.claude/CLAUDE.md` full of personal rules, and Claude Code still read `AGENTS.md` in every test folder that had no project `CLAUDE.md`.

## How I tested which file Claude Code reads

**I gave every instruction file a different codeword, then asked Claude to list the codewords in its project instructions with all file tools blocked**, so it could only answer from what Claude Code had loaded at startup. The command, run inside each folder:

```bash
claude -p "Without using any tools, list every codeword that appears in your project instructions (not in user-level instructions). Reply with just the codewords separated by commas, or NONE." \
  --model haiku --strict-mcp-config \
  --disallowedTools "Read Bash Glob Grep LS PowerShell" --output-format json
```

What came back, verbatim:

| Folder | Files | Claude's answer |
|---|---|---|
| a | `AGENTS.md` (FALCON-AGENTS) | `FALCON-AGENTS` |
| b | `AGENTS.md` + `CLAUDE.md` (OTTER-CLAUDE) | `OTTER-CLAUDE` |
| c | `AGENTS.md` + `CLAUDE.md` whose first line is `@AGENTS.md` | `FALCON-AGENTS, OTTER-CLAUDE` |
| d | `AGENTS.md` + `CLAUDE.local.md` (LYNX-LOCAL) | `LYNX-LOCAL` |
| e | `AGENTS.local.md` + `.agents/AGENTS.md` only | `NONE` |
| f | Same as b, run with `--settings` holding the `claude-md-and-agents-md` JSON shown further down | `OTTER-CLAUDE, FALCON-AGENTS` |
| g | Run from `child/`, with `AGENTS.md` and `.claude/AGENTS.md` in the parent | `GULL-PARENT, WREN-DOTCLAUDE` |

Folder d is the one that catches people: one personal `CLAUDE.local.md` and the team's `AGENTS.md` silently drops out of your session. Folder f listed the `CLAUDE.md` codeword first, which is consistent with the order the docs give for the "both" setting: each folder's `CLAUDE.md` first, its `AGENTS.md` after. Folder g shows Claude Code walking up the tree for `AGENTS.md` exactly as it does for `CLAUDE.md`.

## What is AGENTS.md?

**`AGENTS.md` is a plain Markdown file, usually at the root of a repository, that tells AI coding agents how to work on the project: build and test commands, code style, and conventions.** It is an open format rather than one vendor's file, so Codex, Cursor, Copilot, Gemini CLI, Claude Code and other agents can all read the same instructions. Think of it as a README written for agents instead of people.

## AGENTS.md vs CLAUDE.md: what's the difference?

**They hold the same kind of content, project instructions in plain Markdown, but `CLAUDE.md` is Claude Code's own file and `AGENTS.md` is a shared format that other coding agents read too.** The [AGENTS.md project](https://agents.md/) lists Codex, Cursor, Copilot, Gemini CLI, Jules, Aider, Zed, Warp and others as readers, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. If your team uses more than one agent, `AGENTS.md` is the file they can all share.

Inside Claude Code, an `AGENTS.md` that it reads directly behaves like a `CLAUDE.md` in most ways: `@path` imports expand, `claudeMdExcludes` patterns apply, and a subdirectory's file loads when Claude opens a file there with the Read tool. The docs list three places it differs:

| | `CLAUDE.md` | `AGENTS.md` read through Project instructions (not imported) |
|---|---|---|
| `InstructionsLoaded` hooks | Fire | Don't fire (they do for an `AGENTS.md` that a `CLAUDE.md` imports or symlinks to) |
| Folders added with `--add-dir`, with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` set | Their `CLAUDE.md` loads | Their `AGENTS.md` doesn't |
| An `@path` import of a file outside your working directory | Claude Code asks you to approve it | Loads only if you already approved external imports for this project, with no prompt |

If you rely on an `InstructionsLoaded` hook for auditing, or on `--add-dir` for a shared folder, import `AGENTS.md` from a `CLAUDE.md` rather than letting Claude Code read it directly.

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

**Almost always because a `CLAUDE.md` or `CLAUDE.local.md` exists somewhere on the path from your project folder up to the filesystem root.** Work through these in order:

1. **Look for a blocking file.** Check your working directory and every folder above it, other than `~/.claude/`, for `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md`. In a monorepo, a `CLAUDE.md` at the repository root blocks every package's `AGENTS.md`.
2. **Check your version.** Run `claude --version`. You need 2.1.277 or later, and 2.1.281 or later on Amazon Bedrock, Google Cloud's Agent Platform (Vertex AI), Microsoft Foundry, an LLM gateway, or with telemetry off.
3. **Check the setting.** Type `/config` and find **Project instructions**. If it says `claude-md` or `managed-only`, change it. If the setting isn't there at all, your session can't load `AGENTS.md` directly.
4. **Check the plugin.** The reader is a built-in plugin, `cc-plugin-agents-md@builtin`. If you disabled it in `/plugin`, re-enable it.
5. **Start a new session.** In some cases the first session after upgrading from 2.1.276 or earlier skips `AGENTS.md`; the docs say it loads from the next one.

| Symptom | Cause | Fix |
|---|---|---|
| Claude follows `CLAUDE.md` but not `AGENTS.md` | Default `claude-md-or-agents-md` picked `CLAUDE.md` | `@AGENTS.md` at the top of `CLAUDE.md` |
| `AGENTS.md` stopped working after you added personal notes | `CLAUDE.local.md` counts as a `CLAUDE.md` | Set Project instructions to `claude-md-and-agents-md` |
| No **Project instructions** row in `/config` | Version before 2.1.277, plugin disabled, or first session after upgrade | Update, re-enable in `/plugin`, or start a new session |
| Works locally, not on Bedrock or Vertex AI | Version before 2.1.281 | `claude update` |
| A package's `AGENTS.md` is ignored in a monorepo | A root `CLAUDE.md` blocks it | Import it, or use the "both" setting |
| Instructions from an unexpected `AGENTS.md` appear | One sits in a folder above your project | Move or delete it, or add it to `claudeMdExcludes` |
| `AGENTS.local.md` or `AGENTS.override.md` ignored | Claude Code doesn't read those names | Rename to `AGENTS.md`, or move it to `CLAUDE.local.md` and set Project instructions to `claude-md-and-agents-md` |

## How do I check which file Claude Code loaded?

**Run `/memory` and look for your `AGENTS.md` path in the list, or run `/context all` and look under Memory files.** Both list a directly read `AGENTS.md` from 2.1.280 on; before that, the docs suggest asking Claude what its project instructions say, which is what my codeword test does.

Anthropic's docs also say an interactive session shows a line such as `no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md`. Reading the bundled code of Claude Code 2.1.329, I found that message sent to the debug log rather than the conversation. That differs from the docs, so if you don't see the line, trust `/memory` instead.

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

**Use an import if you want a setup that works everywhere; use the setting if you only need it on your own machine.**

**Option 1: import `AGENTS.md` from `CLAUDE.md`.** This is the one I'd commit to a shared repository, because it works on every version, in every session type, and needs no per-user setting:

```markdown
@AGENTS.md

## Claude Code

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

Claude reads the imported file first, then the rest of `CLAUDE.md`; folder c in my test listed the codewords in that order. Keeping the import never makes Claude Code read `AGENTS.md` twice, even with the "both" setting on.

**Option 2: change Project instructions.** Type `/config`, find **Project instructions**, and pick one of these four values:

| Value | What Claude Code reads |
|---|---|
| `claude-md-or-agents-md` (default) | `CLAUDE.md` files, or `AGENTS.md` when you have no `CLAUDE.md` or `CLAUDE.local.md` |
| `claude-md-and-agents-md` | Both: each folder's `CLAUDE.md` files first, then its `AGENTS.md` |
| `claude-md` | `CLAUDE.md` files only |
| `managed-only` | Only your organization's managed `CLAUDE.md` and auto memory at launch |

To set it in a file instead, add it to your user `~/.claude/settings.json`. Claude Code ignores this entry in project and local settings files, so you can't commit it for your team:

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

Before 2.1.285 the plugin ID was `agents-md@builtin`; 2.1.285 and later read either. My folder f test passed the same JSON with `--settings`, which Claude Code also honours. To start from a template, my [CLAUDE.md and AGENTS.md generator](https://tools.its-tahir.com/claude-md-generator) builds both files and flags stray `@` imports, and the [settings builder](https://tools.its-tahir.com/claude-code-settings) checks the JSON.

## Should I symlink CLAUDE.md to AGENTS.md?

**Only if nobody on the project uses Windows.** On macOS and Linux, `ln -s AGENTS.md CLAUDE.md` gives Claude Code a `CLAUDE.md` that is your `AGENTS.md`, and Claude Code reads the content once. The docs list two catches:

- **Windows:** creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a one-line text file unless `core.symlinks` is on. That clone ends up with a `CLAUDE.md` that just says `AGENTS.md`.
- **Editing:** Claude's Edit and Write tools refuse to write through a symlink and point Claude at the target, `AGENTS.md`, instead.

The `@AGENTS.md` import has neither problem, and it lets you add Claude-only lines underneath. If you already have a symlink, you can leave it: the docs say nothing needs to change.

## Where does Claude Code look for AGENTS.md?

**In your working directory and every folder above it at startup, and in a subdirectory when Claude opens a file there with the Read tool.** In each folder it looks for both `AGENTS.md` and `.claude/AGENTS.md`, as my folder g test showed. A subdirectory's `AGENTS.md` loads only if that subdirectory has none of the three `CLAUDE.md` files of its own.

It does **not** read `AGENTS.local.md`, `AGENTS.override.md`, or anything under a `.agents/` folder, even though some other agents use those names.

There's no separate global `AGENTS.md` setting. Your global instructions file is `~/.claude/CLAUDE.md`, and it loads alongside a project's `AGENTS.md` without blocking it. But because Claude Code walks upward, an `AGENTS.md` in your home folder, or in a folder like `Downloads` where you unpack other people's projects, loads into every project beneath it that has no `CLAUDE.md`. Check the folders above a project before you trust what Claude has been told.

## Should I switch my CLAUDE.md to AGENTS.md?

**If you use more than one coding agent, yes: move the shared instructions into `AGENTS.md` and keep a short `CLAUDE.md` that imports it.** If you only use Claude Code, there's no reason to switch; `CLAUDE.md` gets the hooks and `--add-dir` behaviour that a directly read `AGENTS.md` doesn't.

If you set Claude Code up to read `AGENTS.md` before 2.1.277, the docs say what to do with each old workaround:

- **A `CLAUDE.md` that says in words "read AGENTS.md":** replace the sentence with an `@AGENTS.md` import, or delete the file. Words only work if Claude decides to open the file.
- **A `SessionStart` hook that prints `AGENTS.md`:** remove it, or Claude gets two copies.
- **A `CLAUDE.md` with `@AGENTS.md`, or a symlink:** leave them.

Going the other way, from `AGENTS.md` to a `CLAUDE.md`, Claude Code has two commands. `/init` with `CLAUDE_CODE_NEW_INIT=1` set reads your `AGENTS.md` into the `CLAUDE.md` it generates, and `/import` appends a one-time copy of `AGENTS.md` to the matching `CLAUDE.md`. Both make a copy, so the two files can drift apart afterwards; the `@AGENTS.md` import doesn't.

Either way, keep the file short. Every line of `AGENTS.md` or `CLAUDE.md` loads into context at the start of every session, so a long one costs tokens all session; I measured where Claude Code's tokens go in [why Claude Code uses so many tokens](/blog/why-claude-code-uses-so-many-tokens). Anthropic's advice for `CLAUDE.md` is to target under 200 lines per file, and it applies equally to `AGENTS.md`. My [guide to writing a CLAUDE.md](https://tools.its-tahir.com/guides/how-to-write-claude-md) applies to an `AGENTS.md` too.

## How does Claude Code's AGENTS.md support compare with Cursor's?

**Cursor reads `AGENTS.md` natively, nested files included, while Claude Code treats it as a fallback for `CLAUDE.md`.** Cursor also has its own `.mdc` rule files, each declaring when it applies, per [Cursor's rules docs](https://cursor.com/docs/rules). I compared the two loaders in detail in [Claude Code vs Cursor: AGENTS.md, CLAUDE.md and Cursor rules](/blog/claude-code-vs-cursor-context-management), and my [Cursor rules converter](https://tools.its-tahir.com/cursor-rules-converter) turns `.mdc` or `.cursorrules` files into `AGENTS.md` or `CLAUDE.md` and lists what doesn't carry over.

## Which Claude Code versions changed AGENTS.md support?

| Version | Change |
|---|---|
| 2.1.277 | Added: with no `CLAUDE.md`, Claude Code reads `AGENTS.md` instead; Project instructions in `/config` |
| 2.1.280 | `/memory` and `/context` list an `AGENTS.md` that Claude Code read directly (per the docs) |
| 2.1.281 | Works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and with telemetry off |
| 2.1.285 | Settings ID renamed from `agents-md@builtin` to `cc-plugin-agents-md@builtin`; both still read (per the docs) |
| 2.1.290 | Fixed a subdirectory's `AGENTS.md` not being attached when a file under it is @-mentioned |
| 2.1.290 | Fixed an `AGENTS.md` symlinked outside the working folders loading despite `blockReadsOutsideWorkingDirectories` or a `Read` deny rule |
| 2.1.330 | Fixed the Project instructions picker in `/config` showing only one of its four choices in a 24-row fullscreen window |

**Key takeaways**

- Claude Code reads AGENTS.md since 2.1.277, but by default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md is in your project folder or above it.
- A personal CLAUDE.local.md silently turns AGENTS.md off; your ~/.claude/CLAUDE.md does not.
- To read both, put @AGENTS.md at the top of CLAUDE.md (works everywhere) or set Project instructions to claude-md-and-agents-md in /config (your machine only).
- Claude Code walks upward for AGENTS.md and .claude/AGENTS.md, so a file in a parent folder loads too. It never reads AGENTS.local.md or .agents/.
- Check what loaded with /memory or /context all. On Bedrock, Vertex AI or a gateway, you need 2.1.281 or later.
- Prefer the @AGENTS.md import over a symlink if anyone uses Windows.

## FAQ

## Related

- [Claude Code not working? 30+ errors and how to fix them](/blog/claude-code-troubleshooting)
- [Claude Code vs Cursor: AGENTS.md, CLAUDE.md and Cursor rules](/blog/claude-code-vs-cursor-context-management)
- [Why Claude Code uses so many tokens](/blog/why-claude-code-uses-so-many-tokens)
- [Claude Code mods](/blog/claude-code-mods)
- [Claude Code agent teams](/blog/claude-code-agent-teams)

## FAQ

### Does Claude Code read AGENTS.md?

Yes, since Claude Code 2.1.277, but by default only when your project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it. If one of those exists, Claude Code reads it and skips AGENTS.md. Your personal ~/.claude/CLAUDE.md doesn't count for that check, so it never blocks AGENTS.md.

### What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is the shared file; CLAUDE.md is Claude Code's own. Both are Markdown files of instructions a coding agent reads before it works on your repository, and AGENTS.md is an open format that Codex, Cursor, Copilot, Gemini CLI and many other agents read. Claude Code treats an AGENTS.md read through its Project instructions setting much like a CLAUDE.md, with three differences: InstructionsLoaded hooks don't fire for it, --add-dir folders don't load it, and an @path import outside your working directory loads only if you already approved external imports for the project.

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

Usually a CLAUDE.md or CLAUDE.local.md sits in your project folder or a folder above it, so Claude Code reads that instead. Other causes: a Claude Code version before 2.1.277, Project instructions set to claude-md or managed-only in /config, the built-in AGENTS.md plugin disabled in /plugin, or the first session right after upgrading from 2.1.276 or earlier. Run /memory to see which files actually loaded.

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

Put @AGENTS.md on the first line of your CLAUDE.md and add any Claude-only instructions below it; this works in every session and on every platform. Or open /config and set Project instructions to claude-md-and-agents-md, which reads each folder's CLAUDE.md files first and its AGENTS.md after them. In my test on Claude Code 2.1.302 both methods loaded both files.

### Should I symlink CLAUDE.md to AGENTS.md?

It works on macOS and Linux with ln -s AGENTS.md CLAUDE.md, but Anthropic's docs recommend the @AGENTS.md import if anyone uses Windows: creating a symlink there needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a one-line text file unless core.symlinks is on. Claude's Edit and Write tools also refuse to write through the link.

### Is there a global AGENTS.md for Claude Code?

Not as a setting. The global file is ~/.claude/CLAUDE.md, and it loads alongside AGENTS.md without blocking it. But Claude Code reads AGENTS.md and .claude/AGENTS.md in every folder above your project, so one placed in your home folder loads for every project beneath it that has no CLAUDE.md. My parent-folder test loaded both files from one level up.

### Does CLAUDE.local.md stop Claude Code reading AGENTS.md?

Yes. CLAUDE.local.md counts as a CLAUDE.md for the check, so adding one for your own uncommitted notes makes Claude Code read it instead of your AGENTS.md. In my test a folder with AGENTS.md and CLAUDE.local.md loaded only CLAUDE.local.md. To keep both, set Project instructions to claude-md-and-agents-md in /config.

### Does Claude Code read AGENTS.local.md or .agents/AGENTS.md?

No. Anthropic's docs list AGENTS.local.md, AGENTS.override.md and anything under a .agents/ folder as not read, and in my test a folder holding only AGENTS.local.md and .agents/AGENTS.md gave Claude no project instructions at all.

## Sources

- [How Claude remembers your project: AGENTS.md (Claude Code docs)](https://code.claude.com/docs/en/memory)
- [Claude Code changelog: AGENTS.md support, 2.1.277 to 2.1.330](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
- [AGENTS.md: a simple, open format for guiding coding agents](https://agents.md/)
- [Rules (Cursor docs)](https://cursor.com/docs/rules)
