What should go in a CLAUDE.md file

There are two answers and they do not agree. Anthropic’s documentation says to keep a CLAUDE.md to build commands, conventions, project layout, “always do X” rules. The 216 root CLAUDE.md files in the RuleStack corpus mostly do something else: 82.4% tell the agent how to behave, and only 39.4% name a build command. This page ranks all 20 sections by how many real files carry each one, says what to write in each, and marks the three places practice and documentation part company.

216 root CLAUDE.md files countedmedian 730 wordsmedian 13 headings79.2% carry a runnable command

Measured — counted from real repositories, nightlyAsserted — read from the vendor docs, dated

The short answer

A CLAUDE.md should contain the things you would otherwise retype into the chat every session: the commands that build, test and lint the project; the conventions a linter cannot enforce; the rules that begin with never; and the handful of architectural facts an agent cannot read off the directory tree. Anthropic states the test for inclusion directly — add something when Claude makes the same mistake a second time, or when you type the same correction or clarification into chat that you typed last session. Everything else is context you pay for on every request. In the corpus, the median root CLAUDE.md runs 730 words across 13 headings and covers 6 of the 20 sections below, which is a reasonable target to write against. Quotations read from Claude Code — How Claude remembers your project 2026-08-05

The 20 sections, ranked by how many files ship them

Share is the percentage of the 216 CLAUDE.md files at a repository root that carry each section, detected from the file’s own headings and prose by the classifier in lib/classify.mjs and re-counted on every corpus run. Nested per-package CLAUDE.md files are excluded: they were never trying to be a complete instruction file, and counting them alongside the root one would inflate the denominator with documents that answer a different question. The right-hand column is editorial — it is the only hand-written thing on this page.

Section coverage across 216 root CLAUDE.md files, counted from the corpus
Section	Share of files	Files	What to write in it
Agent behaviouragent-behaviour	82.4%	178 of 216	How the agent should work before it touches anything: ask before wide refactors, do not invent files that were not requested, stop and report rather than guessing at an ambiguous instruction. This is the section that makes a CLAUDE.md a CLAUDE.md rather than a README.
Teststest	59.7%	129 of 216	The exact command that runs the tests, including the filter syntax for a single file — `npm run test -- src/api/handlers.test.ts`, not "run the tests". An agent that has to guess a filter flag runs the whole suite every time.
Code stylecode-style	58.3%	126 of 216	The conventions a linter cannot catch: which of two equivalent patterns this codebase prefers, and the one it has already rejected. Anything a formatter enforces belongs in the formatter config, not here.
Architecturearchitecture	52.8%	114 of 216	Only the parts an agent cannot read off the tree — why the worker and the main thread are split, which module owns a decision. A directory listing is derivable from the codebase and is the first thing Anthropic's own trim check removes.
Hard prohibitionsdo-not	48.6%	105 of 216	Hard prohibitions, written as commands with objects: never commit to main, never edit files under `generated/`, never add a dependency without asking. The highest-value lines in the file and the ones most often left out.
Git, commits & PRsgit-pr	40.7%	88 of 216	Commit message format, branch naming, and what has to pass before a pull request is opened. Cheap to write and it removes an entire category of correction from every session.
Buildbuild	39.4%	85 of 216	The build command and the package manager it belongs to — `pnpm -F @app/web build` beats `build the package`, because the workspace flag is the part an agent gets wrong.
Lint & formatlint-format	37.5%	81 of 216	The lint and format commands, plus whether they are expected to pass before a commit. Name the tool: an agent that knows the project runs Biome will not reach for Prettier.
Setup & installsetup	36.6%	79 of 216	What has to exist before any other command works — the runtime version, the env file, the one-time install. Short, and only the steps that are not obvious from the manifest.
Documentationdocs	24.1%	52 of 216	Which documents have to be updated alongside a change — the changelog, a README table, an API reference — because this is work an agent will otherwise skip every time.
Deploy & releasedeployment	23.6%	51 of 216	How a change reaches production and, more usefully, the circumstances in which the agent must not deploy at all.
Testing strategytesting-strategy	21.3%	46 of 216	Whether a failing test comes first, what may be mocked, and what counts as adequate cover. Distinct from the test command: this is the rule, that is the invocation.
Typestypes	20.8%	45 of 216	The type rules that are enforced socially rather than by the compiler — no `any` at module boundaries, where the shared types live, whether strict mode is non-negotiable.
Securitysecurity	17.6%	38 of 216	What must never be logged, committed or printed, and where secrets are actually read from. Worth writing even in a project with no secrets, because the rule is about what the agent does when it finds one.
Dependenciesdependencies	15.7%	34 of 216	Whether new dependencies are allowed at all, and who decides. The default answer in most repositories is "ask first", and almost nobody writes it down.
APIs & contractsapi	13.4%	29 of 216	The response shape, the error format, and where handlers live — the contract an agent has to match rather than reinvent per endpoint.
UI & componentsui	13%	28 of 216	Which component library and design tokens are in use, and the accessibility floor a new component has to clear.
Database & migrationsdatabase	12.5%	27 of 216	How migrations are generated and applied, and the standing rule that an already-applied migration is never edited.
Performanceperformance	10.2%	22 of 216	The specific hot paths where a naive change is expensive, and what to measure before claiming an improvement.
Monorepomonorepo	6%	13 of 216	Which package a change belongs in, and how to run a command scoped to one workspace. Also the point at which a nested CLAUDE.md becomes the better answer.

How long should a CLAUDE.md file be?

