One writer at bestagent.dev put it about as bluntly as you can: the teams who “standardized on AGENTS.md” over a weekend are the ones getting bitten, because as of June 2026, Claude Code does not read AGENTS.md natively. Another post, over at TECHSY, called it the fact half the internet gets wrong.
My reaction? Relief, mostly. Because I have watched this particular confusion spread through group chats and team wikis for months, and it is nice to see someone say the plain version out loud.
So let’s start by correcting the rumor that brought you here. You may have seen the claim that Claude Code now falls back to AGENTS.md when there is no CLAUDE.md in your project. That is not what the sources say. Claude Code reads CLAUDE.md. That’s it.
What these files even are
If you are not a developer, here is the short version. AI coding assistants work inside a project folder, and they do better when someone leaves them a note explaining how things work around here. That note is a plain text file sitting in the project. It is less “code” and more “onboarding doc for a new hire who happens to be a machine.”
The trouble is that different tools look for the note under different filenames. Claude Code looks for CLAUDE.md. Cursor looks for files in a folder called .cursor/rules/ ending in .mdc, plus AGENTS.md. Cursor does not read CLAUDE.md. Claude Code does not read AGENTS.md.
Two tools, two vocabularies, zero mind-reading.
Why this causes real problems
Imagine leaving detailed instructions for a house sitter on the kitchen counter, then discovering they only ever check the fridge door. The instructions were fine. The pickup location was wrong. Nothing you wrote was read, and nothing warned you.
That’s the failure mode here, and it is quiet. Your assistant doesn’t announce “I found no guidance and am proceeding on vibes.” It just proceeds. You get output that ignores your conventions, your preferences, the thing you specifically asked it never to do again. You assume the model is being difficult. In fact it never saw the memo.
This is why the weekend-standardization story stings. A team decides to consolidate on one filename, feels organized, deletes the duplicate, and silently turns off guidance for one of their tools.
The fix is one small bridge file
Per Claude Code’s own docs, the recommended pattern is to create a CLAUDE.md that imports the other file using @AGENTS.md. In human terms: leave a note on the fridge door that says “read the one on the counter.”
That gives you one source of truth and two working readers:
AGENTS.mdholds your actual instructions, the content you care about maintaining.CLAUDE.mdis a pointer file that imports it, so Claude Code reaches the same content.- Cursor keeps reading
AGENTS.mdalong with its own.cursor/rules/files.
No duplicated text drifting apart over time. No tool left guessing.
Why the rumor spread anyway
I have a theory, and I’ll flag it as a theory rather than a documented fact. The fallback behavior people describe is exactly what you’d expect a well-designed tool to do. If there is no CLAUDE.md but there is an AGENTS.md right there, of course it should look. That feels so obviously correct that people remember hearing it confirmed.
Add to that the pace of these releases. The buildthisnow.com guide on this topic was published in April 2026 and updated again in June. When documentation gets revised that often, secondhand summaries go stale fast, and the stale version keeps circulating in screenshots.
What to take away from this
The useful lesson is not about filenames at all. It is that AI tools fail silently more often than they fail loudly. A missing instruction file produces mediocre output, not an error message, and mediocre output is easy to blame on the model.
So when an assistant seems to be ignoring you, check whether it can actually hear you. Ask which file your tool reads. Ask whether that file exists. Ask whether someone tidied it away last week in the name of consistency.
That is a boring question, and it solves a surprising amount of frustration. The most common reason an AI agent behaves like it has no context is that it genuinely has none.
🕒 Published: