CLAUDE.md has grown to 900 lines, and Claude starts missing rules. What is the best fix?
Why B is the answer
Trim it, and move occasional procedures into skills
The docs suggest under 200 lines. Skills load only when used, so long procedures do not sit in every session. Imported files still load, so splitting alone does not save context.
In detail
- CLAUDE.md loads in every session, so length has a cost whether the content is needed or not.
- The docs suggest keeping it under 200 lines.
- Skills load only when used, so long procedures can move there.
- Keep rules that apply to most sessions, and move the rest out.
Use case
An illustrative scenario, not a real incident.
A team's CLAUDE.md reaches 900 lines, including a long release runbook used once a month. Moving the runbook to a skill shortens the file, and it loads only when someone is releasing.
See it in different ways
flowchart TD
A{"Needed in every session?"} -->|Yes| B["CLAUDE.md"]
A -->|No| C{"Must it run by itself?"}
C -->|"Only on request"| D["Skill with disable-model-invocation"]
C -->|"When relevant"| E["Skill"]mindmap
root((Instructions))
Project CLAUDE.md
Shared through Git
User CLAUDE.md
One person, every project
CLAUDE.local.md
One person, one project
Skills
Loaded when usedflowchart TD
Q{"How often does it apply?"}
Q -->|"Most sessions"| A0["CLAUDE.md"]
Q -->|"Occasionally"| A1["A skill"]Key point: Keep CLAUDE.md short, and put occasional procedures in skills.
Why the other options are wrong
- A. Split it across many files that are all imported at the very top of it
- Imported files still load, so splitting alone saves nothing.
- C. Add a line at the top telling Claude to read every rule with great care
- Asking for more care does not reduce the amount of text that competes for attention.
- D. Copy the whole file into the system prompt of each session as well
- A second copy adds context. It makes the problem worse.