claudemd-maintainer

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)

Category	Include	Avoid
Stack	Technologies, architecture overview	Exhaustive dependency lists
Critical Rules	Must-follow behaviors (consolidated)	Duplicate rules across sections
Quick Commands	Essential build/run commands	Full command reference
File References	Paths to detailed guides	Embedded code that can outdated
Common Mistakes	Documented actual failures	Hypothetical warnings

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

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

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

3. Replace code with references:

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

   ✅ After (1 line)

   Typography → path/to/TYPOGRAPHY_MAPPING.md

4. 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
```swift
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
| Metric | Target | Max |
|--------|--------|-----|
| Total lines | 100-150 | 300 |
| Code blocks | 2-4 | 6 |
| Critical rules | 3-5 | 10 |
| Sections | 6-8 | 12 |

## 🔗 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`.