Anthropic’s stated target is under 200 lines per CLAUDE.md file, on the grounds that longer files consume more context and reduce adherence. The corpus measures words rather than lines, so the two are not directly comparable, but the distribution is informative either way: the median root CLAUDE.md is 730 words, while the 90th percentile is 2,917 — more than four times the median. Length is not a one-off cost. A CLAUDE.md is loaded into context at the start of every session and re-injected after compaction, so a thousand words of directory listing is a bill you pay on every request for as long as the file exists. If a file is growing past the target, the documented fix is not to trim prose but to move the parts that only matter sometimes into .claude/rules/ with a paths: field, so they load only when Claude opens a matching file. Size guidance read from the Claude Code memory documentation 2026-08-05

Does a CLAUDE.md need build and test commands?

Yes, and this is the largest gap between what the documentation asks for and what real files contain. Anthropic puts build commands first in its list of what to keep — build commands, conventions, project layout, “always do X” rules — yet only 39.4% of the 216 root CLAUDE.md files in the corpus carry a build section at all, and 59.7% carry a test section. The commands are worth writing at the level of detail an agent cannot infer: the package-manager prefix, the workspace filter, and the syntax for running one test file rather than the suite. A useful sanity check is that 79.2% of these files contain at least one runnable command line somewhere in them — so most authors do write commands; many just scatter them through prose instead of putting them under a heading where an agent scanning structure will find them.

What should not go in a CLAUDE.md file?

Anything Claude can derive by reading the codebase, and anything that only matters in one corner of it. Anthropic’s own /doctor trim check is explicit about the first category: it cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews and keeps pitfalls, rationale, and conventions that differ from tool defaults. That is worth sitting with, because 52.8% of root CLAUDE.md files in the corpus ship an architecture section — the second-most-common substantive section, and the one the vendor’s own tooling is most likely to delete. The distinction is not “architecture is useless”: it is that a directory listing is derivable and why the worker and the main thread are split is not. The second category is multi-step procedures and per-area rules, which the documentation routes to a skill or a path-scoped rule instead. Also leave out anything personal — sandbox URLs, preferred test data — which belongs in a gitignored CLAUDE.local.md. Trim-check behaviour read from the Claude Code memory documentation 2026-08-05

Which sections do most CLAUDE.md files skip?

Hard prohibitions are the expensive omission: only 48.6% of root CLAUDE.md files in the corpus carry a section of explicit never do this rules, despite that being the category with the clearest payoff per line written. Security is thinner still at 17.6%. Below a quarter coverage the corpus finds Documentation, Deploy & release, Testing strategy, Types, Security, Dependencies, APIs & contracts, UI & components, Database & migrations, Performance and Monorepo — some of which are genuinely project-specific and correctly absent, and some of which, like dependency policy, are standing rules almost every team enforces socially and almost nobody writes down. If you are looking for the highest-value paragraph to add to an existing file, it is a prohibition, phrased as a command with an object: never edit files under generated/ rather than be careful with generated code.

Is a CLAUDE.md different from an AGENTS.md in practice?

Barely, once you look at the files rather than the specifications. On the same root-only basis, the median CLAUDE.md runs 730 words against 723 for AGENTS.md, 79.2% carry a runnable command against 76.8%, and both cover a median of 6 sections; the clearest difference is structural, at 13 median headings against 11. Two files of near-identical shape, written for different readers. The real difference is capability, not content: CLAUDE.md supports @path imports and a user-level file at ~/.claude/CLAUDE.md, and it is read by one tool, while AGENTS.md is read by more than twenty and supports neither. Anthropic’s documentation is unambiguous that they are not interchangeable — Claude Code reads CLAUDE.md, not AGENTS.md — and the documented way to ship both without duplicating a word is a CLAUDE.md whose first line is @AGENTS.md, with any Claude-specific rules underneath. Capability claims read from the Claude Code memory documentation 2026-08-05 The full capability matrix and the nightly adoption counts for both are on AGENTS.md vs CLAUDE.md.

Where does the CLAUDE.md file go?

A project CLAUDE.md goes at the repository root, either as ./CLAUDE.md or ./.claude/CLAUDE.md, and is committed so the team shares it. Three other scopes exist and load in order from broadest to most specific: a managed policy file installed by IT, a personal ~/.claude/CLAUDE.md that applies to every project on your machine, and a gitignored ./CLAUDE.local.md for things like sandbox URLs. Files above the working directory load in full at launch; files in subdirectories load on demand when Claude reads a file in that subdirectory, which is what makes a nested CLAUDE.md the right answer for a monorepo package — though only 6% of root files in the corpus say anything about monorepo scoping at all. Scope table read from the Claude Code memory documentation 2026-08-05

Should instructions go in CLAUDE.md or .claude/rules?

Put an instruction in CLAUDE.md when it applies to every session, and in .claude/rules/ when it only applies to some files. Rules are markdown files discovered recursively under that directory, and a rule carrying a YAML paths: field of glob patterns — src/api/**/*.ts, src/**/*.{ts,tsx} — loads only when Claude reads a matching file, while a rule without one loads unconditionally. That is the escape hatch for the length problem, and it is the reason the RuleStack canon still records CLAUDE.md itself as having no glob targeting: the globs live in a different artifact. Note that @path imports do not solve the same problem — the documentation is direct that splitting into imports helps organization but doesn’t reduce context, since imported files load at launch. Rule and import behaviour read from the Claude Code memory documentation 2026-08-05

Where can I read real CLAUDE.md files?

Every file counted on this page is indexed and readable. The full CLAUDE.md index, ranked by quality score is the place to start; each entry links to the file at the commit on GitHub and breaks out its sections, extracted commands and score. To see how a specific section is handled in practice, the section names in the table above are links — they filter the index to the files that carry that section. For the AGENTS.md equivalent of this page, see the best AGENTS.md examples, and for what the two formats can and cannot do, the CLAUDE.md format page carries the capability canon with the date each row was verified.