Project instruction files, measured

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.

40
Instruction files
Distinct files, one per text. 21 duplicate copies and abandoned clones left out.
92
Lines, the middle file
The longest runs 1,369. 8 sit above the 200 lines the documentation targets.
616
Lines with a date or a measurement
A date, or a word such as Measured or Verified, across 28 of 40 files.
9
Rules published below
Each anchored to a live line in the file it comes from. The rest of the rulebook stays private.

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.md
  • project file at ./CLAUDE.md or ./.claude/CLAUDE.md
  • local 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

Where this corpus breaks that guidance, on purpose. The middle file here is 92 lines, which is inside it. 8 are not. The honest version of the advice: short by default, long only where a line has already been paid for, and a size limit belongs in a check that fails the file rather than in a sentence inside it.

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.

SectionFiles
what this repo is
5
architecture
4
critical
4
deploy
4
quality standard
4
user context
4
absolute
3
activity counter
3
analytics env
3
brand voice constraints
3
build commands
3
hard rules
3
key files
3
prerender
3

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.

No date in the file · lives in the user file

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.

No date in the file · lives in the user file

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.

No date in the file · lives in the user file

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.

Dated 2026-08-26 in the file · lives in the project file

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.

No date in the file · lives in the project file

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.

Dated 2026-08-21 in the file · lives in the project file

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.

Dated 2026-08-09 in the file · lives in the project file

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.

No date in the file · lives in the project file

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.

Dated 2026-08-14 in the file · lives in the project file

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
How this was measured. Every CLAUDE.md under this operation's two code roots, at most four folders deep, with build output and abandoned copies left out. One machine, so every count is a floor. Counted on 2026-11-16. Two files with identical bytes count once, so a repository copied twice counts once; two copies that have since DRIFTED count twice, which makes the file count an upper bound and can repeat a heading in the table. Nothing here publishes a path, a repo, a product or a person: the writer sweeps the payload against the same privacy classes the public skills pack uses and refuses to write a file that trips one.