CLAUDE.md:
the agent's entry point

CLAUDE.md is not a write-once document. It evolves as your project evolves. New patterns emerge, old ones disappear, dependencies get replaced, conventions change.

But most people only add to it. They never remove. After six months, their CLAUDE.md is 400 lines of accumulated rules — half of which describe patterns that no longer exist in the codebase.

The removal filter

Once a month, read every line of your CLAUDE.md and ask one question: "If I deleted this line, would Claude make a mistake?"

If the answer is no, delete it.

That is the entire filter. No nuance, no "but it might be useful someday." If Claude would not make a mistake without it, it is costing you context budget for nothing.

Here are common candidates for removal:

• Framework descriptions ("This project uses Next.js 14 with App Router") — Claude can see this from package.json
• Generic best practices ("Write clean, readable code") — Claude already does this
• Patterns obvious from the code ("Components are in the components/ directory") — Claude reads the file tree
• Rules about deprecated features ("Never use the old auth system") — if the old auth system is gone, the rule is dead weight

CLAUDE.md as code

Your CLAUDE.md should be treated exactly like code. Version-controlled. Reviewed in pull requests. Tested.

What does "tested" mean for a CLAUDE.md? It means checking whether Claude actually follows the rules. If you have a rule that says "always use named exports for utilities" and Claude keeps using default exports, one of two things is true:

1. The rule is poorly worded — rewrite it
2. The rule cannot be reliably enforced by text — replace it with a hook

Either way, an unfollowed rule is worse than no rule. It gives you false confidence. You think the agent will behave a certain way, and it does not.

The de-sloppify pattern

Negative instructions are a problem. "Don't use default exports." "Never import from apps/ in packages/." "Don't call AI providers directly."

These work, but they have a hidden cost. Negative instructions are harder for the agent to track across a long session. The more "don't" rules you accumulate, the more cognitive load you place on the system. The agent has to remember everything it should not do while also doing the thing you actually asked for.

There are two better alternatives:

Remove the temptation. Restructure your code so the bad pattern is not possible. If you do not want imports from apps/ in packages/, set up your TypeScript path aliases so those imports do not resolve. The mistake becomes a compile error, not a convention violation.

Add a cleanup pass. Instead of relying on Claude to never make the mistake, let it work freely and then run a separate check. A PostToolUse hook that catches the violation. A lint rule that flags it. A dedicated reviewer agent that scans for anti-patterns.

Both approaches are more reliable than a line in CLAUDE.md that says "don't."

Evolution patterns

CLAUDE.md rules have a lifecycle. Understanding it helps you keep the file lean and effective.

There is a more automated version of this lifecycle. A Stop hook — one that fires when Claude finishes responding — can parse the session for patterns: what errors occurred, what corrections you made, what workarounds were needed. It extracts observations and proposes CLAUDE.md updates. You review them and decide what to keep.

This is not magic — it is a script that reads the conversation transcript, looks for repeated corrections and error-fix cycles, and suggests rules. The suggestions are not always good. But they surface patterns you would not have noticed because they are too small to remember but too frequent to ignore. Automated pattern extraction turns the evolution lifecycle from a monthly review into a continuous process.

The 200-line budget

CLAUDE.md is loaded at the start of every session. Every line consumes tokens from your context window. Every token spent on instructions is a token not available for actual work.

Treat your CLAUDE.md like a budget. When you add a new rule, look for an existing rule to cut. If you cannot find one to cut, ask yourself whether the new rule is truly necessary — or whether it is something Claude can figure out from the code.

I keep my project CLAUDE.md files under 200 lines. Some are under 100. The ones under 100 tend to work better, because every line in them is load-bearing. There is no filler, no repetition, no "nice to have."

# Count your CLAUDE.md lines
wc -l CLAUDE.md
 
# If it's over 200, time to prune
# If it's over 300, you're paying a significant context tax every session

The living document

Here is what healthy CLAUDE.md evolution looks like in practice:

Week 1: You run /init and get a generated file. It is 150 lines of generic content. You cut it to 80 lines of project-specific rules.

Week 4: You have added 15 rules from friction you captured. You are at 95 lines. You prune 5 rules that are now obvious from the code structure. Back to 90.

Month 3: You have moved 8 rules to hooks (they needed 100% enforcement) and 6 to skills (they were task-specific). You have added 10 new rules from new patterns. You are at 86 lines. Every line is battle-tested.

Month 6: A major refactor changes your project structure. You rewrite the Structure and Boundaries sections. You delete 12 rules about patterns that no longer exist. You add 4 rules about the new architecture. You are at 78 lines.

That is the goal. Not a growing document. A living one. One that reflects what your project is today, not what it was six months ago.