Optimizing CLAUDE.md
optimizing-claude-md
Use when CLAUDE.md is bloated or ineffective. Use when Claude ignores instructions, file exceeds 150 lines, response formatting rules aren't working, or user asks to optimize/restructure their Claude Code configuration.
SKILL.md
Full skill instructions
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
| Tier | Mechanism | Priority | Purpose |
|---|---|---|---|
| 1. Output styles | ~/.claude/output-styles/ | System prompt (highest) | Response format, tone, word limits |
| 2. CLAUDE.md | Project root | User message (medium) | Project rules, safety guardrails |
| 3. .claude/rules/ | .claude/rules/*.md | Same as CLAUDE.md, auto-loaded | Topic-specific reference material |
| 4. Auto memory | ~/.claude/projects/*/memory/ | First 200 lines | Claude's own scratchpad — not for your instructions |
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:
- Response format rule? (word limits, tone) → Output style
- Would removing it cause mistakes THIS session? → No: move to
.claude/rules/or cut. Yes: keep. - Needed every session? → Yes: keep. No: move to
.claude/rules/ - 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
- Audit — Count lines. Classify each section: safety guardrail, project context, reference material, or response formatting.
- Extract formatting → output style — Create
~/.claude/output-styles/<name>.md. Activate with/output-style <name>.--- 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. - Move reference material →
.claude/rules/— Auto-loads at same priority. Scope to paths withpaths: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. - Apply U-shaped attention — Top: safety guardrails. Middle: project context. Bottom: reference pointers.
- Deduplicate across tiers — Check global CLAUDE.md, project CLAUDE.md, output style, and rules files. Same rule twice = wasted budget.
- Add anti-bloat line at top:
**When adding to this file:** Be terse. Show commands, not prose.
Content Classification
| Content type | Destination |
|---|---|
| Word limits, banned phrases, tone | Output style |
| Data-loss prevention rules | CLAUDE.md (top) |
| Path handling gotchas | CLAUDE.md (top) |
| Tech stack, project structure | CLAUDE.md (middle) |
| Architecture patterns | CLAUDE.md (middle) |
| Dev commands, build scripts | .claude/rules/dev-commands.md |
| Testing examples, philosophy | .claude/rules/testing.md |
| Agent workflows, slash commands | .claude/rules/agent-os.md |
| Framework-specific setup | .claude/rules/ with paths: frontmatter |
| Code style enforcement | Linter config, not CLAUDE.md |
Common Mistakes
| Mistake | Fix |
|---|---|
| "Be concise" in CLAUDE.md | Quantified limits in output style: "max 150 words" |
| Everything marked CRITICAL | Reserve for data-loss prevention only |
| Inline test examples (60+ lines) | Move to .claude/rules/testing.md |
| Content moved to custom dirs | Use .claude/rules/ (official, auto-loaded) |
| Deleting anti-bloat instruction | Keep it — file will grow back without it |
| Over-compressing copyable commands | Keep exact commands; compress prose around them |
| Skipping output styles | Create output style first, then restructure CLAUDE.md |
| Dumping everything into one rules file | Split by topic: dev-commands.md, testing.md, etc. Same decision framework applies to rules files. |
When NOT to Use
- File under 100 lines and working well
- Just adding one rule
- Problem is coding behavior, not instruction following