Your CLAUDE.md is probably too long

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

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. Short, specific instructions are easier to inspect and maintain, but length alone does not establish whether a model will follow them.

Other failure patterns to check:

• 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. After moving a procedure, check that an appropriate task still discovers it and unrelated tasks do not load it.

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." These state the intended boundary. Enforce important restrictions with permissions or verification; wording alone is not a guarantee.

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." Check the resulting diff for compliance rather than assuming the sentence prevents every violation.

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.

For a first maintenance pass, run every documented command from a fresh checkout, remove obsolete instructions, and try one task involving a known repository exception. Check both the result and which instruction file the session loaded.

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.