*Every Claude Code session starts by reading one file: CLAUDE.md. Before your first prompt, before any code, before anything happens, Claude reads this file and treats it as ground truth for the entire session.*
Most people either don't have one, or theirs is 300 lines of personality instructions.
The difference between a good CLAUDE.md and a bad one is the difference between onboarding a senior engineer with a clear brief and throwing a new hire into a codebase with no documentation.
Here's how to write one that actually works👇
Before we dive in, I share daily notes on AI & vibe coding in my Telegram channel: https://t.me/zodchixquant🧠
Why most CLAUDE.md files don't work
Three reasons:
Too long. Models can reliably follow about 150-200 instructions. Claude Code's system prompt already contains roughly 50. That means your CLAUDE.md gets maybe 100-150 instructions before Claude starts dropping things. If your file is 200+ lines, Claude isn't ignoring your rules on purpose.
Wrong content. Most people fill CLAUDE.md with things Claude can figure out on its own. Personality instructions like "be a senior engineer" or "think step by step." General advice that doesn't change Claude's behavior. Every line that doesn't prevent a specific mistake is a wasted instruction.
No hierarchy. CLAUDE.md isn't the only place to put instructions. There are three levels and most people dump everything into one:
Global is for rules you'd repeat in every project. Project is for stack-specific context your team needs. Local is for your personal quirks.
Using all three keeps each file short and focused.
The 5 sections that actually matter
After going through dozens of production CLAUDE.md files from open-source projects, Anthropic's own docs, and community best practices repos, every effective file covers these 5 things:
1. Critical commands
Claude doesn't know how to build, test, or lint your project = tell it.
Short and specific. Claude runs these instead of guessing. Without this section, Claude will try npm test when your project uses pnpm vitest and waste 3 turns debugging a command that was never going to work.
2. Architecture map
Claude starts every session with zero knowledge of your codebase. Give it a map.
Not a full directory listing. Just enough so Claude knows where things live and what goes where.
3. Hard rules (the things Claude gets wrong without you)
This is the most important section. Every rule here should answer: "Would removing this line cause Claude to make a mistake?"
Two things to notice:
1. negative rules are as important as positive ones ("never commit .env")
2. emphasis markers like IMPORTANT actually work.
Anthropic's own docs confirm that adding "IMPORTANT" or "YOU MUST" improves adherence.
Keep this section under 15 rules.
4. Workflow preferences
How do you want Claude to work? This prevents the "Claude rewrites your entire file when you asked for a one-line fix" problem.
5. What NOT to include
Equally important is what you leave out:
Auto memory is underrated here. Claude maintains its own notes at ~/.claude/projects/<project>/memory/. Run /memory to see what Claude has already learned about your project.
Don't waste CLAUDE.md lines on things Claude figured out after one session.
The full template (copy this)
Here's a production-ready CLAUDE.md you can copy and adapt. Under 60 lines. Covers everything Claude needs, nothing it doesn't.
Delete sections that don't apply.
The rules that change everything
After testing dozens of CLAUDE.md configurations, these are the lines that made the biggest difference in output quality:
Each of these prevents a specific, common mistake.
That's the test for every line in your CLAUDE.md: does removing it cause Claude to do the wrong thing?
The mistake everyone makes
People treat CLAUDE.md like a wish list.
Your CLAUDE.md should be a technical brief, not a motivational speech. Stack, commands, architecture, rules, workflow. Everything else is noise competing for attention with the instructions that actually matter.
Keep it under 80 lines. Review it when Claude gets something wrong.
The file compounds over time. A good CLAUDE.md in month one saves you from repeating yourself.
By month six it's captured every mistake Claude has ever made in your project and prevents all of them automatically.
I share daily notes on AI, finance, and vibe coding in my Telegram channel: https://t.me/zodchixquant
