AGENTS.md vs CLAUDE.md: Which File Each Coding Tool Reads

A repo has a CLAUDE.md that someone spent an afternoon getting right. Then a teammate opens the same repo in Cursor, or a Copilot coding agent picks up an issue, and an AGENTS.md appears next to it saying roughly the same things in slightly different words. Now there are two files, one project, and no obvious rule about which one anything actually reads.

AGENTS.md is read by four of the six tools here with no configuration. CLAUDE.md is read by three of them, which is the part most guides get wrong: Claude Code, GitHub Copilot in VS Code and its coding agent, and Cursor through its CLI. Only OpenAI Codex reads a single format by default, AGENTS.md, and it lets you configure fallback filenames.

That second number is what changes the decision. If CLAUDE.md were a Claude Code file and nothing else, the answer would be simple arithmetic about how many tools you run. Three of the six read it, which is why the table below has two columns worth reading rather than one.

A note on method, because it matters for how much weight to put on any single cell. I read each vendor’s own documentation page on 17 August 2026 and recorded what it says. Nothing here was tested by running it: no account was opened, no tool was installed, and no behavior is reported that the vendor does not publish. Where a page says nothing about a format, this article says the page says nothing, which is a different and weaker claim than the tool refusing the file.

Which file does each coding tool actually read?

AGENTS.md has the widest reach here: four of the six tools read it with no configuration. CLAUDE.md reaches three, a number most guides miss, and OpenAI Codex is the only tool in the table confined to one format. Every cell below comes from that vendor’s own documentation, dated 17 August 2026.

A cell marked “not documented” means the vendor’s own page named in that row said nothing about that format when I read it on 17 August 2026. None of those cells is a vendor saying no.

The CLAUDE.md column is the one that surprises people, and VS Code states it in a sentence: “VS Code automatically detects a CLAUDE.md file and applies it as always-on instructions, similar to AGENTS.md.” The same page lists four places it looks: the workspace root, the .claude folder, ~/.claude/CLAUDE.md, and a local CLAUDE.local.md variant. The behavior sits behind chat.useClaudeMdFile, and the equivalent AGENTS.md switch is chat.useAgentsMdFile, with nested AGENTS.md files behind an experimental chat.useNestedAgentsMdFiles. VS Code also treats the .claude/rules folder as a location for instructions files, at the workspace level and again under the user profile.

Six tools across five formats give you a mesh rather than a one-to-one mapping. Copilot reads all five columns. Cursor reads three. Claude Code and Cline read two each. Gemini CLI reads one by default and a second once you name it in a setting. Only Codex reads a single format by default (fallback filenames are configurable), and only AGENTS.md is read by four different tools with nothing configured. So the question “which file should I have” cannot be answered from the filename alone, which is what most guides try to do.

On the one platform that reads all five of these formats, the cross-tool file everyone shares is the one it ranks last.

What each of these files is, in one line

AGENTS.md is the cross-tool format. Its own site describes it as a simple, open format for guiding coding agents, and as of 17 August 2026 that site claims 60k+ open-source projects. It is plain markdown with no required sections and no frontmatter, which is exactly why so many tools can agree on it. What actually goes inside one, and whether the file earns the context it costs, is a separate subject from this page.

CLAUDE.md is Claude Code’s own instruction file, and it now has readers beyond Claude Code. Anthropic’s memory documentation gives it four scopes: a managed policy file deployed by IT, a personal ~/.claude/CLAUDE.md, a project ./CLAUDE.md or ./.claude/CLAUDE.md, and a gitignored ./CLAUDE.local.md. Writing a good one, and the guardrail sections most files skip, is its own body of practice and not what this page covers.

.cursor/rules holds Cursor’s project rules as .mdc files. Each carries description, globs and alwaysApply frontmatter, and those three fields select between four application types. That frontmatter is the whole point of the directory, and how Cursor rules are scoped is a topic in its own right.

.clinerules/ is Cline’s equivalent, and it is the most permissive reader in the set. Cline’s rules documentation says it combines every .md and .txt file in that folder, surfaces every detected rule type in a panel with individual toggles, and reaches outside the repo as well: “Cline also reads cross-tool global AGENTS instructions from ~/.agents/AGENTS.md.” What belongs in a .clinerules folder, and how the toggles behave in practice, is Cline-specific and not settled here.

