Claude Code Not Reading AGENTS.md? 19 Tests, 4 Fixes

Short answer: Claude Code reads your AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder you start it from, or in any folder above it. If one exists, AGENTS.md is skipped with no warning. Put @AGENTS.md on line one of CLAUDE.md, or switch Project instructions to load both.

You wrote one rules file, AGENTS.md, so every coding agent on your team follows the same house rules. Codex reads it. Cursor reads it. Claude Code reads it now too. Except when it quietly does not.

That silent skip costs real time. Claude runs the wrong test command, edits a folder you banned, and you blame the model. Below is the exact rule, the four traps I hit in 19 test setups, and a one-line fix for each.

What is AGENTS.md, and why does Claude Code care? §

AGENTS.md is a shared rules file that most coding agents read, and Claude Code finally reads it too, but only as a fallback.

Start with the basics. A coding agent (an AI app that reads your files and runs commands for you) knows nothing about your project when it starts. It only knows what sits in its context (the text the model can see while it answers).

An instruction file (a plain text file of house rules) fixes that. The agent pastes the file into its context before your first message. “Use pnpm, not npm.” “Never touch the billing folder.” Now the model knows.

Claude Code’s own instruction file is called CLAUDE.md. Almost every other agent reads one called AGENTS.md. So teams kept two copies and watched them drift apart. Claude Code reading AGENTS.md was meant to end that.

One thing worth knowing up front: when AGENTS.md does load, it carries full weight. I captured the hidden text Claude Code sends. AGENTS.md sits in the same block as CLAUDE.md, under the line “These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.” It is not a weaker, optional hint.

So the problem is never how strongly Claude treats AGENTS.md. The problem is whether it gets loaded at all.

How did I check what Claude Code actually reads? §

I pointed Claude Code at a fake server on my own machine and looked at exactly what it tried to send to the model.

This matters because advice online disagrees. Some pages say Claude Code never reads AGENTS.md. Others say it always does. Both are wrong, and you only find out by looking at the real request.

Here is the idea from the ground up. Every time Claude Code answers you, it sends a request to an API (the web address where the model lives). That request contains your instruction files. If a file is not in the request, the model never saw it.

ANTHROPIC_BASE_URL is a setting that tells Claude Code which address to send requests to. Point it at a tiny recorder (a fake API that saves every request and replies with an error), and you can read what would have reached the model. No real key needed. Nothing leaves your laptop.

Save this as rec.py. It is 8 lines of Python:

from http.server import BaseHTTPRequestHandler, HTTPServer
class H(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers["content-length"]))
        open("requests.jsonl", "ab").write(body + b"\n")
        self.send_response(400); self.end_headers()
    do_GET = lambda self: (self.send_response(404), self.end_headers())
HTTPServer(("127.0.0.1", 8787), H).serve_forever()

from http.server import BaseHTTPRequestHandler, HTTPServer
class H(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers["content-length"]))
        open("requests.jsonl", "ab").write(body + b"\n")
        self.send_response(400); self.end_headers()
    do_GET = lambda self: (self.send_response(404), self.end_headers())
HTTPServer(("127.0.0.1", 8787), H).serve_forever()

Then, inside your project folder:

python3 rec.py &
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 ANTHROPIC_API_KEY=test claude -p "hi"
grep -c "a phrase from your AGENTS.md" requests.jsonl

python3 rec.py &
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 ANTHROPIC_API_KEY=test claude -p "hi"
grep -c "a phrase from your AGENTS.md" requests.jsonl

Claude Code prints an API error. That is expected, because the recorder refuses on purpose. The request is already saved. A count of 0 means your AGENTS.md never reached the model. The whole check takes about two seconds.

For the 19 tests, I put a unique marker word in each file, ran claude -p "hi" (-p runs one prompt and exits), and counted which markers showed up.

Does Claude Code read AGENTS.md? The 19 results §

Yes, when it is the only instruction file around. Add almost any CLAUDE file and AGENTS.md drops out.

The rule behind all 19 rows is one check. Claude Code walks from the folder you start in up to the top of your disk. If it finds CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md anywhere on that path, it uses the CLAUDE files and ignores AGENTS.md.

Two files do not count in that check: your personal ~/.claude/CLAUDE.md (your rules for every project) and anything in .claude/rules/. Rows 9 and 10 show both loading next to AGENTS.md. That is the good news for most solo setups.

The 4 traps that switch AGENTS.md off §

Each trap is a file or a moment that makes Claude Code think you chose CLAUDE.md, when you never did.

Trap 1: a private CLAUDE.local.md §

CLAUDE.local.md is a personal rules file you keep out of git (not shared with the team). People add one for private notes like “my test database runs on port 5433”.

The catch: it counts as a CLAUDE file. The moment you create it, your team’s AGENTS.md stops loading for you alone (row 3). Your teammates see normal behavior. You see a Claude that forgot the rules. This is the hardest one to debug, because it only breaks on one machine.

Trap 2: an old CLAUDE.md in a parent folder §

Claude Code looks above your repo, not only inside it. Plenty of people once dropped a CLAUDE.md in ~/projects/ or ~/code/ to cover every repo in there.

