Your CLAUDE.md is probably too long

CLAUDE.md sits at your repo root and holds the standing instructions the agent should have before it does anything. Project conventions, the commands that actually work, what not to touch. It is loaded into context automatically, which is both the feature and the trap.

Teams start with fifteen useful lines. Then someone adds a section after a bad session. Then someone else documents the deploy process. Six months in it is 600 lines, and the agent is ignoring the rule you care about most, which was line 40.

Why long files stop working

Instructions compete with each other for attention. A short file with eight rules gets followed. A long file with eighty rules gets treated the way you treat a terms-of-service page.

Two other failure patterns show up constantly when we audit repos:

• Restating things the model already knows. "Write clean, maintainable code" and "follow best practices" are decoration. Delete them.
• Documenting rather than instructing. A three-paragraph architecture explanation belongs in a doc the agent can read on demand. The instruction file should say what to do, not what exists.
• Stale commands. A build command that was renamed a year ago, still sitting there, quietly teaching the agent to run something that fails.
• Task-specific procedures that only apply once a month, loaded on every turn of every session.

That last category is the biggest win. Move those into skills, which load only when the task calls for them. One team we worked with cut a 700-line file to roughly 200 that way, and the remaining rules started being followed.

What belongs in CLAUDE.md

Things that are true for every task and that the model cannot infer from the code.

The commands, verbatim, including the flags that are non-obvious:

npm run test:unit -- --runInBand

The boundaries, stated as prohibitions. "Never edit files in src/generated/." "Never modify the lockfile by hand." Prohibitions get followed more reliably than preferences, because there is nothing to interpret.

The decisions you have already made and do not want relitigated. "We use the repository pattern for data access. Do not add ORM calls in route handlers." That single sentence prevents an entire class of plausible, wrong code.

And the surprises. Every codebase has two or three things that look like bugs and are not. Write those down. It is the highest-value content in the file, because it is the part no amount of reading the code would reveal.

Keeping it honest

The file rots. Nothing fails when it goes stale, which is exactly why it does. Add it to your review habits: if a pull request changes a build command or a convention, the instruction file changes in the same pull request or the review does not pass.

Personal preferences do not belong here. Your teammate does not want your commit message format enforced on their agent. Those go in your own user-level config, not the shared repo file.

What to do next

Open your file and go line by line with two questions. Would a competent new joiner already know this? Does this only apply to one kind of task? Delete the first group, move the second into skills. Aim to cut it in half in one sitting. Then run a normal task and see whether the rules you care about actually hold. If they do, you had a length problem, not a model problem.

If you want help putting this into practice, talk to us.