What goes in a CLAUDE.md: 2,536 files counted
About a quarter of root CLAUDE.md files hold no instructions of their own. Of 1,333 CLAUDE.md files at the root of public GitHub repositories, 132 are symlinks and 190 do little more than import another file, almost always AGENTS.md: 24.2% in all. Of the 1,011 written for Claude, 24.4% run past the 200 lines Claude Code's docs set as a target, and 41.4% list a test or check command.
| The root CLAUDE.md | Files | Share |
|---|---|---|
| A symlink to another file | 132 | 9.9% |
| Imports another file and adds little else | 190 | 14.3% |
| Written for Claude | 1,011 | 75.8% |
| The root files written for Claude | Files | Share |
|---|---|---|
| Uses headings and bullets | 893 | 88.3% |
| Lists a command to run | 618 | 61.1% |
| Lists a test or check command | 419 | 41.4% |
| Runs past 200 lines | 247 | 24.4% |
| Has a build or setup heading | 393 | 38.9% |
| Has a testing heading | 308 | 30.5% |
| Has a security heading | 89 | 8.8% |
| Imports AGENTS.md and adds its own | 71 | 7.0% |
What Claude Code's docs ask for
Claude Code reads a project's CLAUDE.md, at ./CLAUDE.md or ./.claude/CLAUDE.md, at the start of every session. Its memory documentation says what belongs there: facts Claude should hold in every session, such as build commands, conventions and project layout, with multi-step procedures moved to a skill. It sets a size target of under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence, and it asks for related instructions grouped under markdown headers and bullets. A CLAUDE.md can import other files with @path/to/import; imported files load at launch with it, so an import organizes a long file without shortening what Claude reads. CLAUDE.md files in subfolders load when Claude works on files there, not at launch.
24.2% only point elsewhere
132 root CLAUDE.md files (9.9%) are symlinks, 130 of them to an AGENTS.md. Another 190 (14.3%) import a file and add at most three short lines of their own, such as a title; 183 of them import AGENTS.md. Together, 322 root files hand Claude another file's instructions rather than their own. A further 71 files import AGENTS.md and then add instructions for Claude below it, the setup Claude Code's docs show for sharing one file with other coding tools. Since version 2.1.277, Claude Code reads AGENTS.md itself when a project has no CLAUDE.md, and the docs still point to the import for sessions where it cannot.
The import keeps the file short on disk, not in context: what Claude reads at launch is the AGENTS.md behind it, which our count of AGENTS.md files describes. Our earlier count looked only at folders that hold both files; this one takes every root CLAUDE.md, whether or not an AGENTS.md sits beside it.
The 200-line target
The 1,011 root files written for Claude run a median of 88 lines, and one in ten runs past 366. 247 (24.4%) are longer than the 200 lines the docs target, and 54 (5.3%) are longer than 500. Counting the symlinks and pointers, the median root CLAUDE.md is 52 lines, which says more about how many files are pointers than about how long projects write. Nested files, the 1,203 CLAUDE.md files inside subfolders, which load only when Claude works there, run a median of 26 lines.
What the written files hold
Structure is the norm: 893 written files (88.3%) use both headings and bullets, and 37 have no heading at all. Commands are less common. 618 (61.1%) list at least one command, in a code block or inline, and 419 (41.4%) list a test runner, a linter, a type checker or a validation step, the command that lets Claude confirm a change works before it hands the work back. By heading, build or setup instructions are the most common topic, in 38.9% of written files, then an overview (32.5%), testing (30.5%), code style (27.1%) and commit or pull request guidelines (25.7%); security is the rarest, in 8.8%.
These are the same rules our AGENTS.md count used a day earlier, where 68.3% of root AGENTS.md files listed a command and 48.2% a check. That count kept AGENTS.md files that are symlinks, which list nothing, so the gap is if anything wider than those numbers show.
Check your own CLAUDE.md
wc -l gives the line count to hold against the 200-line target. The grep prints each line with an @ that starts a path: every import our count includes, and some it would not, because grep cannot tell code from prose. Claude Code skips an @ inside backticks or a code block, and the docs suggest backticks for a path you mean to mention without importing. This is the output on a scratch file that imports AGENTS.md on line 3 and mentions a path in backticks on line 8:
$ wc -l < CLAUDE.md
8
$ grep -nE '(^|[^[:alnum:]_/.@])@[^[:space:]]+' CLAUDE.md
3:@AGENTS.md
8:- Write a path in backticks, like `@docs/old.md`, to keep it from loading.Line 3 is an import; line 8 is not, because the path sits in backticks. If the file is long, the docs' answer is to move instructions that matter for one part of the codebase into path-scoped rules under .claude/rules/, which load only when Claude works on matching files. Run /context in a session to see which memory files loaded. Real CLAUDE.md files from other projects are on the CLAUDE.md page, most starred first. To start a new one from a file that passes every check the registry runs, use the CLAUDE.md starter on mdpantry, which says what to change in it.
How we counted
The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content. We took every file named CLAUDE.md it holds, 2,536 in 1,437 repositories, read each one's latest stored version, and checked its bytes against its hash. Root files are the 1,284 at a repository's root and the 49 at .claude/CLAUDE.md, 1,333 files in 1,320 repositories, since 13 repositories have both; the other 1,203 are nested. A symlink is a file whose whole content, trimmed, is one path ending in a file name, which is how GitHub serves a symlink; the AGENTS.md and CLAUDE.md count used the same test, but only for a path ending in the other file's name. An import is an @ at the start of a line or after a space, outside code spans and fenced code, followed by a path that runs to the next space, as the docs say, with a space kept when a backslash escapes it. The path must name a file: start with ./, ../, ~/ or /, end in a file extension, or be the bare @README of the docs' own example. That leaves out email addresses, handles, packages such as @types/node, and a path followed by a comma or a period, which then names no file. A pointer is a file with an import and at most three other non-blank lines and 200 characters of its own, a line inside fenced code counting whole. Every other root file counts as written for Claude, including a few that name AGENTS.md in a sentence instead of importing it. Headings, the six topics, commands and test or check commands are matched exactly as in the AGENTS.md count, whose method section lists the words; the script imports that study's rules. A bullet is a line outside fenced code that starts with a dash, an asterisk, a plus sign or a number followed by a period or parenthesis. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.
Sources
Read next
- Every CLAUDE.md in the registry, most starred first
- AGENTS.md, CLAUDE.md, SKILL.md and Cursor rules: which file does what
- What goes in an AGENTS.md: 4,687 files counted
Try it
npx modelranch add anthropics/skills/pdf