L4Lesson 3

Write a CLAUDE.md That Earns Its Tokens

After this, you'll have a CLAUDE.md that prevents your most common recurring mistakes without wasting tokens on things Claude already knows.

Before you start

Before diving in, complete Prune Like a Pro so you arrive with a pruned session history and can see clearly which recurring mistakes still need a rule.

The idea

Claude keeps suggesting MySQL syntax. Your project uses Postgres. You have corrected it four times this week, in four different sessions. Each correction takes two minutes. That is eight minutes you have spent re-teaching the same thing. One line in CLAUDE.md would have prevented all four corrections.

CLAUDE.md is not documentation. It is not a README. It is the instruction file Claude reads at the start of every single session, before you type anything. Every line costs tokens, every session. A bloated CLAUDE.md with 200 lines of general advice is worse than a tight 20-line file with your three most important project-specific rules.

Here is the before and after: One team's CLAUDE.md included 47 lines like 'Always write clean, maintainable code' and 'Consider performance when writing functions.' Those lines cost tokens every session and changed nothing, because Claude already knows them. Three lines replaced those 47 and actually changed behavior: 'Never use var, always const or let.' 'All API calls must include a timeout of 5000ms.' 'This project uses Postgres, not MySQL. Never suggest MySQL syntax.' Those three lines prevented at least 10 repeated mistakes in the following week.

The test for any CLAUDE.md line: would Claude do the right thing without it? If yes, delete it. If no, it earns its place.

Try it (20 min)

Watch out for

Writing CLAUDE.md before you have real mistakes to prevent. Speculative rules waste tokens.
Including project-agnostic advice ('write clean code'). Claude knows this already.
Lines that describe preferences ('I prefer X') instead of explicit rules ('Always X, never Y')
Never updating it. CLAUDE.md should grow from every session where Claude made the same mistake twice.
Making it so long that the important rules get buried and de-weighted by all the noise around them.

Paste this into Claude:

Here is my current CLAUDE.md: [paste your file, or describe what is in it]. Audit it for me. Which lines are things Claude would already do without being told? Which lines are genuinely project-specific and would change Claude's behavior? Which lines conflict with each other? Give me a pruned version under 30 lines that keeps only the lines that earn their place.

What good looks like:

You got a pruned version that is meaningfully shorter than the original
Every remaining line passes the test: Claude would behave differently without it
You removed at least one category of filler (general best-practice advice Claude already knows)
The pruned file has at least one rule that came from a real mistake, not from speculation
You saved the pruned version and started a new session to verify it loaded correctly

What a good response looks like:

Here is your CLAUDE.md audited against the test: would I behave differently without this line?

Lines I would follow without being told (delete these):
- 'Write clean, maintainable TypeScript.' I already do this. Zero behavior change.
- 'Always handle errors gracefully.' Too vague. I handle errors already, this tells me nothing specific.
- 'Follow RESTful conventions for API design.' I default to REST. No change.

Lines that are genuinely project-specific (keep these):
- 'This project uses Postgres 15. Never suggest MySQL syntax or MySQL-specific functions.' Keeps. I would occasionally drift to MySQL without this.
- 'All database access goes through src/db/query.ts. Never use the Prisma client directly in route handlers.' Keeps. I would use Prisma directly.
- 'Never use var. Always const or let.' Keeps. Without this I might use var in legacy-looking contexts.

Pruned file: 3 lines. Original: 14 lines. The 11 deleted lines cost you tokens every session and changed nothing. The 3 remaining lines will prevent real mistakes every session.

Go deeper (15 min)

Paste this into Claude:

Ask Claude to audit your CLAUDE.md directly. Say: 'Read my CLAUDE.md and tell me: (1) Which rules here would you follow anyway without being told? (2) Which rules are genuinely useful project-specific constraints? (3) Which rules contradict each other? (4) What is missing based on the mistakes you have made in our previous sessions?' Then apply its feedback.

What good looks like:

Claude identified at least two rules it would follow without being told
Claude flagged at least one contradiction or redundancy you had not noticed
You updated your CLAUDE.md based on the audit output
You can now explain the purpose of every line in your CLAUDE.md in one sentence

What a good response looks like:

Here is my audit of your CLAUDE.md from the inside.

Rules I would follow without being told (candidates for deletion): 'Use meaningful variable names.' 'Write functions that do one thing.' Both of these are defaults. I do not need to be instructed.

Conflicting rules I found: Rule 7 says 'Prefer async/await over Promise chains.' Rule 12 says 'Use .then() for sequential async operations for readability.' These are contradictory. Every time I hit an async operation I have to guess which you want. Pick one, delete the other.

