AGENTS.md vs CLAUDE.md: I Ran Both for Three Weeks (2026)

Quick answer (July 2026): AGENTS.md and CLAUDE.md are not competitors, and you almost never need both as separate files. AGENTS.md is the open, cross-tool standard read by Codex, Cursor, Copilot, Gemini CLI and about twenty other agents. CLAUDE.md is Claude Code's own file, and Claude Code does not read AGENTS.md. The clean setup is one source of truth: keep AGENTS.md, then add a one-line CLAUDE.md that imports it with @AGENTS.md. That is what I run now, and it ended a week of the two files quietly drifting apart.

I ran two agent-instruction files in the same repo for about three weeks before I admitted it was a mistake.

The repo is a Next.js side project I build with a rotating cast of coding agents. Codex for long chores, Claude Code for the tight edit loop, Cursor when I want to stay in the editor. Each one wanted a config file, so I gave each one a config file. AGENTS.md for the tools that read it, CLAUDE.md for Claude Code. Two files, same intent, and within a week they said slightly different things. The AGENTS.md said "money is integer cents." The CLAUDE.md still said "use the currency helper," which I had deleted. Claude Code cheerfully followed the stale rule.

That is the real story of agents.md vs claude.md in 2026. It is not a format war. It is a question of how many copies of the truth you are willing to maintain, and the honest answer is one.

What each file actually is

These two files get talked about as rivals, but they sit at different layers.

I keep the tools straight with their own marks: Codex, Cursor, Copilot and Gemini CLI all read AGENTS.md, while Claude Code reads CLAUDE.md.

AGENTS.md is an open format. The spec site describes it as "a simple, open format for guiding coding agents," and as of July 2026 it lists more than twenty tools that read it, including Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Jules, Devin, Zed, Amp, Warp and Windsurf (agents.md, 2026). One file, most of the ecosystem. That is the whole appeal.

CLAUDE.md is Claude Code's native instruction file. It is older than the AGENTS.md convention and it does more Claude-specific things: @path imports, a .claude/rules/ directory with path-scoped rules, managed org policy files. It is not trying to be portable. It is trying to be the best file for one tool.

The fact most guides get wrong

Here is the line that cost me a week: Claude Code does not read AGENTS.md.

I assumed it did. A lot of posts imply it does. The official Claude Code docs are blunt about it: "Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them" (Claude Code memory docs, 2026).

So the two-file setup I had was not two views of one truth. It was two separate truths that I was hand-syncing and losing. If you have ever wondered why Claude Code ignored something you clearly wrote down, check whether you wrote it in AGENTS.md and expected Claude to find it. It did not.

The setup I actually run now

One source of truth, one bridge. My whole CLAUDE.md is this:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

The @AGENTS.md line pulls the shared file into Claude Code's context at session start, and the section below it holds the two or three Claude-specific notes that do not belong in the portable file. Everything else lives in AGENTS.md, where Codex, Cursor and Copilot already read it. When I change a convention, I change it once.

A symlink works too if you have nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md

I avoid the symlink on my Windows machine, where it needs Administrator rights or Developer Mode, and the import line is simpler anyway. One nice side effect: running /init in a repo that already has an AGENTS.md reads it and folds the relevant parts into the generated CLAUDE.md, so you are not starting from a blank file.

If you keep the two files genuinely separate, the way I first did, you are signing up to keep them in sync by hand. That is the one setup I would tell you to avoid.

Do these files even help? The honest part

There is a real, unresolved debate about whether agent-instruction files improve results at all, and I am not going to pretend it is settled. A well-argued 2026 thread evaluated AGENTS.md across coding tasks and came away skeptical that a longer context file reliably raises success rates (Hacker News, 2026). My own experience lines up with the smaller-is-better camp: the file competes with your actual code for the same context window, and past a point it starts hurting more than it helps. I wrote a whole field log on cutting my AGENTS.md from 400 lines to 40, and consolidating to one file made that trim easier, because there was only one file left to trim.

So my honest position: the file helps when it is short and holds only what the agent cannot infer from the code, and it stops helping the moment it becomes a second README. That is true whether it is called AGENTS.md or CLAUDE.md. If anything, the auto-memory that Claude Code now writes for itself is doing some of the work these files used to, which I got into in what I keep in Claude Code memory.

What I would tell past me

If you use more than one coding agent, do not maintain two instruction files. Write one AGENTS.md, make CLAUDE.md a one-line @AGENTS.md import plus any Claude-only notes, and keep the whole thing short. The agents.md vs claude.md framing is a trap. They are not fighting for the same job. One is the shared file, the other is the Claude adapter, and your job is to make sure there is exactly one place where the truth lives.