L3Lesson 4

Do Not Stuff CLAUDE.md

After this, you'll be able to distinguish rules that belong in CLAUDE.md from context that belongs in the chat, and keep your rules file lean enough to actually work.

Before you start

Complete Write Your First CLAUDE.md first; this lesson builds on having a live rules file so you have real content to evaluate for what to keep versus cut.

The idea

The most common mistake at Level 3 is treating CLAUDE.md like a notebook. Developers add project notes, architecture explanations, task lists, and meeting decisions. The file grows to 200 lines. Output quality drops. The model is slower and the answers feel less sharp. The cause is straightforward: every line of CLAUDE.md loads into the context window at session start, every session. A bloated CLAUDE.md is a standing tax on every interaction.

There is a clear line between what belongs in CLAUDE.md and what does not. Rules and conventions belong in CLAUDE.md: things that are true every session and change Claude's behavior in a specific way. Runtime context does not: the bug you are debugging today, the ticket you are working on, the meeting notes from last Thursday. That content belongs in the chat window for this session, pasted in when it is relevant, and gone when the session is over.

Here is the practical test. Ask: will this still be true and relevant in six months? If yes, it is a rule. If no, it is runtime context. "Always use the project's logger utility, not console.log" is still true in six months. "We are currently refactoring the auth flow because of the incident last week" is not. The first belongs in CLAUDE.md. The second belongs in the chat for this session, then disappears.

Try it (15 min)

Watch out for

Adding project notes and architecture docs to CLAUDE.md. Those belong in a README or a context file you paste when relevant, not in a file that loads every session.
Using CLAUDE.md as a to-do list. Task lists change daily and cost tokens every session. Use a separate task file.
Adding a rule every time something goes wrong without ever pruning. CLAUDE.md should grow slowly and shrink occasionally.
Thinking longer CLAUDE.md means better sessions. Past about 80-100 lines for a single project, output quality measurably degrades as noise drowns the signal.
Keeping rules that describe preferences instead of constraints. "I prefer TypeScript" is a preference. "This project uses TypeScript. Never suggest JavaScript." is a constraint. Write constraints.

Paste this into Claude:

I want to audit my CLAUDE.md for over-stuffing. Here is my current file: [paste your CLAUDE.md, or describe what you have in it if you do not have one yet]. Review it with me. For each section or rule, tell me: (1) Is this a stable rule that changes Claude's behavior specifically? (2) Is this runtime context, documentation, or project notes that I am reading more than Claude is acting on? (3) Does Claude already know this without being told? Sort every line into: keep as a rule, move to chat when relevant, or delete entirely. Then give me the pruned version.

What good looks like:

You ran the audit and got every line sorted into one of three categories: rule, runtime context, or redundant
You moved at least one piece of runtime context out of the file and into a chat template instead
The pruned file is shorter than the original and every remaining line changes Claude's behavior specifically
You can explain the difference between a rule and runtime context in one sentence
You started a new session with the pruned file and noticed no loss of relevant behavior

What a good response looks like:

Here is every line of your CLAUDE.md sorted into three categories.

Keep as rules (these change my behavior specifically):
- "All database queries go through src/db/query.ts. Never use raw SQL." Rule. I would guess at the query pattern without this.
- "Tests live in src/__tests__/. Never create test files next to source files." Rule. File location is project-specific.
- "This project uses Postgres 15. Never suggest MySQL syntax." Rule. I would occasionally use MySQL-specific functions.

Move to chat when relevant (true today, not in six months):
- "We are refactoring the auth flow. The old code is in src/auth-legacy/ and the new code is in src/auth/." This is a transition state. Once the migration is done, this line is noise every session.
- "Current sprint: add email verification." Task list. Never belongs in CLAUDE.md.

Delete (I already know this):
- "Write readable code with good variable names." I already do this.
- "Always handle errors properly." Too vague for me to act on differently.
- "Consider performance." I already consider it.

Pruned file: 3 lines. Original: 14 lines. Every remaining line earns its place.

When this breaks

Breaks when CLAUDE.md hosts runtime state (current bug, current sprint) because the file ages instantly and pays the load tax forever even after the situation ends.
Breaks when the file collects preferences instead of constraints because the model already does most of what you would prefer and the file delivers no behavior change for the cost.
Degrades when there is no audit ritual because rules accumulate, lines that no longer apply linger, and over time the file pollutes context rather than focusing it.

Claude can do it for you

Paste your CLAUDE.md to Claude and say: "Which lines here are rules that change your behavior? Which are notes, context, or documentation you would never act on? Which would you follow anyway without being told? Give me the pruned version that keeps only the lines that change your behavior." Then use that output as your new file.

You can now

Produce a CLAUDE.md audit that sorts every existing line into rule, runtime context, or redundant, and ship a pruned version that is shorter than the original with no loss of relevant behavior.

Key takeaways

CLAUDE.md is for rules, not notes. If it only matters today, put it in the chat. If it matters every session, put it in the file. Nothing else belongs there.

Every line of CLAUDE.md loads at every session start. Length is a recurring tax, not a free resource
Six-month test: if it will still be true in six months, it is a rule. If not, it is runtime context for chat
Audit periodically. Sort lines into rule, runtime, or redundant, then cut the last two categories
Past about 80-100 lines on a single project, the file actively degrades output. Lean beats comprehensive

Go deeper

I want to audit my CLAUDE.md for over-stuffing. Here is my current file: [paste your CLAUDE.md, or describe what you have in it if you do not have one yet]. Review it with me. For each section or rule, tell me: (1) Is this a stable rule that changes Claude's behavior specifically? (2) Is this runtime context, documentation, or project notes that I am reading more than Claude is acting on? (3) Does Claude already know this without being told? Sort every line into: keep as a rule, move to chat when relevant, or delete entirely. Then give me the pruned version.

Here is every line of your CLAUDE.md sorted into three categories. Keep as rules (these change my behavior specifically): - "All database queries go through src/db/query.ts. Never use raw SQL." Rule. I would guess at the query pattern without this. - "Tests live in src/__tests__/. Never create test files next to source files." Rule. File location is project-specific. - "This project uses Postgres 15. Never suggest MySQL syntax." Rule. I would occasionally use MySQL-specific functions. Move to chat when relevant (true today, not in six months): - "We are refactoring the auth flow. The old code is in src/auth-legacy/ and the new code is in src/auth/." This is a transition state. Once the migration is done, this line is noise every session. - "Current sprint: add email verification." Task list. Never belongs in CLAUDE.md. Delete (I already know this): - "Write readable code with good variable names." I already do this. - "Always handle errors properly." Too vague for me to act on differently. - "Consider performance." I already consider it. Pruned file: 3 lines. Original: 14 lines. Every remaining line earns its place.

Paste your CLAUDE.md to Claude and say: "Which lines here are rules that change your behavior? Which are notes, context, or documentation you would never act on? Which would you follow anyway without being told? Give me the pruned version that keeps only the lines that change your behavior." Then use that output as your new file.