The 3000-line CLAUDE.md Problem

Your CLAUDE.md started at 40 lines. "Here's what this project is. Here's the stack. Here are some conventions." Clean.

Three months later it is 3000 lines and Claude Code is drifting more, not less. Every time Claude did something you didn't want, you added a paragraph to CLAUDE.md: “When reviewing PRs, also check for X.” “When writing tests, remember Y.” “Do not forget Z.”

The file grew. The drift got worse.

Here is why that happens, and what actually fixes it.

Why longer CLAUDE.md makes drift worse

Three compounding mechanisms:

1. Instruction dilution. Claude reads the whole CLAUDE.md every session. When your file has 40 lines of real instruction, each instruction gets meaningful weight. When it has 3000 lines — 80% of which are aspirational fluff, mission statements, and duplicated paragraphs — the real instructions get buried. Claude’s attention mechanism does attend to everything, but when everything is screaming, nothing is heard distinctly.

2. Recency bias hits early instructions hardest. If a 3000-line CLAUDE.md says "always check for N+1 queries" on line 400, and then 800 lines later you’re asking Claude to implement a new feature, the N+1 rule is ambient but not salient. The later context dominates. The earlier rule gets skipped.

3. Interpretive freedom compounds. Every CLAUDE.md paragraph is prose. Prose is interpreted fresh each session. You wrote "review PRs for security issues" — Claude interprets that differently depending on what else is in the context. One session it checks OWASP top 10. Next session it just checks for hardcoded secrets. You can’t tell why. The instruction is unstructured; the behavior drifts.

The problem isn’t that Claude ignores CLAUDE.md. The problem is that long-form prose instructions are inherently re-interpretable, and every session starts fresh. Length doesn’t make instructions more durable. It makes them noisier.

The first symptom: you start writing the same paragraph twice

At some point you notice you’ve written “review this PR for X” in three different sections of CLAUDE.md, each slightly different. You’re solving the same drift problem three different ways.

This is the signal that the instruction should not be in CLAUDE.md at all. It should be a skill.

What a skill is (and why it stops drift)

A skill lives in ~/.claude/skills/{name}/SKILL.md. Claude Code loads it automatically. Invoked explicitly by name:

use the pr-review-comprehensive skill on the current branch

A skill file is not prose. It enforces:

• Scope: exactly which files the skill touches, and which it refuses to.
• Output shape: predictable formatting. [severity] file:line — finding + suggested action. Every invocation, same shape. Greppable.
• Constraints: explicit “refuses to” rules. “Refuses to approve without citing 3+ verified items.” “Refuses to propose a fix before a repro is verified.”
• Sequence: ordered steps. No skipping when context is long.

The key distinction: prose in CLAUDE.md gets re-interpreted each session. A skill file declares rules that fire during execution, not rules that get merged into a free-form context window. Same structure every time.

The migration path

Three steps:

1. Run an audit. Paste your CLAUDE.md into the free client-side tool at septimlabs.vercel.app/tools/claude-md-analyzer. It flags length, instruction-vs-aspirational ratio, corporate-speak terms, and recurring-instruction patterns that should be skills.

2. Extract the top 5 recurring instructions. For every section of CLAUDE.md that tells Claude "when you do X, check for Y," move the how-to into ~/.claude/skills/{x}/SKILL.md. Format:

---
name: x
description: Short description of when to invoke this.
---

# Skill body

## Inputs
- What the skill expects

## Steps
1. Ordered step with explicit constraints
2. Another step
3. ...

## Output format
Structured output spec

## Refuses to
- Specific things the skill will not do

3. Delete the extracted instructions from CLAUDE.md. This is the step most people skip. You write the skill file and leave the original CLAUDE.md paragraph in place. That defeats the purpose — now you have the instruction in two places, with two different interpretations. Remove it from CLAUDE.md. The skill is the source of truth.

What CLAUDE.md should contain after the migration

Project-specific context only. About 5 sections:

1. What this project is. 3-5 lines. Not a mission statement.
2. Stack + deploy target. Bulleted, factual.
3. Project-specific conventions. Naming, testing framework, commit style, env var locations.
4. Gotchas. 5-15 specific traps the project has hit. “The Stripe webhook needs raw body.” “Supabase RLS is on.” This section is where CLAUDE.md earns its keep.
5. What not to touch. Paths, files, patterns Claude should refuse.

Target length: under 400 lines. Ideally under 200. If it’s longer, you still have reusable instructions that should be extracted.

A concrete before / after

Before (excerpt from a 2400-line CLAUDE.md):

## Instructions for Claude

When reviewing my pull requests, please check for:
- Code quality
- Tests
- Security issues
- Performance problems
- Breaking API changes

Please write code that is well-tested, maintainable, and scalable.
Aim for best-in-class quality that our customers will love.
Follow SOLID principles and clean architecture.

When reviewing, also make sure to consider edge cases, error handling,
and that the code follows our team’s conventions. We value excellence
and we want all code to meet our highest standards.

After (the relevant skill file, at ~/.claude/skills/pr-review-comprehensive/SKILL.md):

---
name: pr-review-comprehensive
description: Run a 7-lens review on a pending PR.
---

Run seven review lenses against the diff, in order:
1. Intent drift (does diff match description)
2. Logic correctness (walk every non-trivial branch)
3. Test gaps (every added function has a test)
4. Security (OWASP top-10 class scan)
5. Performance (N+1, unbounded, blocking sync)
6. API surface (breaking change check)
7. Rollback safety (revert cleanly if needed)

Output format:
- [severity] file:line — one-sentence finding + suggested action
Severities: blocker, major, minor, nit.
End with verdict: APPROVE / APPROVE with comments / REQUEST CHANGES / BLOCK.

Refuses to:
- Approve without citing 3+ verified items.
- Speculate about files outside the diff.
- Mark security issues without file:line reference.

The skill file is shorter AND more deterministic. CLAUDE.md shrinks by 300 lines. Claude’s review output stops drifting.

The skills you’ll probably need

Across 3 months of production Claude Code use, the recurring instruction patterns that almost always should be skills:

• Review — PR review, test gaps, migration safety, security triage, performance smell
• Refactor — extract shared logic, dead-code sweep, type tightening, error boundaries, env audit
• Documentation — README sync, API docs, changelog, commit quality, onboarding
• Ops — dependency triage, CI audit, bug reproduce, postmortem, deprecation plan
• Launch — HN post, X thread, release notes, spec-to-plan, effort estimate

If your CLAUDE.md currently has instructions in more than 2-3 of those categories, it’s doing the work of a skill directory, badly.

The last thing

The CLAUDE.md problem isn’t actually about CLAUDE.md. It’s about what happens when you try to solve drift with more prose. Prose doesn’t enforce; prose interprets. Every added paragraph is another interpretation surface.

The fix is structural: move enforcement out of prose and into a format that runs the same way every time. That’s what skills are. CLAUDE.md becomes what it should have been all along — a small, boring, factual context file about THIS project. Skills become the reusable enforcement layer.

Start by running the analyzer on your current CLAUDE.md. It won’t fix anything. It’ll just tell you specifically what’s wrong so you can fix it yourself — or reach for a pre-built pack so you don’t have to.

— The Septim Labs team