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 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.
- 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
1---2name: optimizing-claude-md3description: 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.4---5
6# Optimizing CLAUDE.md
7
8## Overview
9
10Claude Code has a **priority hierarchy** for instructions. Most optimization failures come from putting rules in the wrong tier.
11
12## When to Use
13
14- CLAUDE.md exceeds 150 lines
15- Claude ignores rules you've written
16- Response formatting directives ("be concise") aren't working
17- Multiple sections marked CRITICAL/MANDATORY
18- User asks to optimize, restructure, or create CLAUDE.md
19
20## Priority Hierarchy
21
22| Tier | Mechanism | Priority | Purpose |
23|---|---|---|---|
24| **1. Output styles** | `~/.claude/output-styles/` | System prompt (highest) | Response format, tone, word limits |
25| **2. CLAUDE.md** | Project root | User message (medium) | Project rules, safety guardrails |
26| **3. .claude/rules/** | `.claude/rules/*.md` | Same as CLAUDE.md, auto-loaded | Topic-specific reference material |
27| **4. Auto memory** | `~/.claude/projects/*/memory/` | First 200 lines | Claude's own scratchpad — not for your instructions |
28
29**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.
30
31**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.
32
33**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.
34
35## Decision Framework: Keep, Move, or Cut
36
37For each section, ask in order:
38
391. **Response format rule?** (word limits, tone) → Output style
402. **Would removing it cause mistakes THIS session?** → No: move to `.claude/rules/` or cut. Yes: keep.
413. **Needed every session?** → Yes: keep. No: move to `.claude/rules/`
424. **Discoverable from codebase?** (package.json, READMEs) → Cut it.
43
44## Target: Under 150 lines (best teams run 60-80)
45
46LLMs follow ~150-200 instructions reliably. System prompt uses ~50. Every CLAUDE.md line competes for the rest. If everything is CRITICAL, nothing is.
47
48## Restructuring Workflow
49
501. **Audit** — Count lines. Classify each section: safety guardrail, project context, reference material, or response formatting.
512. **Extract formatting → output style** — Create `~/.claude/output-styles/<name>.md`. Activate with `/output-style <name>`.
52 ```markdown
53 ---
54 name: Concise
55 description: Minimal responses with hard word limits
56 keep-coding-instructions: true
57 ---
58 Max 150 words per response. Bullet points over paragraphs. No preamble before actions.
59 ```
603. **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.
614. **Apply U-shaped attention** — Top: safety guardrails. Middle: project context. Bottom: reference pointers.
625. **Deduplicate across tiers** — Check global CLAUDE.md, project CLAUDE.md, output style, and rules files. Same rule twice = wasted budget.
636. **Add anti-bloat line** at top: `**When adding to this file:** Be terse. Show commands, not prose.`
64
65## Content Classification
66
67| Content type | Destination |
68|---|---|
69| Word limits, banned phrases, tone | Output style |
70| Data-loss prevention rules | CLAUDE.md (top) |
71| Path handling gotchas | CLAUDE.md (top) |
72| Tech stack, project structure | CLAUDE.md (middle) |
73| Architecture patterns | CLAUDE.md (middle) |
74| Dev commands, build scripts | `.claude/rules/dev-commands.md` |
75| Testing examples, philosophy | `.claude/rules/testing.md` |
76| Agent workflows, slash commands | `.claude/rules/agent-os.md` |
77| Framework-specific setup | `.claude/rules/` with `paths:` frontmatter |
78| Code style enforcement | Linter config, not CLAUDE.md |
79
80## Common Mistakes
81
82| Mistake | Fix |
83|---|---|
84| "Be concise" in CLAUDE.md | Quantified limits in output style: "max 150 words" |
85| Everything marked CRITICAL | Reserve for data-loss prevention only |
86| Inline test examples (60+ lines) | Move to `.claude/rules/testing.md` |
87| Content moved to custom dirs | Use `.claude/rules/` (official, auto-loaded) |
88| Deleting anti-bloat instruction | Keep it — file will grow back without it |
89| Over-compressing copyable commands | Keep exact commands; compress prose around them |
90| Skipping output styles | Create output style first, then restructure CLAUDE.md |
91| Dumping everything into one rules file | Split by topic: `dev-commands.md`, `testing.md`, etc. Same decision framework applies to rules files. |
92
93## When NOT to Use
94
95- File under 100 lines and working well
96- Just adding one rule
97- Problem is coding behavior, not instruction following
majiayu000