Redundancy: Rules 3 and 9 both say variants of 'do not use console.log.' One line is enough.

What is missing based on our previous sessions: In three sessions you corrected me for using `interface` instead of `type` for object shapes. There is no rule about this. The line that would prevent it: 'Use `type` not `interface` for object type aliases. Reserve `interface` only for class contracts.'

Updated file suggestion: remove rules 2, 7 or 12 (pick one), 9 (duplicate of 3), and add the new type/interface rule. Net result: same coverage, 3 fewer lines, no contradictions.

When this breaks

Breaks when CLAUDE.md grows by accretion because rules added speculatively are never removed and the file becomes a museum of decisions that no longer apply.
Breaks when project-agnostic best-practice content dominates because Claude already follows it by default and the actual project-specific rules get diluted by the surrounding noise.
Breaks when two contradictory rules accumulate over time because the model picks whichever appears later in the file and your behavior becomes a function of file order, not intent.

Claude can do it for you

After any session where Claude made a mistake it has made before, say: 'Add a rule to my CLAUDE.md to prevent this from happening again. Write the exact line I should add.' It will write the rule for you.

You can now

Audit your CLAUDE.md and produce a version under 30 lines where every remaining line passes the test 'Claude would behave differently without this.'

Key takeaways

Every line of CLAUDE.md is paid for in tokens every session. Each line must earn its place by changing behavior, or it is a tax with no return.

CLAUDE.md is a permanent token tax. Every line bills every session whether it changes behavior or not.
The earn-its-place test: would Claude do the right thing without this line? Yes equals delete.
Rules with provenance, sourced from real session failures, compound. Speculative rules just bloat.
Contradictory rules are worse than no rules. They make behavior depend on file order.
Update CLAUDE.md from observed mistakes, not from one-sitting brainstorms about best practices.

Go deeper

Up nextTrust No Retrieved Document

Here is my current CLAUDE.md: [paste your file, or describe what is in it]. Audit it for me. Which lines are things Claude would already do without being told? Which lines are genuinely project-specific and would change Claude's behavior? Which lines conflict with each other? Give me a pruned version under 30 lines that keeps only the lines that earn their place.

Here is your CLAUDE.md audited against the test: would I behave differently without this line? Lines I would follow without being told (delete these): - 'Write clean, maintainable TypeScript.' I already do this. Zero behavior change. - 'Always handle errors gracefully.' Too vague. I handle errors already, this tells me nothing specific. - 'Follow RESTful conventions for API design.' I default to REST. No change. Lines that are genuinely project-specific (keep these): - 'This project uses Postgres 15. Never suggest MySQL syntax or MySQL-specific functions.' Keeps. I would occasionally drift to MySQL without this. - 'All database access goes through src/db/query.ts. Never use the Prisma client directly in route handlers.' Keeps. I would use Prisma directly. - 'Never use var. Always const or let.' Keeps. Without this I might use var in legacy-looking contexts. Pruned file: 3 lines. Original: 14 lines. The 11 deleted lines cost you tokens every session and changed nothing. The 3 remaining lines will prevent real mistakes every session.

Ask Claude to audit your CLAUDE.md directly. Say: 'Read my CLAUDE.md and tell me: (1) Which rules here would you follow anyway without being told? (2) Which rules are genuinely useful project-specific constraints? (3) Which rules contradict each other? (4) What is missing based on the mistakes you have made in our previous sessions?' Then apply its feedback.

Here is my audit of your CLAUDE.md from the inside. Rules I would follow without being told (candidates for deletion): 'Use meaningful variable names.' 'Write functions that do one thing.' Both of these are defaults. I do not need to be instructed. Conflicting rules I found: Rule 7 says 'Prefer async/await over Promise chains.' Rule 12 says 'Use .then() for sequential async operations for readability.' These are contradictory. Every time I hit an async operation I have to guess which you want. Pick one, delete the other. Redundancy: Rules 3 and 9 both say variants of 'do not use console.log.' One line is enough. What is missing based on our previous sessions: In three sessions you corrected me for using `interface` instead of `type` for object shapes. There is no rule about this. The line that would prevent it: 'Use `type` not `interface` for object type aliases. Reserve `interface` only for class contracts.' Updated file suggestion: remove rules 2, 7 or 12 (pick one), 9 (duplicate of 3), and add the new type/interface rule. Net result: same coverage, 3 fewer lines, no contradictions.

After any session where Claude made a mistake it has made before, say: 'Add a rule to my CLAUDE.md to prevent this from happening again. Write the exact line I should add.' It will write the rule for you.