That Reddit post captures the feeling perfectly: staring at an empty CLAUDE.md file, wondering what to write. You're not alone. Developers often treat CLAUDE.md like a comprehensive project bible they need to write upfront. That's wrong.
Your CLAUDE.md is a living conversation starter, not a final document. Its primary job is to give Claude Code enough context to begin useful work immediately, without wasting tokens on irrelevant history.
The 3-Section Minimum Viable CLAUDE.md
Create this file in your project root:
# CLAUDE.md
## 1. Project Rules
- Always run tests before committing: `npm test`
- Use TypeScript strict mode
- Never modify the `legacy/` directory
- Ask before installing new dependencies
## 2. Tech Stack
- Frontend: React 18, TypeScript, Vite
- Backend: Node.js 20, Express, PostgreSQL
- Testing: Jest, React Testing Library
- Package manager: npm
## 3. Current Task
I'm implementing user authentication. Need JWT-based login/logout endpoints and protected routes.
That's it. 10 lines. This gives Claude Code:
- Guardrails (what not to do)
- Context (what tools you're using)
- Direction (what to work on right now)
Why This Works: Token Economics
Claude Code reads your CLAUDE.md on every interaction. A massive file wastes tokens on every single request. According to Anthropic's recent announcement, their CLI tool saves 37% more tokens than MCP servers—don't undo those savings with a bloated config.
Your CLAUDE.md should be just enough context for the current work session. Update section 3 as you switch tasks. Add to sections 1 and 2 only when you discover new constraints or tools.
Advanced: The Iterative Approach
Once you have the basic template working, evolve it based on what Claude Code struggles with:
## 4. Common Patterns (add as needed)
- API responses use: `{ success: boolean, data?: T, error?: string }`
- Component naming: `FeatureButton` not `ButtonFeature`
- Error handling: Use our custom `AppError` class
## 5. Recent Changes (temporary)
- Just migrated database schema v2 → v3
- Authentication switched from sessions to JWT yesterday
Notice what's missing? No project history. No architecture diagrams. No team member bios. Those belong in your actual documentation, not in the file Claude reads on every request.
The One Rule: Start Now, Edit Later
The biggest mistake is not starting because you're worried about getting it "right." Create the 3-section template today. Run claude code "implement login form" and see what questions Claude asks. Those questions tell you what to add to your CLAUDE.md.
Remember: A CLAUDE.md that exists and is imperfect is infinitely more valuable than one that doesn't exist because you're overthinking it.
