The rumor that Claude Code falls back to AGENTS.md when no CLAUDE.md exists is wrong, and if you built your team’s workflow around it, your context file is being ignored right now.
I keep running into this one. Someone reads a thread, sees the words “fallback” and “AGENTS.md” in proximity, and concludes that Claude Code quietly grew support for the cross-tool standard. It didn’t. As of 2026, Claude Code reads CLAUDE.md. That’s the file. If AGENTS.md is the only context file in your repo, Claude Code is starting every session with no project instructions at all, and it will not tell you.
That silence is the actual problem. A missing config file usually announces itself with an error. This one doesn’t. The agent just behaves slightly worse than it should, ignores your conventions, picks the wrong test runner, reformats things you asked it not to touch. You blame the model. You write a longer prompt. You never check whether the file you wrote was read.
What each tool actually reads
Here is the part worth committing to memory, because half the posts on this subject get it backwards in both directions:
- Claude Code reads CLAUDE.md. It does not read AGENTS.md natively.
- Cursor reads
.cursor/rules/*.mdcand AGENTS.md. It does not read CLAUDE.md.
So the two most common agentic coding tools in a typical shop have zero overlap in what they pick up by default. There is no shared file. There is no graceful degradation. A repo with only CLAUDE.md gives Cursor nothing. A repo with only AGENTS.md gives Claude Code nothing. Teams that “standardized on AGENTS.md” over a weekend standardized themselves out of Claude Code context without noticing.
The fix is four characters long
The recommended pattern, straight from Claude Code’s own docs, is to keep AGENTS.md as your source of truth and create a CLAUDE.md that imports it:
- Write all your real instructions in AGENTS.md.
- Create a CLAUDE.md containing
@AGENTS.md. - Commit both.
That’s the whole bridge. One file with one import line. Claude Code loads CLAUDE.md, resolves the import, and you get your AGENTS.md content. Cursor keeps reading AGENTS.md directly. Nothing is duplicated, so nothing drifts.
I like this more than the alternative I see people reach for, which is copying the content into both files. Duplicated context files rot fast. Someone updates the build instructions in one, forgets the other, and now two agents have two different ideas about how your project works. That failure is worse than no context, because it’s confidently wrong in a way that’s hard to trace.
Why the confusion keeps spreading
Part of it is wishful thinking. AGENTS.md exists because a shared standard is obviously the right outcome, and people assume the tools have already converged because they should have. Part of it is that this behavior used to be something you inferred from issue trackers and scattered comments rather than read in documentation, so the folklore had room to grow. And part of it is that the failure mode is invisible, so nobody’s bad experience ever gets attributed to the real cause.
The version of this rumor going around now, that a missing CLAUDE.md triggers an AGENTS.md fallback, is particularly sticky because it sounds like exactly the kind of small, sensible thing a tool would ship. It isn’t what’s happening.
How to check your own repo in thirty seconds
Don’t take my word for it. Put something falsifiable in your context file, a line like “always start your first response with the word ACKNOWLEDGED.” Then open a fresh session and see if you get it. If you do, your file is being read. If you don’t, it isn’t, and now you know where to look.
I’d run this check any time you add a new agent to your setup, not just once. Tool defaults change, file discovery rules change, and monorepo path resolution has its own quirks. A ten-second canary line beats an assumption every time.
My take
This is a small operational detail that produces an outsized amount of wasted effort, and it’s entirely fixable today with a two-line file. The broader lesson for anyone assembling an AI toolkit is that config discovery is where multi-tool setups break first and loudest, except it isn’t loud at all. Verify what your agents read. Assume nothing about fallbacks until you’ve seen one work in your own repo.
If you only take one action from this piece, go check whether your project has a CLAUDE.md. If it doesn’t and you’ve got an AGENTS.md, add the import. Then get back to work.
🕒 Published: