Your CLAUDE.md is too long. What to cut, and where the rest goes
It started with 30 lines: the test command, the code style, one warning about the database. Every time Claude got something wrong, you added a line. Now the file has 600, Claude Code warns about it at startup, and the rule you added last week is the one it ignores.
The file did its job too well. This page shows what Claude Code does with a long CLAUDE.md, taken from its documentation, and where each kind of line belongs instead.
The short answer
The Claude Code docs advise under 200 lines per CLAUDE.md: "Longer files consume more context and reduce adherence." To get there, delete what Claude can read from the code, and move the rest to where it loads only when needed. Instructions for one part of the code go into path rules, workflows into skills, and must-always steps into hooks.
Splitting the file with @path imports does not help. The docs: imports "help you organize a long file but don't reduce its context cost".
What happens past 200 lines
- Each line counts for less. Claude reads the whole file at launch, but it treats it as context, not as configuration. The more lines compete, the less reliably each one is followed.
- Contradictions creep in. A line from March and a line from October say different things. The docs: "Claude may pick one arbitrarily."
- Claude Code warns you. A file over the recommended length shows a warning at startup and in
/status. So do several files that each stay short but add up past a combined limit. - Some files arrive cut off. A CLAUDE.md in a subdirectory, or a rule that loads on demand, has a per-file limit: 40,000 characters with a 200K context window. Past it, Claude gets only the start, plus a note to read the rest.
- Very large files are skipped. Claude Code skips a file over 4 MiB and loads none of it.
What stays, what moves
| Content | Where it belongs | Why |
|---|---|---|
| Pitfalls, the reason behind a rule, conventions that differ from tool defaults, concrete commands | Stays in CLAUDE.md | /doctor keeps pitfalls, reasons and conventions when it trims. A concrete command is the docs' own example of a good line. |
| Directory layout, dependency lists, architecture overviews | Delete | Claude can read them from the code. /doctor cuts them. |
| Instructions for one part of the code: the API, the migrations | .claude/rules/ with paths: | Loads only when Claude works with a matching file. |
| A workflow you run now and then: release, deploy, a migration | A skill | Loads when you invoke it, or when Claude finds it relevant to the prompt. |
| Something that must always happen, or never | A hook | Runs at a fixed point, whatever Claude decides. |
| Notes for the people who maintain the file | An HTML comment | Removed before the file reaches Claude, so it costs nothing. |
From How Claude remembers your project in the Claude Code docs, as of 6 November 2026. Hooks: every event and what it can block.
Path rules: the biggest win
In most long files, a large share of the lines is about one area: the API, the frontend, the migrations. Move each area into its own file under .claude/rules/ and give it a paths field. It then loads only when Claude reads, writes or edits a matching file. This example is from the Claude Code docs:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation commentsA rule without paths loads at launch like CLAUDE.md itself, so it saves nothing. Only the paths field makes the difference.
Three commands to check
/context alllists the memory files that loaded. If a file is missing there, Claude cannot see it./doctor prompt-auditlooks for outdated instructions, references to files that no longer exist, and files that contradict each other. You get proposed edits; nothing changes until you agree. It needs Claude Code 2.1.283 or later.wc -m path/to/CLAUDE.mdcounts the characters, to compare a subdirectory file with the 40,000-character limit.
The part that keeps growing
After the cleanup, one kind of line keeps coming back: the fixes. "Build fails with a cache miss: the key includes the lockfile hash." "The staging deploy needs the migration first." Each is too specific to load in every session, and a team adds several a week.
They are not instructions, they are experience. They work best in a notes file outside CLAUDE.md, with a UserPromptSubmit hook that brings in only the notes that fit the current prompt. What to write in such a note: Lessons learned for coding agents. Why the same bug keeps coming back without one: AI coding agent keeps making the same mistake.
With cachly
cachly keeps that experience out of CLAUDE.md:
- When a turn in Claude Code ends with a fix, cachly's Stop hook records it as a lesson: the symptom, the cause, what failed, the command that worked.
- Before each prompt, the hook adds up to three lessons that match. CLAUDE.md stays short, and the fix from last month is there when the same error shows up.
- Lessons live in your instance. Your team gets them too, and so do Cursor and Copilot.
/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachlyThen turn on auto-update once: /plugin → Marketplaces → cachly → Enable auto-update. Claude Code leaves it off for marketplaces outside Anthropic's own, and the hooks update only with the plugin.
Lessons are stored on servers in the EU. What leaves your machine, and where it goes.
Sources
- Claude Code docs: Write effective instructions (under 200 lines, imports don't reduce context, contradictions)
- Claude Code docs: My CLAUDE.md is too large (4 MiB, startup warning, what /doctor trims)
- Claude Code docs: Claude ignores the end of my subdirectory CLAUDE.md (per-file limit, wc -m)
- Claude Code docs: Path-specific rules
- Claude Code docs: Audit your instruction files (/doctor prompt-audit)
More: Lost context after /compact · Cursor Memories removed · All docs