AGENTS.md or CLAUDE.md? What 592 Top Repositories Actually Contain

Anthropic's AI-native SDLC playbook reorganizes all six stages of software delivery around coding agents. Stage 3 asks for one concrete artifact: CLAUDE.md, a repository-level knowledge file that gets updated each time an agent repeats the same mistake. A survey of the most-starred public repositories tested how much of that advice shows up in practice, and the answer is surprising. CLAUDE.md is winning in file count and losing in content.

The headline numbers

On 8 September 2026, a probe covered the 592 most-starred repositories drawn from six language rankings (TypeScript, Python, Go, Rust, Java and JavaScript, deduplicated). It looked for CLAUDE.md and several neighboring files.

• 165 repositories (27.9%) contain a CLAUDE.md.
• 94 of those 165 (57.0%) contain no repository knowledge at all. They are redirects.
• Of those 165, 94 (57.0%) hold no repository knowledge whatsoever. They are redirects.
• 209 repositories, 35.3%, contain an AGENTS.md, and 93.8% of those carry real content.
• Where both files exist (132 repositories), 89 point CLAUDE.md at AGENTS.md. Only 10 point the other way.
• Just 5.9% have a .claude/settings.json, the place where the playbook's Stage-3 hooks are configured.
• Substantive CLAUDE.md files have a median size of 3,934 bytes, and the largest reaches 66,176.

Take out the redirects and only 12.0% of top repositories have a CLAUDE.md with anything in it. A substantive AGENTS.md appears in 33.1%.

For anyone adopting the playbook now, the takeaway is mixed. Agents do need a committed, version-controlled knowledge file, yet the playbook names the wrong file. Across these repositories CLAUDE.md has turned into a compatibility shim sitting in front of AGENTS.md, a vendor-neutral file read by every major coding agent. The projects that have already settled this wrote their knowledge once in AGENTS.md and left a one-line pointer behind.

How the count was made

The sampling frame was a public GitHub ranking snapshot, the top 100 repositories by stars in each of the six languages, which collapsed to 592 unique repositories after deduplication. A fixed set of paths was requested at HEAD from raw.githubusercontent.com, with no API key, no authentication and no scraping. The question was only whether a file exists and what it says. Then all CLAUDE.md and AGENTS.md bodies were downloaded, 374 files across 242 repositories, and read by hand.

That reading is where the headline fell apart. The median CLAUDE.md turned out to be two lines long, so 27.9% on its own says almost nothing.

What those files contain

None of the common shapes is real knowledge:

• A git symlink. The file is nine bytes, just the text AGENTS.md without a trailing newline, since git keeps a symlink as a blob containing its target. openclaw, dify, ant-design, moby, home-assistant, superset, Stirling-PDF and nushell are examples.
• A single import line, @AGENTS.md, eleven bytes, which Claude Code resolves when it loads. n8n, supabase, grafana, nuxt, storybook, prometheus, traefik, ruff and pdf.js work this way.
• One sentence of prose. In lazygit it amounts to an instruction to read AGENTS.md first and follow it. Google Workspace's CLI says the same at greater length.

A few edge cases matter to anyone building a classifier. Docusaurus has a heading followed by the import and nothing else. Jest points at .github/copilot-instructions.md instead. Ansible consists of three import lines with no prose. Zed symlinks to a file named .rules.

After excluding every file whose only content is a redirect, 71 of the 592 repositories have a CLAUDE.md with repository knowledge in it, or 12.0%. Those 71 are real, some of them large: median 3,934 bytes, 90th percentile 19,506, maximum 66,176. Projects like bun, pytorch, swc, gstack and 3x-ui maintain genuine operational guides covering build commands, repository maps, testing philosophy and directory-scoped rules.

Where the knowledge actually lives

In AGENTS.md, and by a wide margin. Its substantive rate is 93.8%, 196 of 209 files, against 43.0% for CLAUDE.md. That asymmetry is the story. A repository that writes an AGENTS.md nearly always fills it with content. A repository that writes a CLAUDE.md more often than not builds a bridge to somewhere else.

The 132 repositories that carry both files make the direction explicit:

• In 89 of them CLAUDE.md is the pointer and AGENTS.md holds the content.
• In 10 the roles are reversed: AGENTS.md redirects and CLAUDE.md is the real file. Pytorch, bun, milvus, anki and litellm are among them.
• 31 keep substantive content in both, meaning the same institutional knowledge is maintained twice.
• 2 have pointers in both, which implies a third file somewhere.

