It is tempting to pour everything into CLAUDE.md, but a bloated file works against you. The rules that matter get lost in the noise, and Claude has more to wade through. A small, focused file is easier to follow.
Aim for under about 200 lines
Use roughly 200 lines as a ceiling to keep yourself honest. If the file is growing past that, it is a signal to trim or split rather than keep piling on. The number is a guide, not a hard limit — the real goal is a file you can read top to bottom without losing the thread.
Cut what Claude can infer
The fastest way to shrink a file is to delete what Claude already knows. It can read your code and see the framework, the folder structure, and the obvious patterns. Documenting those wastes space. Keep the things Claude cannot guess: preferences, non-obvious rules, and hard requirements.
Split detail into imported files
When a topic genuinely needs depth, move it out and link it with an @path import instead of inlining it:
# CLAUDE.md
## Core rules
- Prefix commits with the ticket number.
- Never render comment bodies as HTML.
## More detail
@docs/testing-guide.md
The main file stays a tight summary; the long guide lives on its own and loads through the import.
Review it now and then
Memory files drift. Rules that were true six months ago may not be now. Open the file with /memory occasionally and prune anything stale. A file you trust and keep current beats a long one you have stopped reading.
Comments
Be the first to comment.