What belongs in a CLAUDE.md, and what each rule in mine cost to learn.
A CLAUDE.md is the file an assistant reads before it touches your repo. Most advice about it is somebody's opinion. This page is 40 of them in daily use here, 643,173 bytes of instructions written since 2026-03-09, plus the rules about the file itself, each with the failure that produced it, dated where the file dates it.
First, the mechanics
Four scopes load, broadest first, and all of them are concatenated rather than overriding each other. Read 2026-11-16 from the published documentation:
- managed policy
user file at ~/.claude/CLAUDE.mdproject file at ./CLAUDE.md or ./.claude/CLAUDE.mdlocal file at ./CLAUDE.local.md
A file can pull in others with an at-path import, up to 4 hops deep, and the guidance is to keep each file under 200 lines per file, because a longer one eats context and gets followed less. It also reads AGENTS.md in place of CLAUDE.md, and .claude/rules/ for rules scoped to file globs. Source, read2026-11-16: https://code.claude.com/docs/en/memory
What sections a real corpus actually carries
Every section heading that appears in three or more of the 40 files, counted, not curated. Headings naming a product are left out of this list.
The rules about the file itself, with the failure behind each
Each of these is anchored to a line in the file it came from. Remeasuring refuses a rule whose anchor has gone, and for the project file, which lives beside this site's code, every deploy checks the anchors too, so a rule that file stops holding stops the deploy instead of sitting here. The wording below is written for publication, because the files themselves carry paths, repositories and product names that stay private. Where the rule's own entry carries a date, that date is the file's, not a label added here.
Give every rule one home, and say which home by what the rule binds.
Rules that live in two places drift, and the stale half is read first.
A size limit belongs in a program that fails the file, not in a sentence inside it.
A budget written as prose is argued with; a budget written as a check is met.
A list an enforcement check reads lives in a data file beside it, never hardcoded.
A hardcoded list is edited by whoever is nearest, and the file stops agreeing with the check.
Correcting a fact means correcting every copy of it in the same pass.
The intro of this file told readers to deploy one way while its own deploy section forbade that exact path.
Name the one working copy, and name the stale ones so a reader cannot pick the wrong tree.
One wrong pointer in an abandoned copy sent a whole audit through the wrong codebase.
A verify command written into the file is itself a claim: run it before you write it down.
Two versions of one check sat in this file returning zero on a healthy page, claiming coverage nobody had.
Write down which component owns a number, so the next session does not build a second one.
Two scanners for one number disagreed by 927,031 lines, and the page would have shown whichever ran last.
When a thing broke twice in opposite directions, write the shape down, not the last fix.
Two fixes in opposite directions, because the file recorded the symptom instead of the design.
Record a reversal with its date, or the next session helpfully reverses it back.
A parked product was put back in front of visitors by a session restoring what the file still called correct.
Take the file, not the advice
A starter CLAUDE.md built from this corpus: the recurring sections that generalise beyond one project, in order of how many files keep them, with each rule above written in as a line to delete when it stops applying to you. The sections tied to one project are counted in the table above and left out of the file.
Download the starter CLAUDE.md