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:

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:

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:

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

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