That forgotten file wins. In row 4, only the parent CLAUDE.md reached the model, and the repo’s own AGENTS.md was dropped. No message, no hint.

Check in one line from inside your repo:

ls ../CLAUDE.md ../../CLAUDE.md ../../../CLAUDE.md 2>/dev/null

ls ../CLAUDE.md ../../CLAUDE.md ../../../CLAUDE.md 2>/dev/null

Any path that prints is a file blocking your AGENTS.md.

Trap 3: putting the setting in the project file §

There is a switch to load both files. The natural place to put it is your repo’s .claude/settings.json, so the whole team gets it. Claude Code ignores it there (row 15).

It only works in your personal settings (~/.claude/settings.json), in a file passed with --settings (row 16), or in company-managed settings. So you cannot force it for teammates from inside the repo. Use the import in Fix 1 for that.

Trap 4: the first session after an upgrade §

If you had an older Claude Code and just upgraded, the very next session still skips AGENTS.md (row 19). The session after that reads it.

So if you upgrade, test once, see nothing, and conclude “it doesn’t work”, you drew the wrong conclusion. Start one more session before you judge it. Older builds skip it every time (row 18), so update first.

How do I make Claude Code read AGENTS.md? §

Pick the fix that matches your trap. Each one is a single line or a single setting.

Fix 1, the one that works everywhere: make line one of your CLAUDE.md an import (a line that pulls another file in, word for word).

@AGENTS.md

## Claude-only notes
Use plan mode for anything in src/billing/.

@AGENTS.md

## Claude-only notes
Use plan mode for anything in src/billing/.

This worked on every build I tried, and it survives Traps 1, 3 and 4. With the “both” setting on, Claude Code still loads AGENTS.md only once (row 14), so you never pay twice for the same text. If you use CLAUDE.local.md, put the same @AGENTS.md line at the top of that file too.

Fix 2, load both files always: type /config inside Claude Code, find Project instructions, and pick claude-md-and-agents-md. Or add this to ~/.claude/settings.json:

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

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

It is personal, so each teammate sets it once. Rows 12 and 13 show it loading both, even with CLAUDE.local.md present.

Fix 3, the stray parent file: move the old CLAUDE.md out of the parent folder, or rename it. If you really want it, add @AGENTS.md to a CLAUDE.md inside the repo instead.

Fix 4, the upgrade: run claude update, then open a fresh session twice. If /config shows no Project instructions option at all, your build predates AGENTS.md support or the built-in agents-md plugin is switched off in /plugin.

A symlink (a file that just points to another file) also works: ln -s AGENTS.md CLAUDE.md. It loaded once in row 6. Skip it on Windows, where symlinks need admin rights; the import does the same job.

What does Claude Code never read? §

Three names that other agents use are ignored completely: AGENTS.override.md, AGENTS.local.md, and anything inside a .agents/ folder.

This matters if you share a repo with Codex users. Codex reads AGENTS.override.md as a higher-priority rules file. Claude Code does not read it at all (row 8). Rules you put only there never reach Claude.

The same goes for skills (reusable instruction packs an agent loads on demand) stored in .agents/skills/. Claude Code will not find them there. Keep shared rules in plain AGENTS.md, and keep Claude skills in .claude/skills/.

The claude-md setting in /config switches AGENTS.md off on purpose (row 17). If a teammate sees nothing load, ask whether they picked it.

AGENTS.md vs CLAUDE.md: which should you keep? §

Keep AGENTS.md as the single source of truth and use a tiny CLAUDE.md only as a pointer, if you need one at all.

If your team uses only Claude Code, one CLAUDE.md is simplest. If anyone uses Codex, Cursor or another agent, AGENTS.md is the shared language, and the rules live there.

Whichever you pick, keep the file short. Every line costs tokens (the chunks of text the model reads) in every session. If yours has grown into an essay, the CLAUDE.md writeup shows how a 65-line file beats a long one. If you run Claude Code and Codex on one repo, Claude Code and Codex together covers the team setup, and Claude Code and Codex on the same model covers pointing both at one model. For the full picture of how the tool loop works, see the learn-claude-code teardown.

Official rules for every file are in the Claude Code memory docs.

Common questions about Claude Code and AGENTS.md §

Does Claude Code read AGENTS.md? §

Yes, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in your folder or any folder above it. Otherwise it reads the CLAUDE files and skips AGENTS.md.

Can Claude Code read both CLAUDE.md and AGENTS.md? §

Yes. Put @AGENTS.md on the first line of CLAUDE.md, or set Project instructions to claude-md-and-agents-md in /config. Both load once, with no duplicate.

Why did adding CLAUDE.local.md break my AGENTS.md? §

CLAUDE.local.md counts as a CLAUDE file, so Claude Code switches to CLAUDE files only. Add @AGENTS.md to it, or switch Project instructions to load both.

Does Claude Code read AGENTS.override.md? §

No. It ignores AGENTS.override.md, AGENTS.local.md and anything inside a .agents/ folder.

Is AGENTS.md weaker than CLAUDE.md in Claude Code? §

No. When it loads, it lands in the same must-follow instruction block as CLAUDE.md.

Two seconds with a fake server beats an afternoon of guessing what your agent read.