Optimizing CLAUDE.md

Overview

Claude Code has a priority hierarchy for instructions. Most optimization failures come from putting rules in the wrong tier.

When to Use

• CLAUDE.md exceeds 150 lines
• Claude ignores rules you've written
• Response formatting directives ("be concise") aren't working
• Multiple sections marked CRITICAL/MANDATORY
• User asks to optimize, restructure, or create CLAUDE.md

Priority Hierarchy

The #1 mistake: Putting response formatting rules in CLAUDE.md. They belong in an output style (system prompt level). CLAUDE.md formatting rules get ignored under pressure.

Auto memory note: Don't put instructions in MEMORY.md — it's Claude's scratchpad. During optimization, ignore it unless your instructions leaked into it.

Global vs project: Project CLAUDE.md rules take precedence over ~/.claude/CLAUDE.md. Put personal preferences in global, project rules in project. Don't duplicate between them.

Decision Framework: Keep, Move, or Cut

For each section, ask in order:

1. Response format rule? (word limits, tone) → Output style
2. Would removing it cause mistakes THIS session? → No: move to .claude/rules/ or cut. Yes: keep.
3. Needed every session? → Yes: keep. No: move to .claude/rules/
4. Discoverable from codebase? (package.json, READMEs) → Cut it.

Target: Under 150 lines (best teams run 60-80)

LLMs follow ~150-200 instructions reliably. System prompt uses ~50. Every CLAUDE.md line competes for the rest. If everything is CRITICAL, nothing is.

Restructuring Workflow

1. Audit — Count lines. Classify each section: safety guardrail, project context, reference material, or response formatting.
2. Extract formatting → output style — Create ~/.claude/output-styles/<name>.md. Activate with /output-style <name>.
   markdownCopy

   ---
   name: Concise
   description: Minimal responses with hard word limits
   keep-coding-instructions: true
   ---
   Max 150 words per response. Bullet points over paragraphs. No preamble before actions.
   

3. Move reference material → .claude/rules/ — Auto-loads at same priority. Scope to paths with paths: frontmatter when topic-specific. Never use custom dirs (_docs/, references/) — Claude won't auto-load them. Caveat: Path-scoped rules only load for matching files — never put safety rules in path-scoped files.
4. Apply U-shaped attention — Top: safety guardrails. Middle: project context. Bottom: reference pointers.
5. Deduplicate across tiers — Check global CLAUDE.md, project CLAUDE.md, output style, and rules files. Same rule twice = wasted budget.
6. Add anti-bloat line at top: **When adding to this file:** Be terse. Show commands, not prose.

Content Classification

Common Mistakes

When NOT to Use

• File under 100 lines and working well
• Just adding one rule
• Problem is coding behavior, not instruction following