.claude/rules/ is Claude Code’s directory format. Rules without a paths frontmatter field load at launch at the same priority as .claude/CLAUDE.md; rules with one load only when Claude touches a matching file.

.github/copilot-instructions.md is Copilot’s repository-wide file, and .instructions.md files under .github/instructions are its path-scoped layer, selected by an applyTo glob in the header. GEMINI.md is Gemini CLI’s default context file, and the filename is configurable rather than fixed.

README.md stays off this list on purpose. It is written for people who can ask a follow-up question, and none of these tools treat it as standing instructions.

When a repo has more than one of them, which one wins?

Four vendors publish an answer, and the four answers are different enough that no single mental model covers them. The differences are not cosmetic.

Claude Code does not pick a winner at all. Anthropic’s memory page says every discovered CLAUDE.md and CLAUDE.local.md is concatenated into context rather than overriding, stacked root-first, so whatever sits nearest your launch directory lands last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md. A contradiction between two files is not resolved by precedence, it stays in context as a contradiction, and the same page warns that Claude may then pick one arbitrarily.

Codex concatenates in the same direction but does let later files win. It walks from the project root down to your working directory, takes at most one file per directory, and joins them with blank lines, so a file nearer your working directory overrides earlier guidance because it appears later in the combined prompt. Its global ~/.codex/AGENTS.md sits ahead of everything in the repo.

GitHub Copilot publishes a real ranking, and it contains the surprise. Its response-customization page states the top of the order plainly: “Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last.” Inside repository instructions, the order runs path-specific .instructions.md files first, then repository-wide .github/copilot-instructions.md, then agent instructions, which is the category holding AGENTS.md, CLAUDE.md and GEMINI.md. The same page adds that all relevant instruction sets are still provided to Copilot, so this is a ranking, not a filter.

The AGENTS.md format publishes its own rule, which is proximity: “Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions.” Cursor implements that shape too, combining a nested AGENTS.md with its parents and letting the more specific instruction take precedence.

Line those four up and the awkward result is hard to miss. On GitHub Copilot, the platform that reads more instruction formats than any other tool in this set, the cross-tool standard is ranked below both of Copilot’s own file types. A rule you put in AGENTS.md because you wanted every tool to see it is the rule Copilot weighs least.

Two things you have probably read that the vendor docs contradict

Two pages that rank for this question give confident one-line answers, and they contradict each other as well as the vendors.

Both URLs are printed without a link on purpose. These are the pages whose claims this section is correcting, and sending a reader to a claim I have just flagged is not a service to them. Buildbetter has a second reason to stay unlinked: its own product is a column in its comparison table.

The two errors point in opposite directions, which is what makes them useful. Buildthisnow understates CLAUDE.md by treating it as a single-vendor file, so a reader concludes that a CLAUDE.md is dead weight to everything except Claude Code and stops maintaining it. Buildbetter overstates AGENTS.md by giving Claude Code a capability its vendor explicitly declines, so a reader concludes one AGENTS.md covers the whole repo and leaves Claude Code reading nothing at all. The second mistake is the expensive one, because it fails silently.

Neither page cites a vendor documentation link, which is the shared root cause. Buildthisnow names Anthropic and a Claude Code version number without linking either. Buildbetter names OpenAI, Cursor, Anthropic and Sourcegraph and links none of them.

One file or two? Pick by the tools that touch the repo

Which tools open the repo decides this, rather than which format is better designed. There are three shapes worth planning for.

1. 01 Only Claude Code touches the repo: keep one CLAUDE.md and stop there. A second file earns nothing, and every tool that would read it is hypothetical.
2. 02 More than one tool touches the repo, and you have nothing Claude-specific to say: keep one AGENTS.md as the source of truth and give Claude Code a route to it. Four of the six tools here read AGENTS.md without any configuration.
3. 03 More than one tool touches the repo, and you do have something Claude-specific to say: keep AGENTS.md for the shared rules and a short CLAUDE.md that pulls it in and adds the Claude-only lines underneath.

Case three is the one people resist, because two files feels like duplication. Four Claude-only lines sitting under an import duplicate nothing, since none of them repeat what the shared file already says. The failure mode to avoid is two full files that both describe the build, because the moment the build command changes, one of them is wrong and nothing tells you which tool read the wrong one.

