Most CLAUDE.md Files Are Too Long. The Ones That Work Are Under 100 Lines.

By Haim Ari · 2026-04-03

A 400-line CLAUDE.md doesn't make Claude smarter — it makes it slower to follow the rules that matter. Here's the instruction budget you're draining, and the structure that actually works.

A team shared their CLAUDE.md in a community thread last month. It was 847 lines.

Detailed sections on code style. Architecture diagrams in ASCII. Commit message templates copied from their wiki. Documentation conventions. Thirty rules about what to never do. A full onboarding guide for new developers in case they read it.

Their complaint: Claude keeps ignoring the most important rules.

That's not a coincidence. A file that long is actively working against them.

Why Long CLAUDE.md Files Backfire

There's a well-documented phenomenon with large language models: as context grows, instruction-following degrades. Not randomly — uniformly. Every low-value instruction you add dilutes the compliance probability of every high-value rule equally. It's not that Claude ignores long files; it's that it can't prioritize inside them.

The numbers are concrete. Frontier thinking models maintain reliable instruction-following for roughly 150–200 rules before compliance degrades. Claude Code's system prompt already consumes about 50 of those slots before your CLAUDE.md even loads. That leaves you 100–150 instruction "credits" to spend.

An 847-line CLAUDE.md isn't a detailed configuration — it's a compliance budget bankruptcy filing.

Boris Cherny, Claude Code's creator, keeps his CLAUDE.md at around 100 lines. That's not minimalism for minimalism's sake. It's calibrated to how Claude actually processes instructions. His core principle: "Would removing this cause Claude to make a mistake?" If not, it doesn't belong in the file.

The token cost compounds the problem. Every line in CLAUDE.md is loaded on every single inference. A 500-token file costs 500 tokens each time. A 12,000-token file — which is what you get at 800+ lines — costs 12,000 tokens on every tool call, every edit, every shell command. That's not just a performance hit. Over a long session, it accelerates context rot: the gradual degradation that starts when your context window is half full.

!Compliance meter dropping as instruction count climbs past 150

The Instruction Budget You're Draining

The mental model that fixes this: CLAUDE.md is a budget, not a document.

You have roughly 100–150 instruction slots. The question isn't "what should I document?" — it's "which rules are worth spending a slot on?"

A good slot looks like:

• Always use bun (/opt/homebrew/bin/bun), NEVER npm

• Commit only as "Haim Ari

• Dev server: portless vantage /opt/homebrew/bin/bun run dev

Each line is a constraint that, if forgotten, causes a concrete mistake. You can audit these rules with a single question: "If Claude violated this, would I notice immediately and have to correct it?" If yes, keep it. If no — if it's guidance, preference, or documentation — find a better home for it.

A bad slot looks like:

When writing TypeScript, prefer functional patterns and immutability where possible.

Consider using descriptive variable names that explain intent rather than implementation.

Remember that code is read more often than it is written.

This is advice Claude already follows by default. You're spending three slots to achieve zero behavioral delta.

The practical test for a healthy CLAUDE.md: read it top to bottom and ask for each line, "Would Claude behave correctly without this?" If the answer is yes more than 20% of the time, the file needs pruning.

!Developer watching token cost counter rapidly increment with each inference

Hooks Do What Rules Can't

One of the most powerful structural changes teams make when trimming their CLAUDE.md is moving mandatory rules to hooks.

The distinction matters:

• CLAUDE.md is advisory. It's guidance Claude reads and weighs against context. If Claude judges that bending a rule fits the situation, it might. Think of it as a style guide.

• Hooks are deterministic. They run as shell commands on specific events — before a tool call, after a file edit, after a bash command completes. They can't be reasoned around because they execute outside Claude's context entirely.

The community principle that's emerged: If the action must happen every time with no exceptions, use a hook. If it's guidance that allows for judgment calls, use CLAUDE.md.

A common example: "Never use --no-verify when committing." Put that in CLAUDE.md and Claude might override it when it thinks the situation warrants it. Put it in a pre-commit hook and it's physically impossible to bypass.

What moves to hooks:

• "Run linter after every file edit" → PostToolUse hook running eslint

• "Never commit with --no-verify" → PreToolUse hook blocking that flag

• "Always run tests before marking a task complete" → hook triggered on bash commands that include git commit

• "Notify me when a file in /api changes" → PostToolUse hook with a Telegram message

What stays in CLAUDE.md:

• Stack and tool conventions (which package manager, which framework)

• Git identity and commit format

• Build and deploy commands

• Non-obvious project architecture decisions

