Claude Code

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

ContentWhere it belongsWhy
Pitfalls, the reason behind a rule, conventions that differ from tool defaults, concrete commandsStays 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 overviewsDeleteClaude 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 migrationA skillLoads when you invoke it, or when Claude finds it relevant to the prompt.
Something that must always happen, or neverA hookRuns at a fixed point, whatever Claude decides.
Notes for the people who maintain the fileAn HTML commentRemoved 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:

.claude/rules/api.md
---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

A 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

  1. /context all lists the memory files that loaded. If a file is missing there, Claude cannot see it.
  2. /doctor prompt-audit looks 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.
  3. wc -m path/to/CLAUDE.md counts 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.
Claude Code
/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

Then 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

More: Lost context after /compact · Cursor Memories removed · All docs