AGENTS.md vs CLAUDE.md: which file your agent actually reads

Last updated: 2026-09-04

You wrote the rules down. The agent ignored them anyway.

So you go looking, and the internet tells you there are two files. CLAUDE.md is Claude Code's native one. AGENTS.md is the cross-tool standard that Codex and Cursor read. Pick one, or keep both and import one from the other. Every guide says roughly that, and it is roughly true.

It is also not the thing that was breaking.

I have 13 repos with both files in them. Twelve load AGENTS.md every session. One does not, and I did not notice for a month. The difference is not which file I chose. The difference is one line, and it is not the line I first went looking for.

The immediate fix: check line one

Open your CLAUDE.md and look at the first line.

@AGENTS.md

That is an import. Claude Code resolves it and pulls the file's contents into context before your first message. It happens every session, whether or not the agent decides anything.

Now here is what I had in a different repo:

Read `AGENTS.md` alongside this file: it carries the branch/commit/merge
workflow and the short list of load-bearing invariants.

That is not an import. That is a sentence asking the agent to go read a file. It costs a tool call, it happens only if the agent decides to, and it happens after it has already started reasoning about your request.

Same author. Same idea. Two mechanisms, and only one of them is deterministic.

Across 25 repos that have a CLAUDE.md, 13 also have an AGENTS.md:

Wiring	Repos	Loaded every session
@AGENTS.md import	12	Yes
Prose: "Read AGENTS.md alongside this file"	1	Only if it chooses to

The one is 6,479 bytes of branch rules, commit conventions and load-bearing invariants, sitting in a file the agent was politely asked to read. That is the bug. Not the file format.

A trap I walked into while checking this. My first pass tested whether @AGENTS.md was on line 1, and it reported two broken repos. Only one was. The second repo has its import on line 5, under a heading, and works perfectly well. The import is not position-sensitive. If you audit this across repos, grep the whole file for @AGENTS.md; do not check the first line and call it a test. I got that wrong in the first version of this post.

Fix it in one line. Put @AGENTS.md as the first line of CLAUDE.md. Delete the prose that asks the agent to read it, because the prose is now costing you tokens to say something the import already did.

Why this keeps happening

The two files answer different questions, and the guides frame it as a choice when it is actually a split.

AGENTS.md is the open format, used across Codex, Cursor, Aider and others. It is where anything tool-agnostic belongs, and in practice that turns out to be more than a list of conventions. Mine carries the development process itself: the pipeline a change moves through, the tier rules that scale that process to how risky the change is, and the gates that stop it when something is unverified. Branch and commit conventions are in there too, but they are the smallest part of it.

It does not reinvent any of that. It names the compound-engineering plugin as the spine and says which of its skills fires at which step, which is the part a plugin cannot do for you: the plugin ships capabilities, and the file decides when they run and what the bar is for this repo.

The detail I would keep if I rewrote it from scratch is the fallback. Every step in that pipeline also has a manual equivalent written next to it, so the process still runs on a machine where the plugin is not installed. The practice is the durable thing; the tooling is an implementation of it. A process doc that only works when a specific plugin is present is a configuration file wearing a process doc's clothes.

The test for what belongs is whether another agent, on another tool, could read the file and work correctly without you. Process passes that test. Anything Claude-specific does not.

Two things are being described here and only one of them generalizes. The wiring does: one import line, tool-agnostic process in AGENTS.md, tool-specific facts in CLAUDE.md. That applies to any repo. The contents of mine do not. My tier rules are calibrated to which surfaces in my repos can do real damage when they go wrong, and yours are calibrated to yours, which are different surfaces. Copying my file would give you my judgement about risks you do not have.

So take the mechanism and write your own process into it. The file is worth having because it is yours, not because it is correct in the abstract.

CLAUDE.md is Claude Code's own file. It is where Claude-specific things belong: which MCP servers matter, which external services have traps, which of your commands are dangerous.

