Where Claude Code loads CLAUDE.md, what 100 public copies actually contain, and a template built from the headings that repeat.
On this page
The short answer
A Claude MD file is CLAUDE.md in the project root, or ~/.claude/CLAUDE.md when the notes are yours alone. In 100 public root files collected on October 27, 2026, the median length was 85.5 lines. The headings that showed up most, after an H1 titled CLAUDE.md, were Architecture, Project overview, and Testing.
Where the file loads
Claude Code reads CLAUDE.md at the start of a session. The memory docs, checked October 27, 2026, list the launch files from the broadest scope to the most specific. They are concatenated. The file closer to the folder where you started Claude is read last.
Four places load when the session starts.
- Managed policy. macOS uses
/Library/Application Support/ClaudeCode/CLAUDE.md. Linux and WSL use/etc/claude-code/CLAUDE.md. Windows usesC:\Program Files\ClaudeCode\CLAUDE.md. The docs say a developer can exclude other CLAUDE.md files, and cannot exclude this one. - User.
~/.claude/CLAUDE.mdis yours. It loads for every project. - Project.
./CLAUDE.mdor./.claude/CLAUDE.mdis the copy you commit. Ancestor copies, in folders above the working directory, load at launch too. Order is from the filesystem root downward. - Local.
./CLAUDE.local.mdis appended afterCLAUDE.mdin the same directory. The docs say to add it to.gitignore.
A CLAUDE.md in a subfolder under the working directory stays out of the launch set. Claude Code loads it when Claude reads, writes, or edits another file in that subfolder. CLAUDE.local.md beside it loads the same way.
The docs also read AGENTS.md when you have no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it. If one of those three is present, the default is to read the CLAUDE.md files and leave AGENTS.md out. Direct reading of AGENTS.md needs Claude Code v2.1.277 or later, on that same page.
/init can draft a starting file from the repo. I did not run it. The template further down comes from the 100-file count, not from /init.
Rules in .claude/rules/ are a separate mechanism. A rule with no paths field loads at launch, with the same priority as .claude/CLAUDE.md. A rule with paths loads when Claude works on a matching file.
A rule for every session belongs in this file. A worker with its own window and its own tools is a different file. Claude Code subagents is that markdown file, and when a skill or the chat you already have is the better fit. A command you type as /name is a third file. Claude Code slash commands is where that file lives, now that a custom command is a skill.
What 100 public files contain
On October 27, 2026 I took 100 CLAUDE.md files from the root of public GitHub repositories. The method, the definitions, and the row-level table are in the next section. The picture is short.
The median file is 85.5 lines and 587 words. Sorted by length, the 50th and 51st files are 84 and 87 lines. Sorted by words, they are 583 and 591 words. The mean is 149.04 lines, because a few files are very long. The longest in the sample is arolang/aro at 1,338 lines. The highest star count in the sample is securego/gosec at 8,988 stars. That is the max in these 100 files, not a claim about every public file.
-
85.5
Median lines in 100 root files
Survey CSV -
587
Median words, same 100 files
Survey CSV -
76
Files at or under 200 lines
Survey CSV -
12
Files with an @ import token
Survey CSV
The memory docs say to target under 200 lines per file, because a longer file spends more context and Claude follows it less reliably. That 200 is their target. In this sample, 76 files are at or under 200 lines and 24 are over. Five files are 401 lines or longer.
Fifty files have an H1 whose text is exactly CLAUDE.md. Nine files have no ATX heading at all. Eighty-five have at least one H2. Sixty-five contain a fenced code block.
| Heading | Files |
|---|---|
| CLAUDE.md, as an H1 | 50 |
| Architecture | 34 |
| Project overview | 29 |
| Testing | 18 |
| Commands | 12 |
| Project structure | 11 |
| Build commands | 8 |
| Code style | 8 |
| Development workflow | 7 |
| Release process | 7 |
Punctuation is stripped before those names are grouped, and the comparison is case-insensitive. Architecture and architecture count as one heading. Project architecture does not, because the whole heading is different. Build & Test lands in its own group, build test, which is in 3 files and is not in the table.
A second pass tags a file when any heading matches a word list. The lists overlap, so a file can count twice. Architecture words: 67 files. Command words: 66. Testing: 42. Code style: 39. Rules: 38. Setup: 20. Git: 12. Security: 8. The lists are in the survey script. The table above is the stricter count, and it is the one the template uses.
Imports are uncommon. Twelve files contain at least one @ token that the script treats as a file import. That is 24 tokens. Six of the 24 are AGENTS.md. Zero lines outside a code fence start with @import. The docs syntax is @path, and a path inside backticks is left as text.
What we tested
Checked
The collection finished at 09:09:56 UTC on October 27, 2026. The endpoint was GET https://api.github.com/search/code. The query that produced the sample was filename:CLAUDE.md. GitHub reported total_count 942,080 and incomplete_results false. That total counts every indexed hit with that filename, including files that are not at the repository root. I did not download 942,080 files.
I read page 1 and page 2, 100 hits a page, in GitHub’s default best-match order. Across those 200 hits, 164 unique repositories had path exactly CLAUDE.md. I downloaded the first 100 of those, in search order, from the git blob URL on the search hit. Every download returned UTF-8 text under 512 KiB. The excluded list is empty. The repository API, called for each of the 100, reported fork: false and archived: false for all of them.
A query tried first, filename:CLAUDE.md stars:>=100, came back with total_count 0, so it is not the sample. The star counts below show what that zero cannot mean. The sample includes securego/gosec at 8,988 stars. The median repository in the sample has 30 stars. The 50th and 51st, sorted by stars, are both 30. Twenty-four of the 100 have at least 100 stars. The minimum is 2.
Lines are newline-separated rows. A trailing newline does not add an empty row. Words are whitespace-separated tokens in the raw file, code fences included. The median of an even count is the average of the two middle values. A percentile is the nearest rank: sort, take ceil(p / 100 * n), and read that value. Headings are ATX headings outside fenced code blocks. An import token is an @ path outside fences and inline code. It has to start with ~/, ./, ../, /, or \, or end in md, mdx, json, yml, yaml, toml, or txt, or be exactly README, CLAUDE.md, AGENTS.md, or package.json. An npm name such as @scope/package does not count.
The script is scripts/research/claude-md-survey/survey.mjs. Per-file rows are in the survey CSV. A rerun will not match these rows. GitHub’s ranking moves, and star counts move.
| Measure | Result |
|---|---|
| Files kept | 100 |
| Lines, minimum / p25 / median / p75 / maximum | 1 / 38 / 85.5 / 185 / 1,338 |
| Words, minimum / p25 / median / p75 / maximum | 6 / 317 / 587 / 1,370 / 9,378 |
| Mean lines / mean words | 149.04 / 1,121.26 |
| Line bands: 1 to 25, 26 to 50, 51 to 100, 101 to 200, 201 to 400, 401 or more | 18, 13, 27, 18, 19, 5 |
| Files at or under 200 lines / over 200 | 76 / 24 |
| Files with an H1 / with an H2 / with no heading / with a code fence | 89 / 85 / 9 / 65 |
| Files with an import token / import tokens / lines starting with @import | 12 / 24 / 0 |
| Stars, minimum / median / p75 / maximum | 2 / 30 / 86 / 8,988 |
| Repositories with at least 100 stars | 24 |
p25 of the star counts is 16. The sum of stars is 32,382, and the mean is 323.82. The sum of lines is 14,904. The sum of words is 112,126.
Write the file
Put the project file where a teammate will find it. Put private preferences in the user file. Then fill the headings this sample actually repeats, with commands from your repo.
Server config does not go in this file. Add an MCP server to Claude Code is the command that writes it, and the three scopes it lands in.
Add an MCP server to Claude Code One local stdio server and one remote HTTP server, added with claude mcp add, plus the three scopes. Guide-
Put CLAUDE.md in the project root.
Save shared instructions as
CLAUDE.mdor.claude/CLAUDE.md. Both are project files in the memory docs, and both are meant to be committed.Use
~/.claude/CLAUDE.mdfor habits that apply in every repo: how you like commits described, tools you always want available. UseCLAUDE.local.mdfor a sandbox URL or a test account that should stay on your machine. AddCLAUDE.local.mdto.gitignore. -
Start with the headings that show up most.
Copy the names that fit this repo, and skip the rest. From the 100 files, the headings in at least 7 files are Architecture (34), Project overview (29), Testing (18), Commands (12), Project structure (11), Build commands (8), Code style (8), Development workflow (7), and Release process (7). Release process belongs here when the repo ships releases. It is noise when it does not.
An H1 of
CLAUDE.mdwas in 50 files. It names the file. It does not tell Claude anything about the code. Prefer an H1 that says what the repo is, or skip the H1 and start with Architecture. -
Name the commands you actually run.
Write the install command, the test command, and the dev command as you would type them in a terminal. The memory docs use a concrete line, “Run
npm testbefore committing,” against a vague line, “Test your changes.” I did not count how often those two sentences appear. I counted headings. Commands is in 12 files. Build commands is in 8.If the project does not use npm, do not leave
npm testin the file. Write the command this repo actually uses. -
Keep the file near the median length.
85.5 lines is the middle of this sample. The memory docs’ own target is under 200 lines per file. 76 of these 100 files are already on that side of the line. 24 are over, including arolang/aro at 1,338 lines.
When a section is only true for one directory, the docs say to move it to a path-scoped rule under
.claude/rules/so it loads for those files and not for every session. An@pathimport does not buy that. The imported file is loaded with the CLAUDE.md that points at it. -
Add an import only when one file is not enough.
The syntax on the memory page is
@plus a path, outside backticks. Their examples are@README,@package.json, and@docs/git-instructions.md. Relative paths resolve from the file that contains the import, not from the working directory. Imports can nest four levels deep.Twelve of the 100 files had a token that matched the survey rule. Twenty-four tokens in total.
AGENTS.mdaccounted for 6 of them. Zero lines started with@import. If you want a path to stay text, wrap it in backticks.Add the import when the other file already exists. Two files in the sample are a single line. One of them, fedir/ghstat, is 6 words, the minimum. Eighteen files are 1 to 25 lines. The length chart counts the bands. It does not grade those short files.
Copy this template
The headings are the ones in at least 7 files, with Build commands folded into Commands, and Release process left out until the repo has one. The bullets are blanks. Replace them. Nothing in the template is a command measured from the 100 files.
Download the CLAUDE.md template
# CLAUDE.md
## Project overview
What this repository is, in two or three sentences.
## Architecture
The parts of the system, and which directory each one lives in.
## Project structure
- `src/` for application code
- `tests/` for tests
## Commands
Replace each line with a command you have run in this repo.
- Install dependencies
- Run the tests
- Start the dev server
## Testing
Run the test command before you finish. Keep tests offline. Do not call a paid API from a test.
## Code style
Match the file you are editing. Leave unrelated lines as they are.
## Development workflow
One change at a time. Run the test command. Say which command you ran.Add an import on its own line only when that file is real:
See @AGENTS.mdDo not put a database password, an API token, or any other secret in a file you commit. SQLite vs Postgres makes the same point for a connection string.
SQLite vs Postgres, timed on one machine 100,000 inserts, a dashboard query, and 1, 4, and 8 writers, measured locally. Keep the password out of the repo. BlogA standing instruction can point at a procedure you already wrote down. The checks for a new site are in How to get a new website indexed by Google.
How to get a new website indexed by Google The order to do it in, what each Search Console status means, and how long to wait. GuideThe per-file measurements are in the survey CSV. More on this topic lives under AI agents and tools.
FAQ
What is a Claude MD file?
A Claude MD file is CLAUDE.md, the markdown file Claude Code reads for standing instructions. A project copy goes at ./CLAUDE.md or ./.claude/CLAUDE.md. Personal instructions for every project go in ~/.claude/CLAUDE.md.
Where does Claude Code load CLAUDE.md from?
The memory docs, checked October 27, 2026, list four launch locations, broadest first: a managed policy file on the machine, then ~/.claude/CLAUDE.md, then project files from the filesystem root down to your working directory, then CLAUDE.local.md in each of those directories. A CLAUDE.md in a subdirectory loads when Claude reads a file there. The files are concatenated. A later file does not erase an earlier one.
How long should CLAUDE.md be?
In this sample of 100 public root files, the median is 85.5 lines. The 50th and 51st files, sorted by length, are 84 and 87 lines. The memory docs say to target under 200 lines per file. 76 of the 100 files are at or under 200 lines, and 24 are over.
How do you import another file into CLAUDE.md?
The memory docs use @path, outside backticks. @README and @docs/git-instructions.md are their examples. A path wrapped in backticks is not imported. In this sample, 12 files had an import token under the rule in the survey script, 24 tokens in all. Zero lines started with @import. The docs also say an import is loaded with the CLAUDE.md that points at it, so the import does not shrink the context.
Does AGENTS.md replace CLAUDE.md?
By default, Claude Code reads AGENTS.md when the working directory and the directories above it have no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. If one of those exists, it reads the CLAUDE.md files and leaves AGENTS.md out. The memory docs say direct AGENTS.md reading needs Claude Code v2.1.277 or later.
Should I commit CLAUDE.md?
Commit ./CLAUDE.md or ./.claude/CLAUDE.md when the instructions are for anyone who clones the repo. Keep secrets out of it. Keep notes that only apply on your machine in CLAUDE.local.md, and add that file to .gitignore. MCP server config is a separate file, covered in Add an MCP server to Claude Code.