The mechanics of case two and case three, the exact symlink command and the exact import line, are well covered elsewhere and deliberately not repeated here. What that decision needs from this page is the constraint that selects it, not the syntax.

One caveat on case one that is easy to get wrong. “Only Claude Code touches the repo” has to include the tools you did not install yourself. If anyone on the team opens the project in VS Code with Copilot on, or a Copilot coding agent works an issue, the repo is already a multi-tool repo whether or not a second file exists.

What travels between tools, and what does not

Plain instruction text travels fine. A line saying which command runs the tests, or which directory holds the migrations, means the same thing to every tool in the table. That is the whole reason a shared file works at all.

Path scoping does not travel in the same shape, and this is where a single root file runs out. Three tools solve the same problem three ways. Cursor puts a globs field in .mdc frontmatter. Claude Code puts a paths list in .claude/rules/ frontmatter. Copilot puts an applyTo glob in an .instructions.md header. All three express “apply this only to files matching a pattern,” and a root-level AGENTS.md or CLAUDE.md cannot express it at all, in any of the three syntaxes.

There is one genuine bridge, and it runs in a direction most people would not guess. VS Code reads the .claude/rules folder as an instructions location, and its documentation notes that for those files it uses a paths property instead of applyTo, following the Claude rules format, with the property defaulting to all files when omitted. One tool reading another tool’s scoped-rule format, on that format’s own terms, is rarer than the shared filename story suggests.

The trap worth naming, because it fails silently, is the extension in .cursor/rules. Cursor’s documentation says a plain .md file placed there is ignored by the rules system, because it has no frontmatter to specify description, globs and alwaysApply. A file that looks right, sits in the right directory, and does nothing is worse than a missing file, since nothing prompts you to look for it.

What belongs in the shared file, and what stays with one tool

Shared file: the things that are true about the repository regardless of who is reading. Build and test commands as exact strings. The directories that break in non-obvious ways. Conventions a formatter cannot enforce. Domain words that mean something specific in this codebase. None of that changes because a different agent read it.

Tool-specific file: anything that names one product’s surface. Permission and approval settings, hooks, path-scoped rules in that tool’s own frontmatter dialect, and instructions about that tool’s modes. Those lines are noise in every other tool’s context window, and in Copilot’s case they land in the category it ranks lowest anyway.

Keep the split honest and there is nothing to reconcile. Let the same build command exist in both files and you have signed up to update it twice, forever, with no warning when you miss one. The person who eventually notices is the one whose agent confidently ran a script that stopped existing three weeks ago.

Length is the other half of this. Whatever ends up in the shared file is paid for in context on every turn of every session, so what running out of a window costs you is worth understanding before deciding how much goes in. The pruning rule that survives contact with a real repo is narrow: keep a line if an agent has already got it wrong at least once.

The unresolved part, and it is genuinely unresolved as of this reading, is what happens when the tools disagree at the same level. Claude Code says two contradictory instructions may cause it to pick one arbitrarily. Copilot says all relevant instruction sets are provided regardless of rank. Neither vendor tells you what the model does with a shared file and a tool-specific file that quietly say opposite things, and no amount of file layout fixes that.

Common questions about AGENTS.md and CLAUDE.md

Can Claude Code read an AGENTS.md file?

No, not on its own. Anthropic’s memory documentation names CLAUDE.md as the file Claude Code loads and rules AGENTS.md out, then offers two supported ways to point both tools at a single source instead of a second copy.

There is one narrow exception worth knowing. With CLAUDE_CODE_NEW_INIT=1 set, /init reads AGENTS.md as one of the sources it draws on while generating a CLAUDE.md, alongside .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules. That is a one-time read at generation, not standing support, and the same page documents /import as a separate one-time copy that requires Claude Code v2.1.213 or later.

Can Cursor read AGENTS.md?

Yes, and more thoroughly than most tools in this table. Cursor’s rules documentation says AGENTS.md files can sit in any subdirectory and apply automatically when you work with files in that directory or its children, with nested files combining with their parents and the more specific instruction winning.

