Why Token Usage Matters
Claude's context window is finite. Every token in your CLAUDE.md is a token not available for code, conversation, or Claude's output. A bloated CLAUDE.md reduces Claude's effective working memory.
Beyond context limits, longer CLAUDE.md files are harder to maintain, easier to contradict, and less likely to be read and updated by your team.
The CLAUDE.md Token Budget
Target under 300 lines (~4,000 tokens) for most projects. This leaves ample context for real work. Signs your CLAUDE.md is too long:
- You're restating things Claude already knows (general programming best practices)
- You have multiple contradicting rules
- You haven't opened the file in 3+ months
- New team members find it overwhelming to read
Before: Verbose Rules
## Code Quality When writing code, please make sure to write clean, maintainable code that is easy to understand. Code should be self-documenting whenever possible. Variable names should be descriptive and clear. Functions should do one thing and do it well, following the single responsibility principle. Please avoid writing very long functions that do many different things. Keep functions short and focused. Always add comments to explain complex logic. Make sure to handle errors properly. Never ignore errors. Always write TypeScript types for everything. Don't use any. Use interfaces for object shapes. Export types that are used across files.
After: Concise Rules
## Code Style - TypeScript strict mode; no `any` — use `unknown` + narrowing - Interface for object shapes, type alias for unions - Functions: single responsibility, under 40 lines - Export types used across module boundaries
The "after" version says the same things in 4 lines instead of 12. The removed text was either stating obvious best practices or redundant.
Techniques for Shorter Rules
Reference external docs. Instead of copying your entire API design guide, link to it:
## API Design
Follow our REST conventions at docs/api-design.md.
Key points: Zod input validation, { data } | { error } response shape, 422 for validation errors.Use lists over paragraphs. Bullet points parse faster and waste fewer tokens on conjunctions and transitions.
Remove redundant rules. Audit for rules that duplicate each other or state general best practices Claude already knows.
Use code examples strategically. One good code example can replace three paragraphs of explanation — but only include examples where behavior is genuinely non-obvious.
The Layered Approach
Use subdirectory CLAUDE.md files to scope rules. Instead of one massive root CLAUDE.md, have a lean root file and specific files per module:
# Lean root CLAUDE.md (general rules, 80 lines) CLAUDE.md # Module-specific rules (only loaded when Claude enters that dir) api/CLAUDE.md # API-specific conventions frontend/CLAUDE.md # Frontend patterns infra/CLAUDE.md # Infrastructure rules