What NOT to include
Full Lesson Reference
The easiest way to make CLAUDE.md useless is to stuff it with content that doesn't need to be there. Long files dilute the rules that matter, waste tokens on every session, and often contain instructions Claude would follow anyway.
Here's what to cut.
The deletion test
For every line in every CLAUDE.md file, ask
"Would removing this cause Claude to make mistakes?"
If no - delete it. Don't keep it "just in case". Don't keep it because it feels thorough. Delete it.
Things to delete entirely
Code formatting rules
Don't include instructions like "use 2-space indentation" or "prefer single quotes". Claude Code already formats code well by default. These lines just eat tokens.
"Write clean code" style instructions
Claude is already trying to write clean code. Telling it to do so doesn't add value. Same goes for "write clear comments", "use descriptive variable names", "follow best practices".
Generic AI-behaviour instructions
"Be helpful", "explain your reasoning", "suggest improvements" - all baseline behaviour. Don't include.
Rules Claude is going to break no matter what you say
"Always check the docs before writing code" - Claude will guess first if the answer seems obvious. "Never make assumptions" - Claude will make assumptions. Write prompts that make your preferences obvious in the moment instead of hoping CLAUDE.md forces them.
Things to move, not keep in global
Project-specific content
Anything that applies to only one client, one repo, or one codebase doesn't belong in the global file. It gets loaded into every session even when irrelevant, dilutes everything else, and gets ignored when it doesn't match.
Examples of what to MOVE from global to project
- Build or test commands for a specific project
- Architecture descriptions of a particular codebase
- Brand colours for a specific client
- Database connection references for one account
Long tutorials or workflow instructions
If something is a multi-step repeatable workflow (e.g. "how to build a monthly report"), it belongs in a Skill, not CLAUDE.md. Skills are reusable, scoped to the task, and don't pollute every session's context.
Never put these anywhere in CLAUDE.md
API keys, passwords, or credentials
CLAUDE.md files get committed to git. Credentials must never touch them. Use environment variables, a secrets manager, or a 1Password-style tool instead.
Database schemas (usually)
Schemas belong in the project itself - a schema.sql file, an agent_docs/ folder, or the database's own tooling. Not in CLAUDE.md.
Anything sensitive or confidential
If you wouldn't want it on a public GitHub repo, keep it out of CLAUDE.md. Use CLAUDE.local.md (gitignored by convention) for machine-local notes.
The biggest mistake: making it too long
The most common CLAUDE.md failure is a 200-line global file that tries to cover every edge case. Here's what actually happens when CLAUDE.md gets long:
- Rules at the bottom get deprioritised
- Claude picks and chooses which lines to follow based on relevance to the current task
- Your important safety rules get buried in formatting rules
- Token cost hits every session you run
Lean is better than thorough. Under 25 lines for global is the target. If you're over 50, something needs to move or be deleted.
Use CAPS for rules that matter
When a rule is non-negotiable, write it in CAPS
NEVER fabricate metrics or performance data. NEVER commit .env files or API keys. ALWAYS ask before destructive operations. This is a community convention that measurably improves adherence. Reserve it for things where failure has real consequences - not for every preference.
Use Claude to audit the file
Once you've written a CLAUDE.md, tell Claude
Read my global CLAUDE.md at ~/.claude/CLAUDE.md. For each line, tell me: does this apply to every project? Would removing it cause mistakes? Flag anything that should move to a project file, or be deleted entirely.
Claude will go line by line and suggest cuts. Approve or reject each one. This is the fastest way to trim a bloated CLAUDE.md to size.
Action items
☐ Open your global CLAUDE.md - tell Claude to show you its current line count
☐ Tell Claude to audit it against the "would removing this cause mistakes?" test
☐ Cut anything Claude flags as delete-able
☐ Move anything project-specific to the relevant project folder's CLAUDE.md
☐ Reserve CAPS for the 2-3 non-negotiable safety rules
Next lesson: Audit and keep it tight.
Exercises
- Review the concepts covered in this lesson: What NOT to include.
- Write down your key takeaway from this lesson.
- Practice running any commands or prompts mentioned above inside your terminal.