Imagine leaving a detailed note for your housemate on the fridge, except your housemate only ever checks the corkboard by the front door. The note is perfect. The handwriting is neat. The instructions are exactly what they needed. And it gets read by nobody, because you picked the wrong surface.
That is the situation a lot of teams are in right now with AGENTS.md and Claude Code. The claim circulating is that Claude Code will fall back to reading AGENTS.md when no CLAUDE.md exists. I went looking, and the reporting says otherwise. As of 2026, Claude Code reads CLAUDE.md. It does not read AGENTS.md natively. No fallback, no automatic sniffing of the directory for a reasonable alternative.
What the sources actually say
Multiple write-ups converge on the same point, and they are notably blunt about it. One rundown puts it as the part that bites teams who standardized on AGENTS.md over a weekend: as of June 2026, Claude Code does not read AGENTS.md natively. Another frames it as the fact half the internet gets wrong, and adds the mirror-image detail that trips people up in the other direction: Cursor does not read CLAUDE.md. Cursor reads .cursor/rules/*.mdc plus AGENTS.md.
So the file-reading map, based on what has been verified, looks like this:
- Claude Code reads CLAUDE.md.
- Cursor reads
.cursor/rules/*.mdcand AGENTS.md. - Neither reads the other’s primary file on its own.
The recommended bridge, per the Claude Code docs as cited in that reporting, is to create a CLAUDE.md that imports your AGENTS.md with @AGENTS.md. That is the whole trick. One file that exists purely to point at another file.
Why this matters more than it sounds
I build bots for a living, and the failure mode here is the sneakiest kind: everything appears to work. Your agent still responds. It still writes code. It still sounds confident. It just does it without any of the context you carefully wrote down about your naming conventions, your test runner, your “never touch the migrations folder” rule.
Compare that to a broken import or a failed build. Those scream at you. A context file that never got loaded whispers. You find out three days later when you notice the agent keeps reaching for a library you deliberately removed, and you assume the model is being stubborn, when really it never saw the memo.
This is why I have gotten paranoid about verifying that context files are actually in play rather than assuming it. If you are not sure whether your instructions are landing, put something falsifiable in the file. A specific phrase the agent should use, a formatting quirk, a made-up convention you can spot in the output. Ask the agent to restate its instructions. If the tell does not show up, the file is not loaded, and you have learned that in thirty seconds instead of three days.
The practical setup
If you are running more than one coding agent against the same repo, the pattern that follows from the verified facts is straightforward:
- Keep your real content in AGENTS.md. That is the file the wider set of tools reads, including Cursor.
- Add a thin CLAUDE.md that imports it with
@AGENTS.mdso Claude Code picks up the same material. - Keep Cursor-specific rules in
.cursor/rules/*.mdcwhere Cursor expects them.
One source of truth, small adapters around it. If that sounds like every other integration problem you have solved, that is because it is. The agent tooling space has not converged on a shared config format yet, so we are back to writing shims, the same way we did for build tools and linters before defaults settled.
Be skeptical of the convergence story
The reason the “Claude Code now falls back to AGENTS.md” claim spread so easily is that we want it to be true. A single universal instructions file is the obvious right answer, and every few weeks someone reports that the obvious right answer has arrived. Sometimes it has. Often what actually happened is that a tool documented a manual workaround, and the workaround got summarized into an automatic feature somewhere along the retelling chain.
The fix is boring and reliable: check the tool’s own docs, then check behavior in your own repo. A two-line CLAUDE.md costs you nothing and works regardless of which version of the story turns out to be right. Betting your project’s conventions on an undocumented fallback costs you silent drift across every session until you notice.
Write the note. Then make sure it is on the corkboard, not the fridge.
🕒 Published: