Trim Your CLAUDE.md

We cut one CLAUDE.md from 199 to 114 lines and another from 120 to 52. Each model generation turns old scaffolding into debt.

Our global CLAUDE.md was 199 lines and one project file was 120. When we moved to a newer model generation, we cut them to 114 and 52. Here is what we cut, what we kept, and what we built instead.

The official target: under 200 lines

Claude Code’s docs recommend under 200 lines per CLAUDE.md; longer files use more context and reduce adherence (https://code.claude.com/docs/en/memory, checked 2026-10-16). @path imports help organization but still load at launch, so they don’t reduce context (same source).

That 200 is a guideline for CLAUDE.md. The auto-memory index MEMORY.md has a separate hard cap: only its first 200 lines or 25KB load. We cover how to design around it in Designing Agent Memory.

wc -l ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/rules/*.md 2>/dev/null

What we removed

• Step-by-step verification procedures.
• “Think carefully” lines. Reasoning depth is set with effort, not prose.
• Anything the code already tells you: directory layouts, dependency lists.

The docs say /doctor proposes cutting exactly that last category (same source). New instructions get a goal and constraints only, with no model names or effort values baked in.

What we kept

• Reasons behind decisions the code can’t show.
• Traps we have actually hit.
• Conventions that differ from tool defaults.
• A short list of things not to propose, so new sessions stop reviving rejected ideas.

Move must-follow rules into hooks

The docs call CLAUDE.md context, not enforced configuration, and point to PreToolUse hooks for hard blocks (same source). We added a hook that asks before destructive Git operations and rejects malformed commits; the CLAUDE.md section shrank to one line.

Hooks need measuring too. A hook guarding memory writes only matched Write and Edit. Over 30 days, 77 writes slipped past it, because about 85% of actions in auto mode went through Bash. Pick matchers from real call logs.

Hook patterns and the gaps we measured: Claude Code hooks in practice.

Trim the always-loaded descriptions

Skill descriptions load every session as well. Demote unused skills to manual-only, and decide what counts as unused by counting recent calls rather than guessing. The docs also recommend moving workflow-specific instructions from CLAUDE.md into skills, which load on demand (https://code.claude.com/docs/en/costs, checked 2026-10-16).

MCP servers add to context too: MCP context cost.

Audit with a command

/doctor prompt-audit looks for instructions written for older models, references to missing files, and contradictions, and proposes edits without changing files until you ask. It needs v2.1.283 or later (https://code.claude.com/docs/en/memory, checked 2026-10-16). Our test box had 2.1.301 (claude --version, 2026-10-16).

What to add after a failure, including when to quit and where to restart: Don’t Make It Fix the Same Thing Thrice.

Summary

• Keep CLAUDE.md under 200 lines; @ imports don’t save context.
• After a model change, delete procedures and “think carefully.”
• Put must-follow rules in hooks, and size hook matchers from real data.
• Drop unused skill descriptions from always-loaded context.