Your CLAUDE.md is probably too long. Here's how to cut it

A CLAUDE.md file starts life as five useful lines. Six months later it’s two hundred, half of which describe things Claude could work out by reading your code, and the instruction you actually care about is somewhere around line 140.

That’s not just untidy. Anthropic’s best-practices guide says it directly: bloated files cause Claude to ignore your actual instructions, because important rules get lost in the noise. The file is loaded at the start of every conversation, so every line costs context every time.

The test

For each line, the guide suggests asking one question: would removing this cause Claude to make mistakes? If not, cut it.

Applied honestly, that deletes a lot. Here’s a typical file before:

# Project overview
This is an e-commerce backend written in TypeScript using Express.
We value clean, readable, well-tested code.

# Structure
- src/routes: route handlers
- src/services: business logic
- src/db: database access

# Style
- Write clean code
- Use meaningful variable names
- Use async/await instead of callbacks
- Use ES modules, not CommonJS
- Don't use `default` exports in src/services

# Testing
- Run tests with `pnpm vitest run path/to/file.test.ts` for a single file
- Full suite is slow, avoid it unless asked
- Integration tests need `DATABASE_URL` set to the local docker db

Claude can see that the project is TypeScript and Express, and it can see the folder layout by looking. “Write clean code” changes nothing. Async/await is a convention it already follows. What’s left is the stuff it can’t guess:

# Style
- Use ES modules, not CommonJS
- No default exports in src/services

# Testing
- Single file: `pnpm vitest run path/to/file.test.ts`. The full suite is slow, so avoid it unless asked
- Integration tests need `DATABASE_URL` set to the local docker db

The guide’s own include list matches: commands Claude can’t guess, style rules that differ from defaults, testing instructions, repository etiquette, architectural decisions, environment quirks and non-obvious gotchas. The exclude list is the other half: anything Claude can figure out by reading code, standard language conventions, file-by-file descriptions, and self-evident practices like “write clean code.”

Where deleted rules should go

Cutting a rule doesn’t always mean it’s unimportant. Some of it belongs somewhere else:

• Knowledge that’s only relevant sometimes goes in a skill. Claude loads skills on demand, so they don’t bloat every session.
• Things that must happen every time, with no exceptions, go in a hook. Instructions in CLAUDE.md are advisory. Hooks are deterministic. (We covered a Stop hook for tests recently.)
• Detailed API docs should be linked, not pasted. The @path/to/file import syntax lets one file pull in another when you need it.

Let Claude propose the cuts

For a CLAUDE.md that’s checked into git, run /doctor and Claude proposes cuts for content it can derive from the codebase. Claude Code 2.1.283 also added /doctor prompt-audit for auditing these files. Check what your installed version does before relying on either, and read the proposed deletions the same way you’d read any diff.

After editing, run /context to confirm Claude loaded the file, then test the change by watching whether behavior actually shifts. Treat the file like code: review it when things go wrong, and prune it regularly.

One more trick

If Claude keeps skipping a single instruction, the guide suggests adding emphasis such as “IMPORTANT” to that line alone. It only works while it’s rare. Emphasize ten lines and none of them stand out.

Codex users have a version of the same problem: its AGENTS.md chain silently truncates at 32 KiB, as we explained in our Codex layering guide . Different tool, same rule. Short files get read.

Next step: copy your CLAUDE.md, delete everything that fails the one-question test, and work with the short version for a week. Anything you miss goes back in.