How long should CLAUDE.md be? Trimming a CLAUDE.md that Claude ignores

Keep each CLAUDE.md under about 200 lines. Longer files use more context and Claude follows them less reliably. Cut what Claude can read from the code, move personal lines to CLAUDE.local.md or ~/.claude/CLAUDE.md, move folder-specific rules into .claude/rules/ with a paths filter, and turn long procedures into skills.

Why length matters

Every CLAUDE.md that loads at launch goes into context at the start of every session, before you type anything. A 600-line file costs that context every time, and the more lines compete for attention, the more likely one rule gets missed. Claude Code warns when a single file is over the recommended length, and also when several shorter files add up past a combined limit.

A trimming pass in five steps

  1. Delete what the repo already says. Folder trees, dependency lists and architecture overviews go stale and Claude can read the real thing. Keep pitfalls, reasons and conventions that differ from the defaults.
  2. Make every line checkable. "Use 2-space indentation" works; "format code properly" doesn't. If you can't tell whether Claude followed a line, rewrite it or cut it.
  3. Move personal lines out. Your editor habits and sandbox URLs belong in CLAUDE.local.md (this repo) or ~/.claude/CLAUDE.md (every repo), not in the file your team commits.
  4. Scope folder-specific rules. Rules that only matter in src/api/ go in .claude/rules/api.md with paths frontmatter, so they load only when Claude works on matching files.
  5. Move procedures and must-run steps. A ten-step release checklist fits a skill, which loads when needed. "Always run the formatter after editing" fits a hook, which runs every time instead of relying on Claude to remember.

Before and after

# Before: one 400-line CLAUDE.md
- full directory tree (80 lines)
- my preferred terminal colors
- API handler rules
- release checklist (40 lines)
- "always run prettier"

# After
CLAUDE.md                 build/test commands, conventions, pitfalls
CLAUDE.local.md           my preferences for this repo
.claude/rules/api.md      API rules, paths: src/api/**
.claude/skills/release/   release checklist
.claude/settings.json     PostToolUse hook that runs prettier

Check for conflicts across files

Trimming one file isn't enough if another file says the opposite. Your user file, the project file, a subfolder CLAUDE.md and the rules folder all stack into the same context, and when two of them disagree Claude may follow either. Read them side by side. Rulebook shows every level in one window and lets you drag a rule to the file it belongs in, which is most of this pass.

For where each file lives and the order they load, see where Claude Code looks for CLAUDE.md.

Questions

Is there a maximum CLAUDE.md size?
Anthropic recommends under 200 lines per file, and Claude Code warns at startup and in /status when a file is over the recommended length. It skips any file over 4 MiB entirely.
Do @imports make CLAUDE.md smaller?
They make it easier to read, not cheaper. An imported file loads into context together with the CLAUDE.md that imports it, so the total cost is the same.
Why does Claude ignore some of my CLAUDE.md?
CLAUDE.md is context, not enforced configuration. Long files, vague lines and instructions that contradict another file all lower how reliably Claude follows them. Run /context all to confirm the file loaded at all.
What should not go in CLAUDE.md?
Things Claude can read from the code itself (directory trees, dependency lists), multi-step procedures that fit better as skills, steps that must always run (use a hook), and permissions (use settings.json).
Can Claude Code trim CLAUDE.md for me?
Recent versions can. /doctor proposes trims for a checked-in CLAUDE.md, and /doctor prompt-audit looks for outdated, broken or conflicting instructions and proposes edits without changing files until you ask.

Rulebook for Mac

Rulebook is a native Mac app we are building for these files. It shows every CLAUDE.md and settings.json level side by side, lets you drag a rule from one file to another, and edits permissions without hand-written JSON. See the features.

Rulebook is in development and not available yet.

Email us about the launch

Related guides