# What I found in 39,535 CLAUDE.md and AGENTS.md files

> Source: <https://internals.laxmena.com/p/what-i-found-in-39535-claudemd-and>
> Published: 2026-11-17 15:03:41+00:00

I’ll start with a confession: I’ve never opened my own CLAUDE.md. In my hobby projects, I let my agents write it for me and moved on.

So when I wanted to learn how to write a good one, I went looking for a best practice. I found plenty of advice, and a few studies. But I was curious about something simpler. What do people actually write in these files? And how much of it is the same thing, written again and again across thousands of repositories?

(I originally wanted to do this for skills. This is the trial run.)

There are about two million of these files in GitHub’s search index now. Every study I could find looked at a few hundred to a few thousand of them, mostly from popular repos. But about nine in ten repos with one of these files are small: side projects, experiments, personal tools with a handful of stars or none. Repos like mine.

So I looked at all of them. Or as close to all of them as GitHub would let me.

**TL;DR**

- **AGENTS.md has overtaken CLAUDE.md:** 1,196,366 files against 876,678.
- **The typical CLAUDE.md costs about 1,379 tokens, every session.** The biggest 10% cost more than 4,469.
- **About 17% of those tokens go to overview sections,** the kind of content a 2026 study found doesn’t help agents.
- **26% of CLAUDE.md files still open with the generator’s stock line,** and that’s where most of the overviews live.
- **When a repo has both files, most link them,** but 12% keep near-identical copies by hand.

One thing before we start: this counts what people wrote, not whether it works. Skim the bold line under each heading if you’re short on time.

## The setup

**I sampled carefully and weighted the results back to the whole population.**

GitHub’s code search returns 1,000 results per query and about nine queries a minute, so listing every file would take days. I sampled slices of the index at random and measured every eligible repo in that sample, small and popular: 33,762 repos.

Why stop at 39,535 files, and not all two million? Honestly, because I wanted to publish this week. GitHub answers about nine search questions a minute, so I let neri run overnight and called it in the morning. The good news: when I grew the sample sixfold along the way, the headline numbers barely moved. More files would have mostly bought me more decimal places.

**Internals: why weighting matters.** Popular repos are easy to find and over-studied. Study only them and you describe one repo in ten. Weighting each repo by how likely it was to be sampled lets 33,762 repos stand in for public GitHub, with error bars that say how sure we can be.

I built a small tool for this and called it **neri** (நெறி), Tamil for “guideline” or “the right path”. I have a habit of giving my projects Tamil names; the last one was thedu, which means “search!”. The numbers come from plain code: counting tokens, finding sections, reading settings. Where judgment was needed, three AI models from different families labeled samples independently, and I checked the disagreements.

One boundary: this is the **public, committed** layer. Private repos, your personal instruction file and uncommitted settings are invisible to it.

## AGENTS.md has quietly become the default

**There are more AGENTS.md files than CLAUDE.md files, by every measure I tried.**

The index holds 1,196,366 AGENTS.md files and 876,678 CLAUDE.md files. Two in three repos have an AGENTS.md; a little over half have a CLAUDE.md. Plenty have both.

AGENTS.md is a generic name, so I didn’t fully trust it. I opened 40 at random and read them. 39 were instructions for a coding agent.

Looks like the harness-neutral name is winning. If you use more than one coding tool, you’re probably already writing for it. Even Anthropic came around. After a year-long GitHub issue with over five thousand upvotes, Claude Code started reading AGENTS.md in September, as long as no CLAUDE.md sits next to it. The AGENTS have it.

## Every session starts with a bill

**The typical CLAUDE.md loads about 1,379 tokens before your agent reads a line of your code.**

That’s 86 lines. The biggest 10% load more than 4,469 tokens each. AGENTS.md files run smaller, about 1,009 tokens.

This is where my original question got its answer. Popular and small repos write CLAUDE.md files of similar size (1,550 vs 1,361 tokens), and, as we’ll see, they fill them with similar things. If there were a best practice, I’d expect the popular projects to look different. They don’t. Everyone, me included, is still improvising.

**Internals: always-loaded vs on-demand.** The root CLAUDE.md, plus anything it pulls in with `@path` imports, loads every session. CLAUDE.md files in subfolders load only when the agent works there. The first is a fixed cost; the second is pay-as-you-go.

## A sixth of the bill goes to the overview

**43% of CLAUDE.md files have an overview-style section, holding about 17% of all CLAUDE.md tokens.**