Cursor’s CLI goes further and reads a root CLAUDE.md as well, treating it as one more rule source next to whatever sits in .cursor/rules. Note the boundary: that CLAUDE.md support is documented for the CLI, and the editor’s rules page does not carry it. AGENTS.md vs Cursor rules, in one line: AGENTS.md is the portable plain-markdown option, and .cursor/rules is the one that can carry globs and rule types.

Does GitHub Copilot read CLAUDE.md?

Yes, in both places. VS Code detects a CLAUDE.md and applies it as always-on instructions behind the chat.useClaudeMdFile setting, and GitHub’s August 2025 changelog lists CLAUDE.md among the files the Copilot coding agent supports, next to AGENTS.md, GEMINI.md, .github/copilot-instructions.md and .instructions.md files.

This is the single cell that breaks the tidy story about CLAUDE.md being a one-vendor file. It also comes with a ranking: inside repository instructions, Copilot places the agent files below both its own formats.

Does Gemini CLI read AGENTS.md?

Only if you tell it to. Gemini CLI’s default context file is GEMINI.md, and the filename is configurable through the context.fileName property in settings.json. AGENTS.md appears in that page’s own example value, so this is a supported configuration rather than a workaround.

Loading is hierarchical once configured. The documentation describes a global file at ~/.gemini/GEMINI.md, then context files found in workspace directories and their parents, then just-in-time scanning of a directory and its ancestors when the CLI touches files there.

Does Cline read CLAUDE.md?

As of 17 August 2026, Cline’s rules documentation does not document reading CLAUDE.md. It lists four recognized sources instead: its own .clinerules/ directory, .cursorrules, .windsurfrules, and AGENTS.md at both the project root and ~/.agents/AGENTS.md.

That is a documented absence, not a refusal. If you run Cline on a repo whose only instruction file is a CLAUDE.md, the practical move is an AGENTS.md that Cline recognizes, since Cline is one of the four tools here that reads it without configuration.

Should I symlink CLAUDE.md to AGENTS.md, or import one into the other?

Import when you have Claude-specific lines to add, symlink when you do not. The import keeps one real file plus a short Claude-only section; the symlink keeps one real file and nothing else. Both remove the second copy that drifts.

The decision is entirely about that question and not about which is technically cleaner. If you cannot name a rule that applies to Claude Code and to nothing else, the symlink is the smaller thing to maintain. If you can name two or three, the import keeps them out of AGENTS.md, which every tool here reads; they still sit in CLAUDE.md, which Copilot and Cursor’s CLI also load, so keep them short and harmless there. The exact commands for both are documented on Anthropic’s memory page and covered in detail in writing about the AGENTS.md format itself.

What is the difference between AGENTS.md and Claude Skills?

Different mechanisms with different loading behavior. An instruction file is standing context loaded at the start of a session, while a skill is packaged instructions that load when invoked or when the model judges them relevant, which is why Anthropic’s own guidance moves multi-step procedures out of CLAUDE.md and into skills.

The practical test is whether the content applies to every session. Conventions and build commands belong in the instruction file. A long procedure you run occasionally belongs in a skill. The same test sorts Claude Code skills vs Cursor rules: an always-applied Cursor rule sits with the instruction files, and a manually invoked one sits with the skills.

Do AGENTS.md and copilot-instructions.md conflict if both exist?

AGENTS.md and copilot-instructions.md coexist, with a published order. GitHub’s response-customization page ranks path-specific .instructions.md files above repository-wide .github/copilot-instructions.md, and both above agent instructions, the category that holds AGENTS.md, CLAUDE.md and GEMINI.md. All relevant sets are still supplied to Copilot.

So a rule in copilot-instructions.md outranks the same rule in AGENTS.md, which is the opposite of what people assume when they treat the cross-tool file as the authoritative one. The same page advises avoiding conflicting instruction sets in the first place, which is easier than reasoning about the ranking.

Which file should a repo have if only one person works on it?

Whichever file the tools that person actually opens will read, which usually means one file and no second copy. A solo repo where every session runs in Claude Code needs a CLAUDE.md. A solo repo where the editor is VS Code with Copilot on, or Cursor, is already reading AGENTS.md.

Team size is the wrong variable here, and it is why searches phrased as agents md vs claude md file rarely get a useful answer. Count the tools, not the people. One person running three tools has the multi-tool problem; three people all running Claude Code do not.