The number
Anthropic’s official guidance on steering Claude Code says to keep CLAUDE.md under 200 lines. Mine had drifted well past that. Most working repos I see have too.
The reason for the limit is mechanical, not aesthetic. Every line in that file loads into every session, whether or not it is relevant to what you are doing. A 600-line file means your model reads your entire operating manual before answering “what does this function do”.
One piece of context on the number: that guidance is framed mainly around shared team repositories, where the file is a contract between people. A solo project can run a bit fatter without much harm. The principle still holds — it is just less urgent.
The three-way split
The useful part of the guidance is not the line count. It is the boundary it draws between three different steering surfaces. Same documentation, three verbatim rules:
- “Keep CLAUDE.md under 200 lines.”
- “Instructions that are procedural… belong in a skill rather than in CLAUDE.md.”
- “Use hooks for anything that should happen deterministically.”
Which gives you a decision tree you can apply to every line in your file.
Fact, procedure or rule
Is it a fact? Something true about the project in every session — the stack, where things live, house conventions, what not to touch. That belongs in CLAUDE.md. It is cheap because it is short and it is always relevant.
Is it a procedure? A multi-step workflow that applies to some tasks and not others — how to cut a release, how to build a deck, how to onboard a client. That belongs in a skill. Skills load when they are needed and cost nothing when they are not. That is the entire point of them.
Is it a deterministic rule? Something that must happen every time, without judgement — run the formatter after an edit, block a commit that contains a secret, log every deploy. That belongs in a hook. A hook is code. It fires reliably. An instruction in a file is a request that a model may or may not honour on turn forty.
The named anti-pattern
The documentation calls out one phrasing specifically as an anti-pattern: “Every time X, always do Y” written in CLAUDE.md.
It is the most common line in every bloated instruction file I have read, and it is the worst of both worlds. You have described something deterministic, so you clearly want a guarantee. And you have written it as a suggestion to a language model, so you have not got one. If it truly must happen every time, make it a hook. If it does not, stop pretending it does and let it go.
Do the diet in one pass
Paste this into Claude Code with your bloated file in the repo. It proposes the split before writing anything:
Read my CLAUDE.md and count its lines.
Sort every instruction in it into three groups:
1. Facts about this project that are true in every session.
2. Procedures - multi-step workflows that only apply to some tasks.
3. Deterministic rules - things that must happen every time an event occurs.
For group 2, propose a skill file for each procedure, with a name and a description line.
For group 3, propose a hook, naming the event it fires on.
Show me the proposed split before you write any files.Expect the split to be roughly a third facts, a third procedures that should be skills, and a third rules you never enforced. That has been the shape every time I have run it.
What you get back
- Faster, cheaper sessions, because the standing context is smaller.
- Better adherence, because the model is not weighing forty instructions to answer one question.
- Procedures that are actually reusable, because they now live in a file with a name.
- Rules that genuinely hold, because a hook does not have an opinion.
The file is not a dumping ground for everything you have ever wanted Claude to remember. It is the short list of things that are true all the time. Everything else has a better home.
Sources
From idea to operation
Make the next AI decision concrete.
NavAIgate helps leadership teams identify high-value AI opportunities, prove them safely and turn the winners into working systems.