Split that way, neither file duplicates the other and the question "which one do I use" stops being a question. You use both, and one line joins them.

What made this hard to see is that both wirings look identical at a glance. A repo with the prose version and a repo with the import version both have an AGENTS.md, both mention it in CLAUDE.md, and both look organized. Nothing fails loudly. The agent just occasionally does not know a rule you are certain you wrote down.

It survives a careless audit too, as above: check the wrong line and you get the wrong answer in both directions, missing a real break and inventing a fake one.

The part that is actually the problem

I got this wrong in my own repos, while writing about how to organize agent instructions. That is worth sitting with, because the failure is not carelessness. It is that nothing checked.

There was no gate. No test. Nothing that reads a repo and says "this file is never loaded." The rule existed in my head, it existed correctly in twelve repos, and it silently did not exist in the thirteenth. The only reason I found it was that I went looking for something else. Then my first attempt to check it mechanically was itself wrong, which is the same disease one level up.

This is the general shape of agent configuration right now: the rules live in files, the files are loaded by convention, and the convention is enforced by remembering. That works until you have three repos. Then it does not.

The fix is not a better file. It is making the convention mechanical: something that loads deterministically rather than on request, and something that fails visibly when it does not. @AGENTS.md is the small version of that. Writing the operating rules into a file the agent reads first, every time, and keeping the tool-specific things out of it, is the larger one.

I wrote up how that file is structured, and what belongs in it, in compound engineering for Claude Code: the AGENTS.md setup. The short version is that AGENTS.md is a sibling to CLAUDE.md that loads ahead of it, and that splitting process out of CLAUDE.md is a read-order decision rather than a tidiness one.

If you are choosing which process plugin to put behind it, I installed both of the main ones in the same repo and measured what each costs in compound engineering vs Superpowers - including the six skills that collide when you run them together, and the one line in AGENTS.md that settles which wins.

What I have not tested yet

Stated plainly, because the rest of this post is measured and this part is not:

• Whether Claude Code reads a root AGENTS.md natively, with no import line, in current versions. It was not mentioned in any release note I captured between 2.1.257 and 2.1.260. If it does, the prose-versus-import distinction above still holds but the stakes drop.
• The exact token cost of each file. I have byte counts, not tokens, and I am not going to convert one to the other and call it a measurement.

Frequently asked questions

Does Claude Code support AGENTS.md files?

Yes, by import. Putting @AGENTS.md on the first line of CLAUDE.md resolves the file and loads its contents into context at session start. Whether current versions also read a root AGENTS.md with no import line is something I have not verified.

Does Claude auto-read AGENTS.md?

Do not rely on it. An @AGENTS.md import is deterministic. A sentence in CLAUDE.md telling the agent to read AGENTS.md is a request the agent may or may not act on, and it acts on it after it has already begun reasoning. In one of my thirteen repos that meant 6,479 bytes of rules were effectively optional.

Does Copilot read AGENTS.md?

AGENTS.md is an open format adopted across several coding tools, which is the reason to keep tool-agnostic rules there rather than in a vendor-specific file. Support varies by tool and by version, so verify it in yours rather than assuming.

Should it be AGENTS.md or agents.md?

Uppercase, AGENTS.md, matching the published format and matching CLAUDE.md and README.md. On a case-insensitive filesystem the wrong case will appear to work locally and then fail in CI.

Do I need both files?

If you use more than one coding agent, yes. Tool-agnostic rules go in AGENTS.md so every tool gets them; Claude-specific rules go in CLAUDE.md. One import line joins them. If you only ever use Claude Code, one file is enough, and it should be CLAUDE.md.

Which file wins if they disagree?

Do not let them. Split by scope rather than by priority: process and invariants in AGENTS.md, Claude-specific facts and traps in CLAUDE.md. Overlap between them is the thing that produces a conflict, and the conflict is not resolved by any documented rule.