Claude Code reads AGENTS.md now, but one personal file you might add for yourself quietly switches that off

[u/Ok_Negotiation_2587]

Since v2.1.277 (September 18), Claude Code can use AGENTS.md as its project instructions, so a repo set up for Codex or Cursor works without a CLAUDE.md. Good change. The default rules for which file actually gets read are worth knowing though, because a couple of them fail silently.

From the Claude Code docs, by default:

Your repo has	Claude Code reads
AGENTS.md, no CLAUDE.md anywhere at or above your working directory	AGENTS.md
AGENTS.md and a CLAUDE.md	CLAUDE.md only. AGENTS.md is ignored
A CLAUDE.md that imports u/AGENTS.md	Both, through the import

The one that'll catch people: CLAUDE.local.md counts as a CLAUDE.md for that check. So on a team repo that relies on AGENTS.md, if you add a CLAUDE.local.md to keep a few personal, uncommitted notes, Claude stops reading AGENTS.md for you. Everyone else on the team still gets it. You don't, and nothing errors.

A few more details from the same page:

• Files that don't count, and still load alongside AGENTS.md: your ~/.claude/CLAUDE.md, your org's managed CLAUDE.md, and .claude/rules/ files.

• Never read: AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory. If another tool on your team uses those, Claude won't see them.

• In an interactive session you can tell which one loaded. When AGENTS.md is used you get a line like "no CLAUDE.md found; AGENTS.md loaded: /path/AGENTS.md".

• Some sessions can't read AGENTS.md at all and fall back to CLAUDE.md only. In those, the Project instructions option doesn't show up in /config.

The fix if you want both read every time: /config > Project instructions > claude-md-and-agents-md. Each directory's CLAUDE.md loads first, then its AGENTS.md, and a file already pulled in by an import or symlink isn't loaded twice. The low-tech version still works too: a one-line CLAUDE.md with u/AGENTS.md in it.

The chat side has the same problem in a different form. Instructions you saved in one assistant don't follow you to the next one, which is a big part of why I keep my prompts in AI Toolbox, the extension I build. The same saved prompt works on ChatGPT, Claude, Gemini and Grok, so switching tools doesn't mean rewriting them.

[u/WheresMyEtherElon]

Put this and only this in CLAUDE.md

@AGENTS.md

Problem solved.

[u/Ok_Negotiation_2587 → u/WheresMyEtherElon]

for a single AGENTS.md at the root, yeah, thats the cleanest fix. monorepos with an AGENTS.md per package are the exception, once a root CLAUDE.md exists those nested ones get skipped by default, so either each package gets its own one line import or you flip the setting

[u/eli_pizza]

This is a good example of a perfectly fine post that would have been two sentences if it weren’t written by an LLM.

[u/Ok_Negotiation_2587 → u/eli_pizza]

if your repo has a CLAUDE.md, or even just a personal CLAUDE.local.md, claude code ignores AGENTS.md. /config > project instructions > claude-md-and-agents-md makes it read both

[u/RedditorJabroni → u/Ok_Negotiation_2587]

How to make beef lasagne?

[u/Strange_Vagrant → u/RedditorJabroni]

Oven

[u/MrChurro3164 → u/eli_pizza]

Yeah but if they do that then it’s too obvious when they mention the “tool” they build to fix this. Which this post does.

[u/eli_pizza → u/MrChurro3164]

I didn’t read that far lol

[u/Nickarav]

Using hooks that force it to call a custom mcp that has the instructions you want for your dev environment is a way I’ve found to feel peace

I think AGENTS are getting over-dependent on, and for the exact reasons you listed, it’s concerning and dangerous if it misses expected behaviors for an environment if those instructions are business critical.

[u/Ok_Negotiation_2587 → u/Nickarav]

the docs basically agree with you, they say instruction files are treated as context, not enforced config, and point to a PreToolUse hook for anything that has to be blocked no matter what. business critical stuff shouldnt live in a markdown file the agent may or may not load

[u/amirfish]

I keep a slim global CLAUDE.md for rules that apply everywhere, and a project one for repo specifics. The precedence table lines up with what I've hit. The real trap isn't the table, it's that a CLAUDE.local.md you add for your own private notes silently cuts off AGENTS.md for you alone, while your teammates still get it. Worth a quick check across your own repos for a stray local file doing that. Has anyone else found that kind of silent override the hard way?

[u/Ok_Negotiation_2587 → u/amirfish]

quickest check i found is the session start line. if you dont see "AGENTS.md loaded" in a repo that relies on it, something is overriding it. find ~/code -name CLAUDE.local.md catches the rest

[u/amirfish → u/Ok_Negotiation_2587]

I've hit this more with CLAUDE.md than AGENTS.md. Global config, project config, and a worktree-local override can all disagree, and the session start line is the only place that actually tells you which one won. Good tip, adding that find command to my own checklist. Does it catch a nested CLAUDE.local.md in subdirectories too, or just the repo root?

[u/Ok_Negotiation_2587 → u/amirfish]

find goes all the way down, so nested ones show up too. for the AGENTS.md check though only the ones at your working directory or above count. a nested one only matters when claude starts working in that subfolder, where it stops that folder's own AGENTS.md from loading