AGENTS.md vs CLAUDE.md
They are not competitors and most teams that use one seriously end up shipping both. AGENTS.md is a vendor-neutral file read by 23 tools; CLAUDE.md is Anthropic’s file, read by Claude Code alone, and it can do two things AGENTS.md cannot — import other files and apply from your home directory across every project. Of the 264 repositories in this corpus carrying a CLAUDE.md, 52.7% also carry an AGENTS.md. This page puts the documented capabilities and last night’s counts side by side, and marks which is which.
Write AGENTS.md first, and add a CLAUDE.md only when you want something AGENTS.md does not have. That is not a preference; it is what both vendors' own pages say. Anthropic documents the interop explicitly — "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 the two-file arrangement costs one line and no duplicated prose. Choose CLAUDE.md as the primary file when your instructions have outgrown one document: it is the only one of the two with an import syntax, resolved recursively "with a maximum depth of four hops", and the only one with a documented gitignored companion for personal notes. Choose AGENTS.md as the primary file when more than one agent touches the repository, because it is the only one of the two not owned by the tool that reads it — it is "stewarded by the Agentic AI Foundation under the Linux Foundation", and it is named as a readable format on GitHub's, Cursor's and Cline's own documentation. Both handle a monorepo, and they handle it the same way: the nearest file to the code wins.
Should you use AGENTS.md or CLAUDE.md?
Write AGENTS.md first, and add a CLAUDE.md that imports it if anyone on the team uses Claude Code. AGENTS.md is the file with reach — 23 tools read it, including Cursor, Codex, Copilot’s coding agent, Gemini CLI, Zed, Aider and Windsurf — and it is deliberately unstructured: AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
CLAUDE.md is read by exactly one tool, and Anthropic is explicit that the two are not the same file: Claude Code reads CLAUDE.md, not AGENTS.md.
What makes the pairing cheap rather than duplicative is that CLAUDE.md supports imports, so a two-line CLAUDE.md whose first line is @AGENTS.md gives Claude Code the same instructions every other agent already reads, with room underneath for anything Claude-specific. In this corpus 139 repositories do exactly that kind of pairing — 52.7% of everything carrying a CLAUDE.md and 32.4% of everything carrying an AGENTS.md. Quotations read from agents.md and Claude Code — How Claude remembers your project 2026-08-08
AGENTS.md vs CLAUDE.md, row by row
The top band is asserted — capability rows read from each format’s own documentation, stamped with the day that reading was last checked. The bottom band is measured, counted from real repositories on 2026-08-15. Every file column here counts all indexed files, including the nested per-package ones; the root-only figures further down are a different and narrower basis.
| Format | AGENTS.md 2026-08-02 | CLAUDE.md 2026-08-02 |
|---|---|---|
| Asserted — what the docs say it can express | ||
| File | AGENTS.md | CLAUDE.md |
| Status | open-standard | vendor |
| Cross-tool | Yes | No |
| Tools that read it |
|
|
| Frontmatter | No | No |
| Glob targeting | No | No |
| Imports other files | No | Yes |
| Nested / per-directory | Yes | Yes |
| Multiple files | Yes | Yes |
| User-level scope | No | Yes |
| When it applies | Always in scope; in a monorepo the nearest AGENTS.md to the edited file wins. | Always in scope. Project file, plus nested files in subdirectories, plus a user-level file (~/.claude/CLAUDE.md) that applies across every project. |
| Size limits | None | None |
| Measured — counted from real repositories on 2026-08-15 | ||
| Repositories carrying it | 429 | 264 |
| Share of indexed repos | 57.5% | 35.4% |
| Files indexed | 1,496 | 842 |
| Median length (words) | 937 | 1,923 |
| 90th percentile length | 2,970 | 3,001 |
| Files naming commands | 44.7% | 37.9% |
| Files containing code | 36.6% | 35.6% |
| Median quality score | 54 | 44 |
| Median repository stars | 10,042 | 133 |
Does Claude Code read AGENTS.md?
No. Anthropic’s memory documentation states it in one line — Claude Code reads CLAUDE.md, not AGENTS.md
— and a repository that ships only an AGENTS.md hands Claude Code nothing at session start. Two documented workarounds exist and both are one line of work. The first is an import: create a CLAUDE.md whose first line is @AGENTS.md, which Anthropic recommends directly — create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them
— and add any Claude-specific rules below the import. The second is a symlink, ln -s AGENTS.md CLAUDE.md, which is documented as working when you have no Claude-specific content to add, with the caveat that on Windows it needs Administrator privileges or Developer Mode. Separately, the /import command copies another agent’s configuration, AGENTS.md included, into the matching CLAUDE.md as a one-time append; that route requires Claude Code v2.1.213 or later. Read from the Claude Code memory documentation 2026-08-08
Which tools read AGENTS.md and which read CLAUDE.md?
AGENTS.md is read by 23 tools and CLAUDE.md by one. The AGENTS.md list on the format’s own site names OpenAI Codex, Cursor, Amp, Aider, Zed, Google Jules, Gemini CLI, Factory and 15 others; the format is described there as used by over 60k open-source projects
, and stewardship now sits with the Agentic AI Foundation under the Linux Foundation rather than with any single vendor, which is the concrete reason it is an open standard rather than one company’s file with a generic name. CLAUDE.md is Anthropic’s own file — the canon dates it to 2025-02 — and Claude Code is the only tool that loads it. Cursor is the case worth knowing about, because it reads both: its rules documentation says Nested AGENTS.md support in subdirectories is now available
, alongside its own .cursor/rules/*.mdc files. That asymmetry is the whole argument for writing the instructions once in AGENTS.md and pointing everything else at them. Tool list and stewardship read from agents.md ; Cursor’s support read from Cursor — Rules 2026-08-08
How many repositories actually use each one?
AGENTS.md leads on repositories and CLAUDE.md leads on the share of its users who also run the other file. Counted on 2026-08-15, 429 repositories in the corpus carry at least one AGENTS.md against 264 carrying a CLAUDE.md — 57.5% and 35.4% of everything indexed — across 1,496 and 842 files respectively, since a repository may ship several. The number no capability table can produce is the intersection: 139 repositories carry both, which is 52.7% of the CLAUDE.md population and 32.4% of the AGENTS.md one. Read that asymmetry carefully, because it is the practical finding on this page: adopting CLAUDE.md is usually a decision made in addition to AGENTS.md, while adopting AGENTS.md frequently is not. The audiences also differ sharply by project size — the median AGENTS.md repository has 10,042 stars against 133 for CLAUDE.md.
What can CLAUDE.md do that AGENTS.md cannot?
Import other files, and apply from outside the repository. CLAUDE.md supports @path/to/import syntax with both relative and absolute paths, and imported files can recursively import other files, with a maximum depth of four hops
— the mechanism that makes @AGENTS.md work at all. It also has scopes above the project: a personal ~/.claude/CLAUDE.md that applies to every project on your machine, a managed-policy file an organisation can deploy to every developer, and a gitignored ./CLAUDE.local.md for things like sandbox URLs. AGENTS.md has none of these; it is one file per directory and nothing else. One caution that catches teams reaching for imports as a size fix: the documentation is direct that splitting into imports helps organization but doesn’t reduce context, since imported files load at launch
. The documented answer to length is .claude/rules/ with a YAML paths: field of globs, which loads a rule only when Claude opens a matching file — a separate artifact from CLAUDE.md, which is why the capability table above still records CLAUDE.md itself as having no glob targeting. Import, scope and rule behaviour read from the Claude Code memory documentation 2026-08-08
What can AGENTS.md do that CLAUDE.md cannot?
Reach every other agent, and stay readable when the tooling changes. An AGENTS.md is read by 23 tools against CLAUDE.md’s one, so it is the only one of the two that survives a teammate switching editors or a repository being handed to a contributor using something else. It also asks nothing of the author: AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
There is no frontmatter, no required schema and no filename convention beyond the name itself — which is worth weighing against Cursor’s .mdc rules, where a plain .md file in .cursor/rules is simply ignored. The trade is real rather than free: with no schema there is nothing to validate against, and no equivalent of ~/.claude/CLAUDE.md for the preferences you want on every project you touch. Read from agents.md 2026-08-08
Which one is better for a monorepo?
AGENTS.md and CLAUDE.md both support nested files, and they resolve them in opposite ways — which is the difference that actually matters in a monorepo. AGENTS.md narrows: Agents automatically read the nearest file in the directory tree, so the closest one takes precedence
, so a package’s own file replaces the root file for work inside that package. CLAUDE.md accumulates: files up the tree from the working directory are concatenated into context rather than overriding each other
, ordered from the filesystem root down, with files in subdirectories loaded on demand when Claude reads something in them. Practically, a per-package AGENTS.md can contradict the root one and win; a per-package CLAUDE.md sits alongside the root one and both are in context at once, which is why Anthropic’s guidance on conflicting instructions matters and why the claudeMdExcludes setting exists at all. In this corpus, monorepo scoping is under-documented either way: 7.8% of root AGENTS.md files and 6% of root CLAUDE.md files say anything about it. Precedence rules read from agents.md and the Claude Code memory documentation 2026-08-08
Do the two files actually contain different things?
Less than the specifications suggest. On a root-files-only basis the median AGENTS.md runs 723 words across 11 headings, and the median CLAUDE.md 730 words across 13 headings. 76.8% and 79.2% respectively contain at least one runnable command, and both cover a median of 6 of the 20 sections in the table below. Two files of near-identical shape, written for different readers. Note that these root-only medians are lower than the all-files medians in the matrix above, which count nested per-package files too; the bases are different and the numbers are not comparable across them. Where the formats do diverge is emphasis: CLAUDE.md files lead on Agent behaviour (+21 pts) and Architecture (+11 pts), while AGENTS.md files lead on Git, commits & PRs (+14.9 pts) and Code style (+13.5 pts).
| Section | AGENTS.md | CLAUDE.md | Gap |
|---|---|---|---|
| Agent behaviouragent-behaviour | 61.4% | 82.4% | +21 pts |
| Code stylecode-style | 71.8% | 58.3% | -13.5 pts |
| Teststest | 56.4% | 59.7% | +3.3 pts |
| Hard prohibitionsdo-not | 50.9% | 48.6% | -2.3 pts |
| Git, commits & PRsgit-pr | 55.6% | 40.7% | -14.9 pts |
| Architecturearchitecture | 41.8% | 52.8% | +11 pts |
| Buildbuild | 40.7% | 39.4% | -1.3 pts |
| Lint & formatlint-format | 39.2% | 37.5% | -1.7 pts |
| Setup & installsetup | 28.2% | 36.6% | +8.4 pts |
| Documentationdocs | 26.4% | 24.1% | -2.3 pts |
| Securitysecurity | 24.3% | 17.6% | -6.7 pts |
| Deploy & releasedeployment | 17% | 23.6% | +6.6 pts |
| Typestypes | 18.3% | 20.8% | +2.5 pts |
| Testing strategytesting-strategy | 17.8% | 21.3% | +3.5 pts |
| APIs & contractsapi | 15.4% | 13.4% | -2 pts |
| Dependenciesdependencies | 13.1% | 15.7% | +2.6 pts |
| UI & componentsui | 11.5% | 13% | +1.5 pts |
| Database & migrationsdatabase | 10.4% | 12.5% | +2.1 pts |
| Performanceperformance | 10.2% | 10.2% | — |
| Monorepomonorepo | 7.8% | 6% | -1.8 pts |
Which file survives a context compaction?
For Claude Code, a project-root CLAUDE.md is re-injected after /compact and a nested one is not. The documentation is specific: Project-root CLAUDE.md survives compaction: after /compact, Claude re-reads it from disk and re-injects it into the session
, while nested CLAUDE.md files and rules carrying paths: frontmatter are not re-injected automatically; they reload the next time Claude reads a file in that subdirectory or a file matching the rule’s patterns
. This is a real argument for keeping the rules you cannot afford to lose — the prohibitions, the commit policy, the build command — in the root file rather than distributed into per-package ones. No equivalent guarantee is documented for AGENTS.md, because compaction is a property of the tool reading the file rather than of the format, and AGENTS.md is read by 23 tools that each handle their own context. Compaction behaviour read from the Claude Code memory documentation 2026-08-08
Where can I read real AGENTS.md and CLAUDE.md files?
Every file counted on this page is indexed and readable at the commit it was scraped from. The two starting points are the AGENTS.md index ranked by quality score and the CLAUDE.md index; each entry breaks out the file’s sections, extracted commands and score, and links to the file on GitHub. For the annotated walk-throughs, see the best AGENTS.md examples and what should go in a CLAUDE.md file. To read one file against another line by line, the diff tool takes any two indexed configs. The capability canon for each format, with the date every row was last verified, is on the AGENTS.md format page and the CLAUDE.md format page.
Running both, in full
The whole of it, for a repository that already has an AGENTS.md and wants Claude Code reading the same instructions. Anthropic documents this exact file.
1@AGENTS.md23## Claude Code45Use plan mode for changes under `src/billing/`.
Claude loads the imported file at session start, then appends whatever follows. Nothing is duplicated, and the 23 tools that read AGENTS.md are unaffected by the second file existing.
Does Claude Code read AGENTS.md?
No. Anthropic's memory documentation states it directly: "Claude Code reads CLAUDE.md, not AGENTS.md." The documented fix is not to duplicate the file but to import it — "create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them", after which Claude-specific instructions can be appended below the import. A symlink is documented as the alternative where you have nothing Claude-specific to add, with the caveat that on Windows a symlink needs administrator privileges or developer mode.
Can I use AGENTS.md and CLAUDE.md at the same time?
Yes, and the import path is the documented way to do it without maintaining two copies of the same prose. A CLAUDE.md whose first line is an @-import of AGENTS.md loads the imported file at session start and then appends whatever else the file says. Anthropic's page shows exactly that arrangement. GitHub documents a third variation on the same idea: Copilot reads AGENTS.md files "stored anywhere within the repository" and, alternatively, "a single CLAUDE.md or GEMINI.md file stored in the root of the repository", so a repository carrying both is a repository every one of those three agents can read.
Which one should I use in a monorepo?
Either — they resolve nesting the same way, and the difference is when the files load rather than which one wins. AGENTS.md says "agents automatically read the nearest file in the directory tree, so the closest one takes precedence", and cites the main OpenAI repository as carrying 88 of them. Anthropic's page says Claude "discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory" but that "instead of loading them at launch, they are included when Claude reads files in those subdirectories" — so a deep monorepo costs context only as it is touched. If you need a rule that loads on a file pattern rather than a directory, that is a third mechanism on the Claude side: .claude/rules/ files "can also be scoped to specific file paths".
How long should the file be?
Anthropic publishes a number and agents.md does not. The memory docs say "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence", and point at path-scoped rules for anything larger. agents.md publishes no line count, no byte budget and no context-cost guidance at all; its sizing advice is editorial — "anything you'd tell a new teammate belongs here too". Of the five formats RuleStack tracks, only two publish a number: 200 lines for CLAUDE.md and 500 lines per rule for Cursor.
What happens when two instruction files disagree?
Both resolve it by proximity, and both say so. agents.md: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." Anthropic's docs describe the same outcome through load order rather than a winner — every discovered file is concatenated, "content is ordered from the filesystem root down to your working directory", so "instructions closer to where you launched Claude are read last", and within a directory CLAUDE.local.md is appended after CLAUDE.md.
