5 CLAUDE.md Mistakes Everyone Makes
Your CLAUDE.md is probably too long, too vague, or missing the parts that matter most. Here's how to fix it.
You set up a CLAUDE.md. Good. But is it actually helping? Here are the five mistakes I see constantly.
Mistake 1: Too Long
If your CLAUDE.md is 500+ lines, Claude Code is spending tokens reading your novel instead of doing work. Keep it under 200 lines. Be ruthless about what's essential.
Mistake 2: Too Vague
"Use good coding practices" tells Claude nothing. "Use TypeScript strict mode, Tailwind for styling, and put components in src/components/" tells it everything. Be specific. Be opinionated.
Mistake 3: No Session Lifecycle
The most valuable section of CLAUDE.md is the session lifecycle : what to read at start, what to write at end. Without it, you lose the memory system entirely.
Mistake 4: No Communication Preferences
Tell Claude Code HOW to talk to you. "Be direct. No preamble. Code first, explanation after. Don't ask if I want you to proceed, just do it." This saves hundreds of back-and-forth messages.
Mistake 5: Never Updating It
Your CLAUDE.md should evolve. When Claude makes a mistake you've corrected before, add it to CLAUDE.md. When you discover a pattern that works, document it. A living CLAUDE.md gets more powerful every week.
The Quick Fix
Open your CLAUDE.md right now. Check:
- Under 200 lines?
- Specific stack and conventions listed?
- Session lifecycle defined?
- Communication preferences included?
- Updated in the last week?
If any answer is no, spend 10 minutes fixing it. Your next 100 sessions will thank you.
If you are a UX or UI designer, we have a guide series built specifically for your work: decoding briefs, running heuristic evaluations, synthesizing research, and handing off to code. No terminal required for most of it.
Browse the designer guidesRelated Posts
CLAUDE.md Is Not Optional
Skipping CLAUDE.md is like hiring a developer and never telling them about the project. Stop doing it.
The 3 Prompts That Changed How I Use Claude Code
Specific, copy-paste-ready prompts that immediately level up your Claude Code workflow.
Why Context Beats Cleverness Every Time
Stop trying to write the perfect prompt. Start giving Claude Code the right context instead.
New guides, when they ship
One email, roughly weekly. CLAUDE.md templates, workflows I actually use, and the cut-for-length stuff that does not make the public guides. One-click unsubscribe.
Or follow on Substack