Locul / Tools / The State of CLAUDE.md

Original research · data collected 8 Oct 2026

The State of CLAUDE.md: what 6,967 public files contain

We downloaded 6,967 CLAUDE.md files from public GitHub repositories, plus 2,484 AGENTS.md files to compare, and measured what is in them: length, sections, commands, imports, the files that sit next to them, and how often anyone edits them. Below are the numbers, a template built from them, and a checker for your own file.

Junaid Khalid By Junaid Khalid| Published | Data: GitHub, collected
6,967CLAUDE.md files measured
100median lines
22%over 200 lines
37%keep the /init header

The short answer

A CLAUDE.md file is the Markdown instruction file Claude Code loads at the start of every session. A typical public one is 100 lines long (about 1,256 tokens), and 22% are longer than Anthropic's 200-line target. Most name real commands (76% list at least one tool such as npm or pytest), but 37% still open with the boilerplate line /init writes, only 12% have a security heading, and only 3.8% use @imports. 38% of files were committed once and never edited again.

The sample: 6,967 root-level CLAUDE.md files from public, non-fork repositories, drawn in proportion to the sizes of the roughly 590,000 such files GitHub's code search indexes. 6,688 of them have real content; the rest are one-line pointers or near-empty. What stands out:

  1. The median file is 100 lines; 22% are over 200. Anthropic's docs say to "target under 200 lines". 4.4% of files run past 500 lines. See the distribution.
  2. 37% still carry the /init header. The line "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository" is left in place. It tells Claude nothing it does not already know.
  3. Commands are the core. 76% of files name at least one command-line tool, and 73% mention tests somewhere. npm alone appears in 26% of all files. See the tools.
  4. Security is the gap. 36% mention secrets, keys or .env anywhere, and only 12% give security its own heading. 7% of repos commit .claude/settings.local.json, a file Claude Code keeps out of git when it creates it.
  5. AGENTS.md is moving in next door. 21% of repos with a CLAUDE.md also have an AGENTS.md, and the most common @import target is AGENTS.md itself. Compare the two.
  6. Most files are written once. 38% have a single commit, the median is 2 commits, and 34% have not been touched in six months. See upkeep.
  7. Popular repos write longer, more complete files. In repos with 100+ stars the median is 138 lines, 49% have a testing section (all files: 33%) and 82% name a command. See the table.

What the docs and earlier research say

"Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."
Anthropic, Claude Code docs: memory
"We conclude that while context files are useful for specifying non-standard coding practices, any attempts to improve performance should be rigorously evaluated before deployment."
Gloaguen et al., Evaluating AGENTS.md (arXiv, 2026)
"non-functional requirements such as security (14.8%) and performance (14.5%) are rarely specified."
Chatlatanagulchai et al., Agent READMEs (arXiv, 2025)
"Never commit secrets" was the most common helpful constraint.
Matt Nigh, GitHub Blog (2025)
Length

How long is a typical CLAUDE.md file?

The median CLAUDE.md is 100 lines, about 675 words or 1,256 tokens. Half of all files fall between 59 and 180 lines. Anthropic's guidance is to "target under 200 lines per CLAUDE.md file", and 22% of files are over it; 4.4% pass 500 lines. Pointer files and near-empty files are left out of these length numbers.

Lines per CLAUDE.md file

Share of 6,688 files with real content, by line count. Amber bars are over Anthropic's 200-line target.

1-2526-5051-100101-150151-200201-300301-500501-1k1k+

Lines are counted as they are in the file, blank lines included. Tokens are estimated at 4 characters per token.

Length percentiles
Measure10th pct25thMedian75th90th
Lines3359100180334
Words2043766751,2372,276
Estimated tokens3696901,2562,3164,247
Headings46101627
Code blocks00248

All 590,000 indexed root CLAUDE.md files, by size

GitHub's own counts for filename:CLAUDE.md path:/, per size range. Our sample follows these proportions.

under 0.5 KB~30,592 files5.2%
0.5-1 KB~22,784 files3.9%
1-2 KB~48,640 files8.3%
2-3 KB~68,224 files12%
3-4 KB~71,808 files12%
4-5 KB~51,968 files8.9%
5-6.5 KB~65,536 files11%
6.5-8 KB~44,032 files7.5%
8-10 KB~50,624 files8.6%
10-13 KB~40,704 files6.9%
13-17 KB~32,256 files5.5%
17-25 KB~27,712 files4.7%
25-50 KB~22,112 files3.8%
over 50 KB~9,440 files1.6%