“Project overview”, “Architecture”, “Tech stack”: these are the sections people write first. 18% of files also paste a directory tree.

Researchers at ETH Zurich ran coding agents on real tasks, with and without a context file. Repository overviews didn’t help agents find the right code, context files raised cost by over 20% on average, and agents *did* follow specific instructions. (Directory trees weren’t tested on their own.)

That stung a little. The part we write most is the part the research found least useful.

Here’s the twist, and it brings me back to my confession. 26% of CLAUDE.md files still carry the stock opening line that generated files share: *“This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.”* Those files have an overview section 87% of the time, against 28% for the rest, and overviews take up 41% of their tokens, against 7%.

So a lot of the overview habit isn’t people choosing to write overviews. It’s what the generator writes, and we keep it. Remember, I let my agents write mine. I’m in this number.

**Internals: how I spotted generated files.** I matched that opening line. I checked where it comes from by running Claude Code’s `/init` (version 2.1.326) in an empty folder: the file it wrote opens with `# CLAUDE.md` and exactly this sentence. It’s a text match, not proof of how a file was made: someone could type it, or delete it after generating.

## One file, rarely split

**83% of CLAUDE.md setups are a single file. 1.0% use** `@imports`**.**

Claude Code lets you import shared files, or put instructions in subfolders that load only when needed. Few people do: 16% have subfolder files, and imports barely register. The features are there. Most of us just don’t use them.

## Two names for one file

**Among repos with both CLAUDE.md and AGENTS.md, 58% link one to the other. 12% keep near-identical copies by hand.**

Most people do the sensible thing: a symlink, a one-line `@AGENTS.md` import, or a sentence that says “read AGENTS.md first”. One source of truth. The symlink is still the most common bridge, which makes sense: when both files exist, Claude still reads its own.

The copies are the ones to watch. Two files that say almost the same thing will eventually say different things. The other 30% keep two genuinely different files, which can be deliberate.

## Guardrails over trust

**About 10% of repos commit Claude Code settings. Of those, 41% define hooks; only 2% pre-approve any shell command.**

People who invest in configuration don’t open the gates. They add checks. Hooks most often run *before* the agent acts, and their script names tell the story: guards that block risky commands or protect data, context loaders at session start, formatters after an edit. One team runs a hook that updates its CLAUDE.md after every edit, the neatest answer to stale instructions I saw.

Prose tells the agent what to do. Hooks make sure it happens.

**Internals: hooks.** A hook is a command Claude Code runs on an event: before or after a tool runs, at session start, when the agent stops. Committed settings are what a team shares, so these are team setups, not personal ones.

## What I’d do with your file

I started this looking for a best practice, and the files didn’t give me one. So here’s what I’d do instead, pieced together from the numbers above and the studies that tested what helps. None of these is a guarantee. All of them are cheap to try.

- **Tell it how you check your work, if it isn’t obvious.** In Rust and Go, the agent can guess`cargo test` . In a JavaScript repo it can’t: which runner, which script, lint and typecheck too? Yet JavaScript files mostly say how to*run* the app, not how to*check* it.
- **If an agent wrote your file, edit it.** Start by cutting what the agent can read for itself: the overview and the directory tree. Keep what it can’t infer: conventions, gotchas, the reasons behind odd choices.
- **Say the few “don’t”s that matter.** In a small experiment its authors call suggestive, the rules that helped on their own were constraints like “don’t refactor unrelated code”. Here, the median file phrases only 4.3% of its rules that way.
- **Keep one source of truth.** Link CLAUDE.md and AGENTS.md; don’t copy.
- **Enforce what matters with a hook,** instead of asking nicely in prose.
- **Know what you load.**[This checker](https://concepts.laxmena.com/concepts/claude-md-census/) compares your file with everyone else’s. (I’m going to go open mine now.)

## Mistakes along the way

**Counting was easy. Knowing when my own checker was wrong was not.**

I wanted to measure how many instruction files point at things that no longer exist. My first detector flagged dead paths in about one repo in five, and was right only about half the time. It tripped on truncated repo listings, commands run from subfolders, placeholders like `path/to/file`, and files a tool creates at runtime.

The uncomfortable part: I had Claude Code label a sample of its own detector’s flags. Where we disagreed, it was always too generous, exactly where the detector was blind. An AI grading its own work repeated its own mistakes. So there’s no “how much is wrong” number here. That’s the next post.

**From the lab notebook, 17:36.** CLAUDE.md listing complete (2,140 buckets, 876,678 files).

Two “findings” also died before publication. Agent-file repos looked unusually young, until a baseline showed most active repos are young. And CLAUDE.md/AGENTS.md pairs looked like they’d drifted apart, until I found most were pointer files my detector missed. Both were caught by asking a different model to break the analysis, the most useful habit I took from this project.

## More numbers

- **Top command:**`npm:build` in 25% of npm-family repos,`cargo:test` in 58% of Rust repos,`go:test` in 53% of Go repos.
- **CLAUDE.md files not in English:** 18%, mostly Chinese, Spanish, Portuguese, Japanese and Korean.
- **Repos with a CLAUDE.md that also have skills:** 16%.
- **Files with a shouted IMPORTANT, NEVER or MUST:** 12%.
- **CLAUDE.md files that are near-copies of 4+ others:** 1.1%. People rarely copy whole files; line-level copying is the next question.

## What’s next

Next, two things I still want to know. How much of what we tell our agents is already out of date? And my original question, at the level of single lines: which instructions does everyone copy from everyone else? Then, skills.

If you maintain one of these files, I’d love to hear what surprised you, and criticism is just as welcome. The dataset is open; if you build something with it, show me.

*How I worked: analysis code written with Claude Code (Sonnet 5.5) and reviewed by me; Codex (GPT-5.6 Sol) and Gemini as independent reviewers and labelers. The writing is mine, edited with Claude.*

*INTERNALS.md: what happens inside the systems you build on. If this was useful, share it with an engineer who maintains an agent file.*

## Methods and limitations

- **Population:** public, non-fork, non-archived repos in GitHub code search (default branches, recently active), pushed in the 180 days before 15 Nov 2026, with a CLAUDE.md or AGENTS.md of 200 B–100 KB.
- **Sampling:** seeded random slices of the index, with inclusion probabilities recorded. Every eligible repo in each sampled slice was measured, small (0–9 stars) and popular (10+). Analyzed: 33,762 repos; 17,960 CLAUDE.md and 21,575 AGENTS.md files.
- **Estimates:** population-weighted, 95% bootstrap intervals clustered by repo, robustness check with trimmed weights. The small-repo share is weight-sensitive, hence “about nine in ten”.
- **Tokens:** an open tokenizer (o200k), as a proxy for Claude’s.
- **Checks:** commands 19/20 correct; link classes and instruction-file checks labeled independently by Claude Sonnet 5.5, Gemini (gemini-4-hydrogen, via OpenRouter) and Codex (codex-cli 0.169.0, GPT-5.6 Sol), with human adjudication. Dropped for failing validation: package-manager mismatch (2/20) and instruction “smells” (8/20).
- **Generator signature:** a text match for the sentence Claude Code’s`/init` writes, in the first ten non-empty lines. I confirmed it firsthand by running`/init` in an empty folder with Claude Code 2.1.326. A file with the line may have been edited, and a generated file may have had it removed, so it is not proof of how a file was made.
- **Not visible:** private repos, personal or global instruction files, uncommitted settings (so broad permissions are likely undercounted).
- **Data and code:** pointers and derived features only, no third-party file text:[https://github.com/laxmena/neri](https://github.com/laxmena/neri)

## Sources

- Gloaguen et al., *[Evaluating AGENTS.md](https://arxiv.org/abs/2602.11988)* , arXiv:2602.11988 (ETH Zurich, 2026).
- Zhang et al., *[Guardrails Beat Guidance](https://arxiv.org/abs/2604.11088)* , arXiv:2604.11088 (2026).
- Chatlatanagulchai et al., *[Agent READMEs](https://arxiv.org/abs/2511.12884)* , arXiv:2511.12884.
- Mohsenimofidi et al., *[Context Engineering for AI Agents in Open-Source Software](https://arxiv.org/abs/2510.21413)* , arXiv:2510.21413.
- Jiang & Nam, *[Beyond the Prompt: An Empirical Study of Cursor Rules](https://arxiv.org/abs/2512.18925)* , arXiv:2512.18925 (MSR 2026).
- Sharma, *[ContextCov](https://arxiv.org/abs/2603.00822)* , arXiv:2603.00822.
- Thariq Shihipar, [AGENTS.md support in Claude Code](https://simonwillison.net/2026/Sep/18/thariq-shihipar/) (Sept 2026), and the[v2.1.277 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.277) .
- GitHub Docs, *[About searching code](https://docs.github.com/en/search-github/github-code-search/about-github-code-search)* .
