Nettoyer et optimiser un CLAUDE.md

# CLAUDE.md — Nettoyer et optimiser un CLAUDE.md de projet

> Contexte spécialisé pour Claude Code. À utiliser quand votre CLAUDE.md a grossi et que vous voulez l'auditer, le nettoyer, et réduire la consommation de tokens sans perdre en qualité de guidage.

---

## Quand utiliser ce contexte

- ✅ Votre CLAUDE.md dépasse 100-150 lignes et vous sentez qu'il grossit sans contrôle
- ✅ Claude recharge des instructions sans rapport avec la tâche en cours
- ✅ Vous venez d'ajouter plusieurs fonctionnalités et le fichier n'a jamais été revu
- ✅ Vous voulez découper un CLAUDE.md monolithique en fichiers spécialisés
- ❌ Votre CLAUDE.md fait moins de 50 lignes — il ne nécessite pas de restructuration
- ❌ Vous n'avez qu'un seul domaine fonctionnel — pas besoin de découpe

---

## Section 1 : Pourquoi le CLAUDE.md grossit

### Le pattern d'accumulation

Le CLAUDE.md grandit par ajout successif, jamais par réécriture. Chaque nouvelle règle est collée en bas. Au bout de quelques semaines d'utilisation intensive, il contient des couches sédimentaires : des conventions réglées depuis longtemps, des cas limites qui ne se reproduiront plus, des notes de contexte qui sont maintenant dans le code lui-même.

Le problème : Claude charge ce fichier **en entier** à chaque session. Si une section de 80 lignes ne concerne que le daemon de veille et qu'on travaille sur le CSS du blog, ces 80 lignes sont là, consommées, sans aucune valeur pour la tâche.

### Les trois catégories de bruit