GitHub reports these counts as estimates. They cover non-fork public repositories in its code search index.

Contents

What do CLAUDE.md files actually contain?

Most CLAUDE.md files contain build and run commands, architecture notes, a project overview and code style rules; testing, git and security sections are far rarer. By heading, the most common are commands (64% of files), architecture (56%) and a project overview (50%). Code style follows at 50%, then structure (41%). Testing gets a heading in 33%, git and pull requests in 19%, gotchas in 15% and security in 12%. The median file has 10 headings; 1.5% have none at all. Switch the group to see how popular repos and each language differ.

Show files from

Share of files with a heading about…

All 6,688 files with real content. Median length: 100 lines.

Commands (build, run, dev)64%
Architecture56%
Project overview50%
Code style and conventions50%
Project structure / layout41%
Agent workflow40%
Rules and constraints37%
Testing33%
Setup and environment31%
Tech stack and dependencies31%
API, data and database30%
Deploy and CI21%
Docs and references20%
Git, commits and PRs19%
Gotchas and troubleshooting15%
Security and secrets12%

A file counts once per category if any heading matches. One heading can match more than one category ("Build and test commands" counts for both).

Topics mentioned anywhere in the file

Not only in headings: any mention in the text.

Tests73%
Linting39%
Secrets, keys or .env36%
CI27%
A formatter23%
Pull requests22%
Type checking18%
Commit message rules13%

Claude Code features mentioned

How many files talk about the newer parts of Claude Code.

MCP servers14%
Skills9.2%
Subagents5.1%
A memory bank or progress file3.2%
Claude Code hooks3%
Slash commands2.8%
Plan mode1.1%
"think hard" / ultrathink0.2%

The 30 most common section headings

Level-2 headings, lowercased, with numbering and emoji stripped. The share is of files with real content.

architecture 32%project overview 24%commands 19%conventions 8.3%testing 7.4%development commands 7.4%project structure 6.9%tech stack 5.8%what this is 5.6%stack 3.6%common commands 3.6%environment variables 3.3%code style 3.2%architecture overview 3.1%project 2.9%overview 2.7%development workflow 2.5%deployment 2.4%build commands 2.4%layout 2.3%dependencies 2.3%key files 2.2%configuration 2%repository structure 1.9%important notes 1.9%code conventions 1.7%development notes 1.6%what this project is 1.6%development guidelines 1.6%gotchas 1.5%
Commands

Which commands and tools do the files name?

76% of files name at least one command-line tool in a shell block or inline code. JavaScript tooling leads: npm appears in 26% of all files and git in 16%. Among the 2,367 files that name a JavaScript package manager, 73% use npm, 20% pnpm, 7.7% bun and 3.7% yarn (a file can name more than one). Beyond running things, 39% mention a linter, 18% type checking and 13% give commit message rules.

Command-line tools named

From shell code blocks and inline code that starts with the tool's name.

npm26%
git16%
python10%
npx9.1%
pip7.5%
make7.2%
pnpm7.1%
docker6.5%
uv5.5%
node5.2%
cargo4.7%
python34.4%
gh4.4%
pytest4.2%
go3.7%
bun2.7%

Tech the files talk about

Any mention in the file text.

TypeScript36%
Python29%
React23%
Tailwind17%
Docker16%
JavaScript14%
PostgreSQL13%
Next.js11%
Rust7.7%
FastAPI6.9%
C#/.NET5.7%
Java5.2%
Supabase4.6%
Go4.4%
CLAUDE.md vs AGENTS.md

Is CLAUDE.md the same as AGENTS.md?

Same idea, different reader. Claude Code reads CLAUDE.md; Codex, Cursor, Copilot and others read AGENTS.md, and Anthropic's docs now say "Claude Code can read AGENTS.md as your project instructions". In practice many repos keep both: 21% of repos with a root CLAUDE.md also have an AGENTS.md, and 35% of repos with an AGENTS.md also have a CLAUDE.md. 3.4% of CLAUDE.md files are pointers ("See AGENTS.md" or a one-line @AGENTS.md), against 1.8% of AGENTS.md files pointing the other way. Next to the file, 32% of repos commit a .claude/ folder, most often for skills (14% of all repos) and shared settings (11%).

Other agent files in the same repo

Share of repos with a root CLAUDE.md that also have…

AGENTS.md21%
.mcp.json5.1%
.github/copilot-instructions.md3.6%
.cursor/rules/2.4%
GEMINI.md2.2%
.cursorrules0.9%
.windsurfrules0.3%