Moving five rules from CLAUDE.md to hooks frees five instruction slots. Applied consistently, it's one of the fastest ways to bring a bloated file back under 100 lines — while actually increasing compliance on the rules that matter most.

!Robotic arm physically stopping a commit button — hooks as deterministic enforcement vs advisory rules

The @import Architecture

For larger projects — monorepos, multi-team repos, or codebases where different conventions apply to different directories — a single CLAUDE.md becomes a poor fit. The community solution is @imports.

The syntax is simple:

`markdown

Project: vantageacademy.io

Stack

• Vite + React 19 + TypeScript SPA

• See @docs/frontend-conventions.md for component patterns

• See @docs/content-pipeline.md for blog post workflow

Git

• Commit as "Haim Ari

• Never add Co-Authored-By lines

Build

• bun install && bun run build && node scripts/prerender.mjs

The root CLAUDE.md stays lean — under 50 lines ideally. The @imports pull in detailed conventions only when Claude is working in the relevant area. Imports are recursive: @docs/frontend-conventions.md can itself reference @docs/design-tokens.md.

The architectural principle this enables: keep detailed conventions in the same directory as the code they govern. An api/CLAUDE.md imported from the root can describe API-specific patterns without polluting the global context. A scripts/CLAUDE.md can explain pipeline conventions without every developer session loading them.

The practical constraint: not every tool supports @imports equally, and Claude processes referenced files on demand rather than up front. For instructions that must always be in context, they belong in the root CLAUDE.md directly. For conventions that only matter when working in specific areas, @imports are the right tool.

One pattern that's emerged from heavy @import users: a compact-instructions section in the root CLAUDE.md that tells Claude what to preserve during compaction. Because CLAUDE.md is re-injected after every compaction (it lives in the system prompt, not conversation history), this section survives context resets and keeps long sessions on track.

`markdown

Compact Instructions

When compacting, always preserve:

• Current task and files modified

• Any constraints I've stated in this session ("don't modify migration files")

• The list of completed steps in multi-step tasks

!Nested file structure with @import arrows flowing from sub-documents into a clean root CLAUDE.md

Try It Yourself

Step 1: Run the self-audit

Open your CLAUDE.md and mark each line with one of three labels:

• [essential] — Claude would make a concrete mistake without this

• [hook] — This is mandatory enforcement, not advisory guidance

• [noise] — Claude already does this, or it belongs in documentation

Delete every [noise] line immediately. Move every [hook] line to your hooks configuration.

Step 2: Check your line count

`bash

wc -l CLAUDE.md

Target: under 100 lines. Acceptable: up to 150. Above 200: you have context budget problems.

Step 3: Add one compaction preservation section

At the bottom of your root CLAUDE.md:

`markdown

Compact Instructions

When compacting, preserve: active task description, files modified this session,

any hard constraints I've stated ("don't change the API contract"), completed steps.

!Developer running the self-audit: marking each CLAUDE.md line as essential, hook, or noise

Step 4: Move the details to @imports

Take any section that applies only to a specific subsystem and extract it:

`bash

Create a sub-CLAUDE for your scripts directory

mkdir -p scripts

cat scripts/CLAUDE.md << 'EOF'

Scripts Directory

• All scripts run with Node 20

• Use ES modules (import/export), not CommonJS

• Environment variables from .env.local via dotenv

• Never hardcode API credentials

EOF

In your root CLAUDE.md, replace the deleted section with:

`markdown

Scripts

• See @scripts/CLAUDE.md for script conventions

Step 5: Set up the three most common hooks

`bash

In your .claude/settings.json

{

"hooks": {

"PostToolUse": [

{

"matcher": "Edit|Write",

"hooks": [{"type": "command", "command": "cd $PROJECT_ROOT && npm run lint --silent 2&1 | head -20"}]

}

"PreToolUse": [

{

"matcher": "Bash",

"hooks": [{"type": "command", "command": "if echo '$CLAUDE_TOOL_INPUT' | grep -q 'no-verify'; then echo 'blocked: --no-verify not allowed'; exit 2; fi"}]

}

]

}

Step 6: Run /init on a fresh project

For any new project, start with:

/init

Claude Code reads your project structure and generates a starter CLAUDE.md. Edit it to fit the 100-line target before adding anything. It's much easier to keep it lean from the start than to prune a file that's grown to 400 lines.

The before/after difference is measurable. Teams that trim to under 100 lines report that their most important rules — the ones that caused repeated corrections when violated — suddenly hold across long sessions. Not because Claude got smarter. Because it's no longer wading through 800 lines of noise to find the 10 rules that matter.

The file that makes Claude follow your rules is the one that only contains your rules.