1. **Règles obsolètes** — ce qui était vrai il y a 3 mois et a changé depuis (version de dépendance, structure de fichiers, noms d'endpoints)
2. **Règles implicites** — ce qui est déjà visible dans le code et que Claude redécouvre de toute façon (architecture de dossiers, conventions de nommage évidentes)
3. **Règles hors scope** — ce qui ne concerne qu'une partie du projet mais se retrouve dans le fichier global

---

## Section 2 : Prompts d'audit

### Prompt d'audit complet

Pour identifier ce qui peut être supprimé ou déplacé :

```text
Lis le CLAUDE.md et audite-le ligne par ligne.

Pour chaque règle ou section, classe-la dans une de ces catégories :
- ESSENTIEL : information non déductible du code, utilisée fréquemment
- DÉDUCTIBLE : déjà visible dans la structure du projet ou les fichiers existants
- OBSOLÈTE : fait référence à quelque chose qui a changé ou n'existe plus
- HORS SCOPE : ne concerne qu'un sous-domaine précis, candidat au découpage

Donne le résultat sous forme de tableau avec : ligne(s) concernée(s), catégorie, raison.
```

### Prompt de réécriture ciblée

Après l'audit, pour réécrire seulement ce qui doit l'être :

```text
Sur la base de l'audit, réécris le CLAUDE.md en :
1. Supprimant toutes les règles DÉDUCTIBLES et OBSOLÈTES
2. Gardant les règles ESSENTIELLES, formulées en 1 ligne maximum chacune quand possible
3. Remplaçant les sections HORS SCOPE par une note de référence : "> Voir CLAUDE.[domaine].md"
4. Conservant l'ordre logique : stack → conventions → déploiement → notes de domaine

Ne reformule pas ce qui n'a pas besoin de l'être. Touche le moins possible.
```

### Prompt de vérification post-nettoyage

```text
Compare le CLAUDE.md original et le CLAUDE.md nettoyé.

Pour chaque règle supprimée ou déplacée, confirme :
- qu'elle est soit présente ailleurs (code, autre fichier), soit vraiment obsolète
- qu'aucune règle métier non triviale n'a été perdue

Si tu trouves une règle supprimée qui aurait dû rester, signale-la explicitement.
```

---

## Section 3 : Règles de découpage

### Quand créer un fichier séparé

Créer `CLAUDE.[domaine].md` dès qu'un domaine remplit deux critères :
- Il représente plus de 30% du CLAUDE.md global
- Il n'est actif que pour une sous-partie du projet (un dossier, un service, un type de tâche)

Exemples courants : `CLAUDE.veille.md`, `CLAUDE.deploy.md`, `CLAUDE.api.md`, `CLAUDE.frontend.md`.

### Structure du fichier principal après découpage

Le CLAUDE.md principal doit rester sous 50 lignes. Structure cible :

```text
# Projet — résumé en 2 lignes

## Stack
- [techno principale] [version]
- [autres dépendances clés]

## Développement local
[commande pour lancer le projet]

## Déploiement
[commande + règles critiques en 3 lignes max]

## Domaines spécialisés
> [Domaine A] : voir `CLAUDE.domaine-a.md`
> [Domaine B] : voir `CLAUDE.domaine-b.md`
```

### Comment référencer sans charger automatiquement

Ne pas utiliser la syntaxe `@fichier` dans le CLAUDE.md principal — elle charge le fichier automatiquement à chaque session. Utiliser à la place une note en texte simple :

```text
> Système de veille : voir `CLAUDE.veille.md`
```

Claude lira ce fichier quand vous lui demandez explicitement. Le reste du temps, il n'existe pas dans le contexte.

---

## Section 4 : Optimiser ce qui reste

### Reformuler les règles longues

Chaque règle devrait tenir en une ligne. Les formulations longues signalent souvent :
- Une règle qui en cache deux (à séparer)
- Un exemple qui devrait être dans le code plutôt que dans le CLAUDE.md
- Un contexte qui n'est plus nécessaire

Avant :
```text
Ne jamais modifier le fichier registry.json directement depuis un script — toujours passer
par la fonction updateRegistry() dans lib/registry.js qui gère la validation du schéma et
le verrouillage concurrent pour éviter les race conditions.
```

Après :
```text
Modifications registry.json : toujours via `lib/registry.js:updateRegistry()` (validation + lock concurrent).
```

### Supprimer les règles redondantes avec le code

Si la règle dit "les fichiers de config sont dans `config/`" — et que le dossier `config/` existe bien — Claude le voit. La règle est inutile.

Si la règle dit "les logs sont en JSON avec le champ `level`" — et que c'est visible dans les fichiers existants — idem.

Garder uniquement ce qui n'est pas déductible : conventions qui dévient du standard, contraintes métier invisibles dans le code, décisions d'architecture qui semblent contre-intuitives.

### Tester l'effet du nettoyage

Après restructuration, ouvrir une nouvelle session Claude (`/clear`) et observer :
- Claude trouve-t-il les informations essentielles sans aide ?
- Pose-t-il des questions sur des points qui étaient dans les sections supprimées ?
- Le contexte initial de la session est-il significativement plus court ?

Si Claude pose des questions sur des points supprimés, ces points méritaient de rester.

---

## Section 5 : Checklist de nettoyage

```
□ Audit fait — chaque règle classée (ESSENTIEL / DÉDUCTIBLE / OBSOLÈTE / HORS SCOPE)
□ Règles DÉDUCTIBLES supprimées
□ Règles OBSOLÈTES supprimées ou mises à jour
□ Sections HORS SCOPE déplacées dans CLAUDE.[domaine].md
□ Références @fichier remplacées par des notes texte (> Voir CLAUDE.x.md)
□ CLAUDE.md principal < 50-60 lignes
□ Nouvelle session ouverte pour tester — Claude n'a pas perdu d'information critique
□ Fichiers spécialisés versionnés avec le projet
```

---

*Last updated: 2026-03 — Contexte associé à l'article [Optimiser la consommation de tokens Claude Code](https://www.web-developpeur.com/blog/optimiser-tokens-claude-code).*