Remember the .eslintrc years? Every project carried four config files that all claimed authority over the same rules, and nobody could tell you which one actually won until something broke in CI. We solved that eventually, mostly by attrition. Agent memory files are currently at the exact same stage of the cycle, and the rumor going around — that Claude Code now falls back to AGENTS.md when no CLAUDE.md exists — is a good example of how fast wishful thinking outruns behavior.
It doesn’t. As of 2026, Claude Code reads CLAUDE.md and only CLAUDE.md. There is no graceful fallback. If your repository contains a beautifully maintained AGENTS.md and nothing else, Claude Code starts with an empty memory and no complaint about it.
The silent failure is the interesting part
I care less about which filename wins than about the failure mode, because the failure mode tells you something real about how these systems are built.
When a compiler can’t find a header, you get an error. When a test runner can’t find a config, you get an error. When an agent can’t find its instruction file, you get a perfectly fluent, perfectly confident session that simply doesn’t know your repo uses snake_case, or that the migrations directory is generated, or that utils/legacy is radioactive. The output looks identical to a correctly configured session. That asymmetry between input failure and output appearance is the defining ergonomic problem of agent tooling right now.
Context loading gets treated like configuration when it functionally behaves like a dependency. A missing dependency halts the build. A missing memory file degrades quality in ways that only show up in code review, three commits later, when someone asks why the agent reinvented a helper that already existed.
What each tool actually reads
The current split, per tool documentation and the reporting around it:
- Claude Code reads
CLAUDE.md. NotAGENTS.md, not natively. - Cursor reads
.cursor/rules/*.mdcplusAGENTS.md. NotCLAUDE.md. - Most other major tools have settled on
AGENTS.md.
So a team running both Claude Code and Cursor has two tools with zero overlap in what they read. Neither one warns you. Both produce plausible work. The divergence in behavior between your teammates becomes a mystery nobody has instrumentation for.
The bridge, and why it’s more than a workaround
The documented pattern is to create a CLAUDE.md that imports the other file with @AGENTS.md. Two lines of indirection and both tools read the same source of truth.
It reads like a hack. I’d argue it’s the more honest design. An import directive makes the resolution explicit: this agent loads this file, because a human wrote that instruction down. Compare that to an implicit fallback chain, where the agent searches a list of candidate filenames in priority order and silently picks one. Implicit fallbacks are how you end up debugging which of four .eslintrc files won. They optimize for the first five minutes of setup and tax you forever after.
Explicit indirection also gives you somewhere to put tool-specific content. CLAUDE.md can import the shared instructions and then add the parts that only matter to Claude Code, which is closer to how real teams actually work than pretending one file serves every agent identically.
What this says about agent architecture
The filename disagreement is a surface symptom. Underneath it is a harder question the space hasn’t answered: what is an agent’s memory, architecturally?
Right now it’s a file that gets concatenated into a prompt. That’s it. There is no schema, no validation, no way to assert that a rule was loaded, no signal back to the developer about which instructions actually made it into context and which got truncated or ignored. We have a convention where we need an interface.
A real interface would let an agent report its loaded context. It would fail loudly on a missing or malformed memory file. It would let a rule declare scope — this applies to Python files, this applies to the whole repo — in a way every tool could parse. Cursor’s .mdc format gestures at some of this with structured rule files, which is probably why it kept its own directory alongside AGENTS.md rather than collapsing everything into one document.
Until that interface exists, the practical advice is unglamorous. Check what your tools read instead of trusting a blog post, including this one. Keep one source of truth and bridge to it explicitly. And treat a missing memory file as a build-breaking condition in your own head, because your tooling won’t do it for you.
The convention will converge eventually. Conventions always do. The part I’d like to see converge faster is the part where the agent tells you what it knows before it starts writing code on your behalf.
🕒 Published: