CLAUDE.md Maintainer (Smart Router)

Purpose

Context-aware guidance for maintaining and improving CLAUDE.md files. Helps ensure the file stays effective, concise, and follows best practices for LLM instruction files.

When Auto-Activated

• Editing or discussing CLAUDE.md
• Keywords: claude.md, project instructions, onboarding claude, context file
• Discussing documentation structure for AI assistants

🚨 CRITICAL RULES

1. Keep under 300 lines - Research shows LLMs handle ~150-200 instructions reliably; performance degrades with more
2. Never auto-generate - Manually craft each line; auto-generated content often contains noise
3. Universal applicability only - Remove task-specific or narrow-scope guidance
4. File references over code snippets - Code embeds become outdated; paths stay accurate

📊 Effective CLAUDE.md Principles

What To Include (WHAT, WHY, HOW)

What To Exclude

• Code style guidelines → Use linters instead (SwiftFormat, ESLint, etc.)
• Exhaustive command references → Point to tool documentation
• Task-specific instructions → Put in skills or separate docs
• Code snippets → Use file:line references instead

🎯 Progressive Disclosure Pattern

Level 1: CLAUDE.md (~100-150 lines ideal, max 300)
├─ Critical rules (must-follow behaviors)
├─ Quick start (essential commands only)
├─ High-level architecture
└─ Pointers to Level 2 and 3

Level 2: Skills (.claude/skills/)
├─ Domain-specific quick references
├─ Decision trees and workflows
└─ "→ Routes to" comprehensive docs

Level 3: Specialized Guides
├─ Complete technical documentation
├─ Full examples and edge cases
└─ Troubleshooting guides

📋 Quick Audit Checklist

When reviewing CLAUDE.md:

• Line count under 300? (wc -l CLAUDE.md)
• No duplicate rules? (Search for repeated concepts)
• Code snippets minimized? (Replace with file path references)
• Narrow-scope items removed? (Move to skills)
• Critical rules consolidated? (Single authoritative location)
• File references current? (Paths still valid)
• Common mistakes documented? (Actual failures, not hypotheticals)

🔄 Optimization Workflow

Reducing Line Count

1. Find duplicates: Search for repeated concepts

``bash # Find potential duplicates grep -n "NEVER" CLAUDE.md | head -20 ``

1. Consolidate rules: Move all critical rules to one section

1. Replace code with references:

``markdown # ❌ Before (takes 10+ lines) ### Typography `swift AnytypeText("Title", style: .uxTitle1Semibold) AnytypeText("Body", style: .bodyRegular) ``

# ✅ After (1 line) Typography → path/to/TYPOGRAPHY_MAPPING.md ```

1. Move narrow guidance to skills: If it applies to < 20% of tasks, it's a skill

Adding New Guidance

Before adding, ask:

1. Does this apply to most tasks? (If no → skill or specialized doc)
2. Is there existing guidance? (If yes → consolidate, don't duplicate)
3. Can a linter/tool enforce this? (If yes → use the tool instead)
4. Will this code example outdated quickly? (If yes → use file reference)

⚠️ Common Mistakes

Accumulating Hotfixes

# ❌ WRONG - Adding one-off rules
### Special Note (2025-01-15)
Remember to always check X when doing Y...

# ✅ CORRECT - Add to appropriate skill or remove

Duplicating Rules

# ❌ WRONG - Same rule in 3 places
## Critical Rules: NEVER add AI signatures
## Pre-Commit: NO AI signatures
## PR Format: No "Generated with Claude"

# ✅ CORRECT - Single consolidated rule
## Critical Rules
2. **NEVER add AI signatures anywhere** - No Co-Authored-By, no emoji signatures

Embedding Code That Outdates

# ❌ WRONG - Code will outdated

Image(asset: .X32.qrCode) // What if asset name changes?

# ✅ CORRECT - File reference stays accurate
**Icons** → `Modules/Assets/.../ImageAsset.swift:45`

📚 Research & Best Practices

Source: Based on industry practices and LLM behavior research

Key Findings

• LLMs handle ~150-200 instructions reliably
• Performance degrades with additional instructions
• Irrelevant context may be ignored entirely (Claude adds "this context may or may not be relevant")
• Code snippets in docs become maintenance burden
• Progressive disclosure reduces context overhead

Recommended Metrics

🔗 Related

• .claude/skills/README.md - Skills system overview
• .claude/skills/skills-manager/SKILL.md - Managing the skills system
• Progressive disclosure architecture documentation

Navigation: This skill helps maintain CLAUDE.md quality. For skills system management, see skills-manager. For adding new skills, see .claude/skills/README.md.