When CLAUDE.md gets too long, and what to move out of it
CLAUDE.md is read at the start of every session, so everything in it costs context every time. What belongs there, and where the rest should live instead.
CLAUDE.md is loaded at the start of every session in the project. That makes it perfect for facts that apply to everything and a poor home for anything that applies to one task in twenty.
| Keep in CLAUDE.md | Move out |
|---|---|
| Build, test and lint commands | Step-by-step procedures for one kind of task |
| Where the main code lives | Long style guides and design systems |
| The handful of hard rules | Reference tables and examples |
| What not to touch | History of past decisions |
Where the rest goes
Procedures and systems that apply to a kind of task belong in a skill, which loads only when that task comes up. Reference material belongs in docs that CLAUDE.md links to with one line each. The split, with examples, is in skills vs CLAUDE.md vs MCP.
A quick trim
- Delete anything the code already makes obvious.
- Turn each multi-paragraph procedure into a skill.
- Replace long explanations with a pointer to the doc that has them.
- Reread what is left: every line should matter to most tasks.
The same thinking applies inside skills, covered in how long SKILL.md should be.
Questions
What should go in CLAUDE.md?
Facts about the project that apply to almost every task: how to build and test, where things live, the few rules everyone must follow. Short and current.
Where should detailed procedures go instead?
Into skills, which load only when the task matches, or into docs that CLAUDE.md points to. That keeps every-session context small.
How do I know CLAUDE.md is too long?
When most of it is irrelevant to most tasks, when it repeats what the code or docs already say, or when rules in it start being ignored.