CLAUDE.md Optimization Skill

Based on best practices from Writing a Good CLAUDE.md

Core Principle: LLMs Are Stateless

The only thing the model knows about your codebase is the tokens you put into it.

CLAUDE.md automatically enters EVERY conversation, making it the highest leverage point in the entire system. A flawed instruction cascades through research, planning, and implementation phases.

---

The Three Dimensions (WHAT / WHY / HOW)

Every CLAUDE.md should cover exactly these three dimensions:

Dimension	Content	Example
WHAT	Technology stack, architecture, codebase structure	"React + Bun monorepo with 5 plugins"
WHY	Project purpose, what each component does	"Frontend plugin handles UI development"
HOW	Build tools, verification, testing, workflow	"Run bun test, use /implement command"

---

Optimization Rules

Rule 1: Less Is More

❌ BAD:  500+ lines of detailed instructions
✅ GOOD: 60-300 lines of focused context (ideally < 150)
         HumanLayer's own CLAUDE.md is < 60 lines!

Research-Backed Data:

Metric	Value	Implication
Frontier LLM instruction limit	~150-200	Beyond this, compliance drops
Claude Code system prompt	~50 instructions	Already consumed!
Your remaining budget	~100-150	Every line counts

Critical Insight: As instruction count increases, compliance quality decreases uniformly across ALL instructions - not just the later ones. This means bloated CLAUDE.md degrades even your most important rules.

Model Size Matters:

• Frontier thinking models: Linear decay (graceful degradation)
• Smaller models: Exponential decay (rapid failure)
• ⚠️ Avoid smaller models for multi-step tasks or complex plans

Rule 2: Progressive Disclosure

Don't cram everything into CLAUDE.md. Create an agent_docs/ directory for task-specific details:

agent_docs/
├── commands-and-agents.md    # Detailed command/agent reference
├── architecture-guide.md     # Deep architectural documentation
├── api-patterns.md           # API conventions and examples
├── testing-strategy.md       # Testing approaches
└── release-process.md        # Release workflow details

Use pointers, not copies:

## Detailed Documentation

| Topic | Reference |
|-------|-----------|
| Commands | [agent_docs/commands-and-agents.md](agent_docs/commands-and-agents.md) |
| Architecture | [agent_docs/architecture-guide.md](agent_docs/architecture-guide.md) |

Rule 3: LLM Attention Distribution

LLMs bias towards instructions at the peripheries:

┌─────────────────────────────────────────────────────┐
│  HIGH ATTENTION                                     │
│  ├── System prompt (Claude Code)                   │
│  └── CLAUDE.md (beginning)                         │
├─────────────────────────────────────────────────────┤
│  LOW ATTENTION                                      │
│  └── Middle of context window                       │
├─────────────────────────────────────────────────────┤
│  HIGH ATTENTION                                     │
│  └── Recent user messages (end)                     │
└─────────────────────────────────────────────────────┘

Implication: Put your most critical rules at the TOP of CLAUDE.md, not buried in the middle.

Rule 4: Claude Is NOT a Linter

Never put style rules in CLAUDE.md:

• ❌ "Use 2-space indentation"
• ❌ "Always use semicolons"
• ❌ "Prefer const over let"

Instead:

• Use Biome/ESLint/Prettier for formatting
• Claude learns patterns from existing code (in-context learning!)
• Well-structured code demonstrates conventions

Advanced Technique: Stop Hook

Set up a Stop Hook to run formatter after Claude finishes:

// .claude/settings.local.json
{
  "hooks": {
    "Stop": [{
      "matcher": "*.{ts,tsx,js,jsx}",
      "command": "biome check --fix --unsafe"
    }]
  }
}

This separates implementation from formatting - both improve as a result.

Rule 5: Never Auto-Generate

❌ DON'T: Use /init output directly
✅ DO:    Use /init as starting point, then manually optimize

Why: Every line has multiplicative impact. Auto-generated content includes noise that pollutes every conversation.

Rule 6: Universal Applicability Only

Only include instructions that apply to EVERY task in this project:

• ✅ "This is a TypeScript monorepo"
• ✅ "Run tests with bun test"
• ❌ "When implementing auth, use JWT" (task-specific → agent_docs/)
• ❌ Detailed API patterns (task-specific → agent_docs/)

---

Optimization Workflow

When user requests CLAUDE.md optimization, follow this workflow:

Phase 1: Analysis

# Count current lines
wc -l CLAUDE.md

# Identify sections
grep "^##" CLAUDE.md

Classify each section:

• 🟢 KEEP (core WHAT/WHY/HOW)
• 🟡 MOVE (detailed → agent_docs/)
• 🔴 DELETE (redundant, outdated, task-specific noise)

Phase 2: Create agent_docs Structure

mkdir -p agent_docs

Move detailed content to appropriate files:

Content Type	Target File
Command/Agent lists	agent_docs/commands-and-agents.md
Architecture details	agent_docs/architecture-guide.md
API patterns/examples	agent_docs/api-patterns.md
Tool-specific guides	agent_docs/{tool}-guide.md
Version history	agent_docs/release-history.md
Protocol documentation	agent_docs/{protocol}-protocol.md

Phase 3: Rewrite CLAUDE.md

Target structure (60-150 lines):

# Project Context for Claude Code

## Project Overview (WHAT)
[2-5 lines: name, purpose, owner]

## What This Repository Contains (WHY)
[Table or bullet list: components and their purposes]
[10-20 lines max]

## Directory Structure
[Simplified tree, 10-15 lines]

## How to Work with This Project (HOW)
[Quick setup, env vars, dependencies]
[15-25 lines]

## Key Architecture Decisions
[3-5 bullet points of universal principles]

## Important Files
[Table: role → files]

## Detailed Documentation (Progressive Disclosure)
[Table: topic → agent_docs/ reference]

## Project Rules
[3-5 universal rules that apply to EVERY task]

Phase 4: Verification

# Verify line count
wc -l CLAUDE.md  # Should be 60-200 lines

# Verify agent_docs created
ls -la agent_docs/

# Verify no orphaned references
grep -r "agent_docs/" CLAUDE.md

---

Anti-Patterns to Avoid

Anti-Pattern	Why It's Bad	Fix
500+ lines	Degrades all instructions	Split to agent_docs/
Code examples inline	May become outdated	Use file:line references
Version history in CLAUDE.md	Not universal	Move to agent_docs/release-history.md
Detailed protocols	Task-specific	Move to agent_docs/{protocol}.md
Style/linting rules	Use proper tools	Remove, use Biome/ESLint
Auto-generated content	Contains noise	Manual curation required

---

Quick Reference: Section Classification

🟢 KEEP in CLAUDE.md

• Project name, purpose, owner
• High-level directory structure
• Environment variables (list only)
• System dependencies
• Universal commands (bun test, bun build)
• Design principles (3-5 points)
• Important file references (table)
• Progressive disclosure table
• 3-5 universal project rules

🟡 MOVE to agent_docs/

• Detailed command documentation
• Agent specifications
• API patterns and examples
• Tool-specific guides (claudemem, etc.)
• Protocol documentation
• Version history and changelog details
• Architecture deep-dives
• Testing strategies

🔴 DELETE

• Redundant information
• Outdated content
• Task-specific instructions
• Inline code snippets (use references)
• Style/formatting rules
• Verbose explanations

---

Example Transformation

Before (982 lines):

## Commands and Agents Available
### Frontend Plugin
**Agents:**
- `typescript-frontend-dev` - TypeScript/React implementation (Sonnet)
- `frontend-architect` - Architecture planning (Sonnet)
[... 100+ lines of agent details ...]

## Claudemem AST Structural Analysis (v0.3.0)
[... 150+ lines of tool documentation ...]

## Parallel Multi-Model Execution Protocol
[... 180+ lines of protocol details ...]

After (154 lines):

## Detailed Documentation (Progressive Disclosure)

| Topic | Documentation |
|-------|---------------|
| Commands & Agents | [agent_docs/commands-and-agents.md](agent_docs/commands-and-agents.md) |
| Claudemem Guide | [agent_docs/claudemem-guide.md](agent_docs/claudemem-guide.md) |
| Parallel Execution | [agent_docs/parallel-execution-protocol.md](agent_docs/parallel-execution-protocol.md) |

---

Success Metrics

After optimization, verify:

• CLAUDE.md is 60-200 lines (ideally < 150)
• Contains only WHAT/WHY/HOW
• agent_docs/ directory exists with detailed docs
• Progressive disclosure table references agent_docs/
• No inline code examples (use file references)
• No style/linting rules
• No version history details
• All content is universally applicable