What is inside the .claude/ folder

32% of these repos commit a .claude/ folder. Share of all repos with each entry:

skills/14%
settings.json11%
settings.local.json7%
commands/6.7%
agents/6.7%
hooks/3.3%
rules/2.4%
launch.json1.9%
CLAUDE.md and AGENTS.md compared
MeasureCLAUDE.mdAGENTS.md
Files in sample6,9672,484
Median lines10077
Median words675520
Over 200 lines22%19%
Pointer files (hand off to another file)3.4%1.8%
Names a runnable command76%72%
Has a testing section33%41%
Mentions secrets or .env36%32%
Repo also has the other file21%35%
Median commits to the file22

Both samples were drawn the same way on the same day. Length rows exclude pointer and near-empty files.

Upkeep

How often are CLAUDE.md files updated?

A CLAUDE.md is only as good as its last edit. On the default branch, 38% of files have a single commit, 26% have two or three, 23% have four to ten and 13% have more than ten. The median file was last changed 133 days before we collected the data, and 36% were edited in the last 90 days. Almost all of these files are new: 81% were first committed in 2026.

38%were committed once and never changed
23%have 4 to 10 commits
14%were edited in the last 30 days
34%untouched for over 180 days

When each file was first committed

Month of the first commit that touched the file, for files with up to 50 commits. Hover a bar for the share.

Feb 2025Oct 2026 (partial)

Based on 6,865 files whose full history we could read. October 2026 is a partial month (data collected on the 8th).

Tone

Do people shout at Claude? IMPORTANT, MUST and NEVER

Some files read like a terms-of-service page: IMPORTANT, MUST, NEVER in capitals. Fewer than you might think do it. 16% of files use at least one shouted word and only 3.6% use five or more. MUST is the most common (8.2% of files), then NEVER (6.6%), CRITICAL (4.7%), IMPORTANT (3.8%), ALWAYS (3.9%) and DO NOT (1.9%). Code blocks are not counted.

Anthropic's advice points the other way from volume: "The more specific and concise your instructions, the more consistently Claude follows them." A specific rule ("Use 2-space indentation") does more than a loud vague one.

Tool

How does your CLAUDE.md compare?

Paste your file (or drop it in) and see where it sits against the 6,688 public files. It is measured with the same rules as the study, in your browser. Nothing is uploaded.

Open a file
Your results show here: length percentile, which common sections you have, and anything worth a second look.
Template

A CLAUDE.md template built from the data

We took the sections that files in repos with 100+ stars use most and put them in the order they usually appear. Each heading below shows how many of those files have it. The template is short on purpose: fill in what is true for your repo, delete the rest, and you will land well under Anthropic's 200-line target.

  1. Project overview58% of 100+ star repos
  2. Commands (build, run, dev)72% of 100+ star repos
  3. Architecture61% of 100+ star repos
  4. Code style and conventions63% of 100+ star repos
  5. Testing49% of 100+ star repos
  6. Git, commits and PRs29% of 100+ star repos
  7. Rules and constraints39% of 100+ star repos
  8. Gotchas and troubleshooting22% of 100+ star repos
# CLAUDE.md

<!-- Template from the State of CLAUDE.md study (locul.ai/research/state-of-claude-md). Replace every <...>, delete what does not apply, and delete this line. Aim to stay under 200 lines. -->

## Project overview

<One or two sentences: what this repo is, who uses it, and the main stack.>
Example: "REST API and admin dashboard for <product>. TypeScript, Next.js 15, Postgres via Prisma."

## Commands

Swap in your own tools; keep the exact flags.

```bash
pnpm install                          # install dependencies
pnpm dev                              # dev server on http://localhost:3000
pnpm test                             # full test suite
pnpm test -- path/to/file.test.ts     # one test file
pnpm lint                             # lint (must pass before a PR)
pnpm typecheck                        # type check
pnpm build                            # production build
```

## Architecture

- `<dir>/`: <what lives here and why>
- `<dir>/`: <what lives here and why>
- <How a request or job flows through the system, in one or two lines.>
- <Where config and environment variables are read.>

## Code style

- <The conventions a linter does not enforce: naming, file layout, error handling.>
- <Preferred patterns, with one real example path to copy from: see `<path/to/good/example>`.>
- <Anything Claude tends to get wrong here, stated as a concrete rule.>

## Testing

- Run `pnpm test` before saying a change is done. Run a single file while iterating.
- New code gets a test next to it in `<test dir or naming pattern>`.
- <Test data, fixtures or services the tests need, and how to start them.>

## Git and pull requests

- Branch from `<main branch>`; never push to it directly.
- Commit messages: <format, e.g. Conventional Commits: feat:, fix:, chore:>.
- <PR checklist: tests pass, lint clean, screenshots for UI changes.>

## Rules

- Never commit secrets. Keys live in `<.env.local or secret manager>`, which is gitignored.
- Do not edit `<generated or vendored paths>`; regenerate them with `<command>`.
- Ask before adding a dependency or changing the database schema.

## Gotchas

- <The non-obvious thing that costs a new contributor an hour.>
- <Known flaky test, required service, or OS-specific step.>
Raw file
Examples

Real CLAUDE.md examples worth reading

The most-starred repositories in the sample whose CLAUDE.md has real content and no /init boilerplate. Each card shows the file's length when we measured it and the first sections it covers. Links open the current version on GitHub.

ankitects/anki31,840 stars · 123 linesRustSetup and environmentAgent workflowProject overviewmantinedev/mantine31,806 stars · 81 linesTypeScriptDocs and referencesCode style and conventionsTestingmindfold-ai/Trellis14,882 stars · 109 linesTypeScriptRules and constraintsDocs and referencesCommandscrossoverJie/cim9,488 stars · 46 linesJavaSetup and environmentCommandsTestingsecurego/gosec8,962 stars · 51 linesGoSecurity and secretsCommandsTestingiflytek/astron-agent8,879 stars · 103 linesJavaProject overviewProject structure / layoutGotchas and troubleshootingredpanda-data/connect8,778 stars · 174 linesGoSetup and environmentCommandsProject overviewevrone/go-clean-template7,689 stars · 259 linesGoCommandsRules and constraintsTech stack and dependenciesjrnl-org/jrnl7,334 stars · 108 linesPythonProject overviewSetup and environmentCommands
The CLAUDE.md file, by Anthropic's Claude channel (3 min)

If you have not written one yet, Anthropic's three-minute video shows where the file lives and how /init drafts it. Then trim what /init writes: in our data, 37% of files never removed its opening line. To check your own file against this study, use the checker above; for a line-by-line audit, the CLAUDE.md Analyzer. If the context your agent needs lives in notes and docs rather than the repo, Locul can serve that to Claude Code as memory over MCP, which keeps CLAUDE.md for the repo-specific rules.

Method

How was this measured?

What we collected

GitHub's code search reported about 586,432 files named CLAUDE.md at the root of public, non-fork repositories on 8 October 2026 (query filename:CLAUDE.md path:/). The search API returns at most 1,000 results per query, so we split the population into 14 file-size ranges, read GitHub's count for each, and took a quota from each range in proportion to its share. That keeps the sample's size distribution the same as the population's. We downloaded each file at the exact commit GitHub had indexed, then read repository metadata, the file's commit history on the default branch (up to 50 commits) and the presence of other agent files through the GitHub GraphQL API.

The result is 6,967 repositories, one root CLAUDE.md each. 6,688 have real content; the rest are pointer files (a file under 400 characters that hands off to AGENTS.md, README.md or an @import) or have fewer than 20 words. Length, section and tone numbers use the 6,688 files with content; sibling-file, folder and history numbers use all 6,967. A comparison sample of 2,484 root AGENTS.md files was drawn the same way.

How we measured

  • Lines are counted as written, blank lines included. Tokens are estimated at 4 characters per token; exact counts vary by model.
  • Sections come from Markdown headings outside code blocks, matched to 16 categories by keyword (for example, "Build and test commands" counts for both commands and testing).
  • Commands are tools at the start of a line in a shell code block, or at the start of an inline code span with arguments (`pnpm test`).
  • Mentions match anywhere in the file. Shouted words count capitalised IMPORTANT, MUST, NEVER, ALWAYS, CRITICAL and DO NOT outside code blocks.
  • @imports are @path references to a file with an extension such as .md or .json, outside code blocks.

The checker on this page runs the same rules in JavaScript. We tested it against the Python pipeline on 1,000 random files from the sample, and every measured field matched on all 1,000.

What this does not tell you

  • GitHub orders results by its own relevance, not at random, so within each size range the sample leans towards what GitHub ranks first. The search index also lags and skips some repositories.
  • Only root-level CLAUDE.md files are counted. Files in subfolders, .claude/CLAUDE.md, personal ~/.claude/CLAUDE.md files and private repositories are not.
  • Keyword matching misses headings phrased in unusual ways, and 7.5% of files are written mostly in a non-Latin script, which the keyword rules mostly miss.
  • Nothing here measures whether a file makes Claude better at its job. For that, see the ETH Zurich study below.

Earlier studies

StudySampleFocus
Agent READMEs, Chatlatanagulchai et al., 20252,303 context files from 1,925 repos, including 922 CLAUDE.mdContent categories, words, edits
Agentic coding manifests, Chatlatanagulchai et al., 2025253 CLAUDE.md files from 242 reposStructure and content
Context engineering in open source, Mohsenimofidi et al., 2025466 projectsAdoption of AGENTS.md
Evaluating AGENTS.md, Gloaguen et al., 2026Agent runs on SWE-bench Lite and 138 new tasksWhether context files help agents
GitHub Blog, Nigh, 20252,500+ agents.md filesPractitioner lessons
This study, 20266,967 CLAUDE.md + 2,484 AGENTS.md, sampled by sizeLength in lines, sections, commands, imports, sibling files, .claude/ folder, edit history
FAQ

Questions people ask about CLAUDE.md

How long is too long for a CLAUDE.md?

Anthropic's own line is the best answer we have: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." In our sample the median file is 100 lines and 22% of files are over 200. Claude Code only refuses a file outright when it is over 4 MiB, so length is a quality problem long before it is a hard limit.

How many lines should a CLAUDE.md have?

Most public files land between 59 and 180 lines, with a median of 100. Files in repositories with 100 or more stars have a median of 138 lines. A file that lists the commands, the layout, the conventions a linter cannot enforce and the few rules that matter usually fits well under 200 lines; the template on this page is under 70.

What should go into a CLAUDE.md?

What Claude cannot work out from the code. In public files the most common headings cover commands (64% of files), architecture (56%), a project overview (50%) and code style (50%). Testing has its own heading in 33% and security in only 12%. Exact commands ("pnpm test -- path") beat descriptions ("we use Jest").

Is CLAUDE.md the same as AGENTS.md?

They do the same job for different tools. CLAUDE.md is the file Claude Code reads; AGENTS.md is the shared format used by Codex, Cursor, Copilot and others. Anthropic's docs say "Claude Code can read AGENTS.md as your project instructions". In our sample 21% of repos with a CLAUDE.md also have an AGENTS.md, and 3.4% of CLAUDE.md files are pointers that hand off to another file, usually AGENTS.md.

Is CLAUDE.md really useful?

For the right content, yes. A 2026 ETH Zurich study found that "context files are useful for specifying non-standard coding practices" but that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average." The lesson for your file: keep what is specific to your repo (commands, odd conventions, traps) and cut the generic overview.

Does Claude always read CLAUDE.md?

Claude Code loads the CLAUDE.md files in the directory tree above where you start it at launch, and files in subdirectories when it works there. Anthropic is clear that "Claude treats them as context, not enforced configuration", so a rule in the file is a strong hint, not a guarantee. Shorter, specific rules are followed more reliably.

Where should CLAUDE.md live?

For a project, at the repository root as ./CLAUDE.md or ./.claude/CLAUDE.md, committed so the whole team shares it. Personal rules for every project go in ~/.claude/CLAUDE.md. This study only measures root-level CLAUDE.md files, the most common place.

What is the difference between CLAUDE.md and CLAUDE.local.md?

CLAUDE.md is shared through version control. CLAUDE.local.md holds your private notes for one project; Anthropic's docs say: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root." Because it is meant to stay out of git, public data cannot measure it. Its settings cousin leaks more often: 7% of repos in our sample commit .claude/settings.local.json, a file meant to stay personal.

Use the data

Download or cite this study

The data is free to reuse under CC BY 4.0. Link back to this page so readers find the method.

Cite it

Khalid, J. (2026). The State of CLAUDE.md: what 6,967 public CLAUDE.md files contain. Data collected 8 October 2026. Locul. https://locul.ai/research/state-of-claude-md/

Download

The CSV holds measurements only, not file contents. Each row links to the public file on GitHub.

Related
ToolCLAUDE.md Analyzer: score and clean up your file GuideCLAUDE.md best practices: keeping your AI setup from going stale ExplainerClaude.md file: what it is and why every project needs one How-toMultiple Claude.md files: how to structure a monorepo How-toAuto-generating a Claude.md file for any codebase ResearchAI memory and context limits by plan