Redirects therefore flow roughly nine to one toward the vendor-neutral file. A one-directional result is often a measurement artifact, so the opposite case was searched for on purpose. It exists, but only as a minority.

Adoption by language

The spread between languages is wide enough to plan around. CLAUDE.md share first, AGENTS.md second:

• TypeScript: 46.5% and 53.5%.
• Rust: 33.3% and 43.4%.
• Go: 32.3% and 37.4%.
• Python: 25.5% and 31.6%.
• JavaScript: 19.0% and 23.0%.
• Java: 10.3% and 22.7%.

AGENTS.md leads in every language. Java shows the sharpest gap, with a repository more than twice as likely to have AGENTS.md as CLAUDE.md, and TypeScript projects are over four times as likely as Java ones to have a CLAUDE.md. Across all six languages, 43.2% of top repositories have some agent-instruction file, whether AGENTS.md, CLAUDE.md, .cursorrules or Copilot's instructions file. Copilot's is present in 9.3%. The .cursorrules convention has nearly vanished from this group at 0.5%, a good reminder of how quickly a vendor-specific habit can die.

The rest of the Stage-3 stack

Platform teams should read this part carefully. The playbook asks for more than a knowledge file: it combines knowledge files, skills and hooks, and hooks are the enforcement layer that stops dangerous actions during builds.

Only 35 of 592 repositories (5.9%) have a .claude/settings.json, and only 32 (5.4%) have it together with a CLAUDE.md. The documentation piece, which is just a file anyone can write, is what people adopted. The enforcement layer, the one that actually changes what an agent may do, exists in about one repository in eighteen. A playbook whose safety story depends on hooks describes something almost nobody has built yet.

Limits of the data

• The sample is public repositories ranked by stars. A playbook like this is deployed in private enterprise repositories, which cannot be seen. Adoption there may be higher and more disciplined.
• It is a single snapshot, taken at HEAD on 8 September 2026. Adoption moves quickly, so within a month the percentages will be wrong, and direction matters more than level.
• A file is not a practice. A substantive CLAUDE.md shows only that someone wrote one. It gives no evidence that anyone maintains it or that agent output improved. Published work questions whether these files help coding agents at all, and this measurement says nothing about that.
• The settings.json file is a proxy for hooks and not a census. Any hooks defined in other locations go unseen, which makes 5.9% a minimum.
• The pointer versus substantive boundary is a judgment call. The cut was 120 characters of leftover prose after stripping headings, imports and redirect sentences. The fourteen files closest to that line were audited manually, and the nearest substantive file, lazydocker, has 172 characters of real build flags. Moving the threshold moves the number. A second hand-check of 25 repositories against live files found that errors run in one direction: the classifier occasionally passes a redirect as substantive when the redirect is worded as an instruction to the agent instead of a statement about where documentation lives, as in zeroclaw. So 57.0% is a floor, and the true pointer share is slightly higher.

There was also a near miss worth admitting. The first pass reported that 27.9% of top repositories had adopted CLAUDE.md, and that line would have been published. The two-line median is what stopped it.

Practical answers

Which file should hold the content? The evidence favors AGENTS.md, with CLAUDE.md reduced to a pointer. Most dual-file repositories (89 of 132) do exactly that. One copy of the knowledge remains, and agents that never search for a Claude-specific filename can still read it.

Does Claude Code read AGENTS.md directly? Not by naming convention, unlike CLAUDE.md, and that gap is why the pointer pattern exists. Two forms work in practice: a git symlink named CLAUDE.md that targets AGENTS.md, or the @AGENTS.md import. The new-api project even cautions in its own CLAUDE.md that the import does not always load reliably, and directs the agent to open the file itself.

Is 27.9% adoption good or bad? Better than expected for such a young convention, worse than the playbook implies. Two other figures say more: 12.0% of repositories have CLAUDE.md files with real content, and only 5.4% pair one with enforcement hooks.

Why would 31 repositories keep both files substantive? Drift between the copies was never measured, which is the clear next study. Duplicate institutional knowledge becomes a liability once the copies disagree, and tooling gives no warning.

Can others repeat this? Yes. The sample comes from a public star ranking, the probe is plain unauthenticated HTTP requests to raw.githubusercontent.com, and the classifier fits in roughly 40 lines.

One closing check for anyone running a repository with a coding agent attached: the last time a build command changed, did the agent's knowledge file change in the same commit, or did the stale command surface three sessions later?