The viral version of this story is wrong. The headline going around says Claude Code now falls back to AGENTS.md when no CLAUDE.md exists. It doesn’t. As of 2026, Claude Code reads CLAUDE.md. That’s it. If your repo has a beautifully maintained AGENTS.md and no CLAUDE.md, Claude Code walks past it like a stranger at a bus stop.
I keep seeing teams discover this the hard way, usually about three weeks after a migration nobody documented. They consolidated everything into AGENTS.md because a blog post told them it was the universal standard, deleted the “redundant” CLAUDE.md, and then spent a sprint wondering why the agent kept ignoring their build commands and reintroducing patterns they’d explicitly banned. The instructions were right there in the repo. The tool was never looking.
What each tool actually reads
The mechanics are simpler than the discourse suggests:
- 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.
Two tools, two conventions, zero overlap. Anyone telling you there’s a single file that covers your whole toolchain is selling a tidier reality than the one you work in.
The documented workaround is unglamorous and it works: create a CLAUDE.md that imports your AGENTS.md with @AGENTS.md. One file, one line, and Claude Code picks up whatever you’ve written for everything else. Per the Claude Code docs, that’s the recommended pattern. It’s a shim. Shims are fine. Shims you didn’t know you needed are the problem.
Why this particular rumor spread so fast
Because people want it to be true. A shared context file across agents is the obvious right answer, the thing every developer assumes already exists because it should. So when someone posts that the fallback shipped, it slots straight into the gap where the expectation already lives. Nobody checks. The post gets 4,000 likes and a week later half a dozen teams have a silently broken config.
There’s a second reason, and it’s less flattering to all of us. Agent context files are hard to verify. When you delete a config in a normal system, something breaks loudly. When you delete the file your coding agent reads, nothing breaks. The agent just gets a little worse. It forgets your test runner. It writes the class-based component in your hooks-only codebase. It’s subtly, deniably mediocre, and you attribute it to the model having an off day.
That’s the actual cost here. Not a crash you can trace, but a slow drift in output quality with no error message attached to it. Missing context looks exactly like a model being dumb.
What I’d do instead
Treat agent context files as configuration, not documentation. Configuration gets verified. Documentation gets written once and rots.
Practically, for a mixed Claude Code and Cursor team:
- Keep AGENTS.md as the single source of truth for project conventions, commands, and constraints.
- Keep a thin CLAUDE.md whose only job is importing it. If someone deletes it during cleanup, you’ll notice, because it will be the only file in the repo with a comment explaining why it exists.
- Keep
.cursor/rules/*.mdcfor the Cursor-specific rules that genuinely need to be Cursor-specific, and resist the urge to duplicate your whole convention set there. - Verify rather than assume. Ask the agent to repeat a distinctive rule from your context file at the start of a session. If it can’t, it isn’t reading what you think it’s reading.
That last one takes ten seconds and would have saved every team I’ve watched trip over this.
The part that actually annoys me
None of this is a technical problem. Reading a fallback file when the primary is absent is not a hard feature. The reason it doesn’t exist is that competing vendors have no strong reason to converge on each other’s conventions, and the cost of divergence lands on us instead of them. We’re the ones writing the same instructions in three formats and maintaining a one-line import file to bridge a gap that shouldn’t be there.
So pin your assumptions to what the docs say, not what the timeline says. Right now the docs say Claude Code reads CLAUDE.md, Cursor reads AGENTS.md and its own rules directory, and the bridge between them is a manual import you have to write yourself. If that changes, it’ll change in the changelog before it changes on social media.
Until then, go check whether your repo has a CLAUDE.md. I’ll wait.
🕒 Published: