Optimiser CLAUDE.md avec scoring A-F

Contexte

Votre projet a un CLAUDE.md mais vous ne savez pas s’il est optimal pour Claude Code. Claude-md-optimizer l’audite avec le plugin officiel Anthropic /claude-md-improver (scoring 100 points, Grade A-F) et ajoute des vérifications ulk-spécifiques (taille, conflits, rules/).

Prérequis

• Projet avec CLAUDE.md ou .claude/CLAUDE.md
• Plugin officiel Anthropic : claude-md-management installé
• Accès Read au projet

Étapes

1. Invocation audit CLAUDE.md

Lancez Claude-md-optimizer :

/ulk:claude-md-optimizer

ou

Optimize claude.md

ou

Audit claude.md

Claude-md-optimizer démarre Phase 0 (Détection).

2. Phase 0 — Détection

Agent vérifie l’existence de :

ls -la CLAUDE.md ./.claude/CLAUDE.md 2>/dev/null
ls -la ./.claude/rules/*.md 2>/dev/null

Rapport :

=== Détection ===

✅ CLAUDE.md trouvé : ./CLAUDE.md (247 lignes)
⚠️ Rules/ folder : 2 fichiers
❌ Auto memory : Non configuré

Si absent → Phase 1A (Création). Si présent → Phase 1B (Audit).

3. Phase 1B — Audit via plugin officiel

Claude-md-optimizer invoque le plugin officiel :

/claude-md-improver

Le plugin exécute automatiquement :

=== CLAUDE.md Quality Audit ===

Scanning CLAUDE.md (247 lignes)
Checking sections, commands, architecture docs...
Analyzing actionability and specificity...

Results:

4. Scoring officiel (100 points, Grade A-F)

Rapport détaillé du plugin :

=== GRADE OFFICIEL ===

GRADE : B (77/100)

Breakdown (100 points total):
  Commands          : 18/20  (build, test, lint documentés)
  Architecture      : 18/20  (structure claire, patterns expliqués)
  Non-obvious items : 12/15  (gotchas partiels)
  Conciseness       : 12/15  (quelques sections trop longues)
  Currency          : 14/15  (à jour, minor: React version outdated)
  Actionability     : 15/15  (instructions spécifiques)

Grade explanation:
  ✅ Strong : Commands précis, actionability excellente
  ⚠️  Gaps  : Non-obvious patterns manquants, size optimizable

Grille des grades :

A (85-100)  : Excellent — CLAUDE.md de référence
B (70-84)   : Bon — quelques améliorations possibles
C (55-69)   : Moyen — sections manquantes ou vagues
D (40-54)   : Faible — nécessite refonte significative
F (0-39)    : Insuffisant — quasi inutile pour Claude

5. Phase 2 — Métriques complémentaires ulk

Au-delà du score officiel, Claude-md-optimizer ajoute des vérifications spécifiques à ulk :

# Taille
wc -l CLAUDE.md  → should be < 200 lines

# Doublons avec rules/
grep -h "^##" CLAUDE.md ./.claude/rules/*.md | sort | uniq -d

# Instructions vagues
grep -i "properly\|nicely\|well\|correct\|bon\|propre" CLAUDE.md

# Sections path-specific
grep -n "dans src/\|in src/" CLAUDE.md  → should extract to rules/

# Imports valides
grep "@" CLAUDE.md | while read import; do [ -f "${import#@}" ] || echo "BROKEN: $import"; done

# Conflits potentiels
(grep "tabs\|tabs" CLAUDE.md; grep "spaces" CLAUDE.md) | wc -l  → should be < 2

Rapport ulk complémentaire :

=== MÉTRIQUES ULK COMPLÉMENTAIRES ===

| Métrique | Valeur | Status |
|----------|--------|--------|
| Lignes totales | 247 | 🟡 (cible < 200) |
| Sections (##) | 8 | ✅ (3-10 idéal) |
| Instructions vagues | 2 | ⚠️ ("properly", "correct") |
| Instructions spécifiques | 18 | ✅ |
| Doublons avec rules/ | 0 | ✅ |
| Imports @path | 2 | ✅ (valides) |
| Conflits détectés | 0 | ✅ |
| Sections path-specific | 1 | 🟡 ("dans src/components/...") |

Score ulk complémentaire : 8/10 🟡 OPTIMIZABLE

6. Phase 3 — Rapport synthétique

Rapport combinant score officiel + métriques ulk :

## 📋 Audit CLAUDE.md

### Grade officiel : B (77/100)

Commands: 18/20 ✅ Architecture: 18/20 ✅ Non-obvious: 12/15 ⚠️ Conciseness: 12/15 ⚠️ Currency: 14/15 ✅ Actionability: 15/15 ✅

### Métriques ulk : 8/10 🟡
- ⚠️ 247 lignes (target: < 200)
- ✅ Sections bien structurées
- ⚠️ 2 instructions vagues à clarifier
- ✅ Imports valides
- 🟡 1 bloc path-specific à extraire en rules/

### Findings (plugin + ulk)
1. **Conciseness** (plugin) : Section "Testing" trop longue (15 lignes → 8)
2. **Instructions vagues** (ulk) : "Format code properly" → "Use 2-space indentation, no trailing whitespace"
3. **Non-obvious patterns** (plugin) : Ajouter section "Gotchas" — async/await patterns, dependency issues
4. **Path-specific** (ulk) : Bloc "Dans src/components, utiliser..." → extraire en .claude/rules/components.md
5. **Currency** (plugin) : React version mentionnée (18.0) → vérifier et mettre à jour (18.2 disponible)

### Recommandations
- [ ] Réduire taille : extraire rules/, condenser sections
- [ ] Clarifier instructions vagues
- [ ] Ajouter non-obvious patterns
- [ ] Mettre à jour versions

7. Phase 4 — Optimisation (optionnel)

Si l’utilisateur approuve, Claude-md-optimizer peut appliquer les optimisations via le plugin officiel :

/claude-md-management:revise-claude-md

Ou proposer des modifications manuelles :

Avant (vague) :

## Conventions
- Format code properly
- Write good tests

Après (spécifique) :

## Conventions
- Use 2-space indentation, no trailing whitespace
- Run `npm test` before commit, target 80% coverage minimum

8. Fichiers extraits en rules/

Si path-specific détecté, proposer créer .claude/rules/ :

# .claude/rules/components.md
---
paths:
  - "src/components/**/*.tsx"
---

# Component Guidelines
- Functional components only (no class)
- Export as named exports
- Use `React.memo()` for expensive renders
- PropTypes or TypeScript interfaces required

9. Auto Memory

Vérifier et proposer configuration :

=== AUTO MEMORY ===

Current: Disabled

Recommendation:
  Enable autoMemoryEnabled in ~/.claude/settings.json
  This allows Claude to capture learnings across sessions
  Max 200 lines in MEMORY.md

Variantes

• Variante A — Audit uniquement : Pas d’application, juste rapport
• Variante B — Application via plugin : Utiliser /claude-md-management:revise-claude-md
• Variante C — Scheduled audits : /schedule claude-md-optimizer --cron "0 9 1 * *" (1er du mois)
• Variante D — Post-change audit : Après blackemperor audit, relancer pour sync

Agents enchaînés

Flux typique : shuri (01) spec → claude-md-optimizer (42) audit CLAUDE.md → lovecraft (47) memory loop.

Troubleshooting

Symptôme	Cause probable	Résolution
Plugin not found	/claude-md-improver absent	Installer via marketplace
Grade trop bas	CLAUDE.md très générique	Ajouter commandes exactes, gotchas
Imports cassés	Fichiers @path supprimés	Vérifier chemins
Auto memory conflicts	MEMORY.md > 200 lignes	Réorganiser et archiver

Voir aussi

• agents/audit/42-claude-md-optimizer.md — agent complet
• https://code.claude.com/docs/en/memory — official reference
• /claude-md-improver — official plugin
• /claude-md-management:revise-claude-md — sync plugin