MISTAKES.md et Claude Code : transformer une erreur répétée en règle

Dans un dépôt complexe, Claude Code rencontrera inévitablement des particularités peu visibles : définitions TypeScript obsolètes, dépendances d’exécution cachées ou comportements propres au bundler. Corriger la même erreur à répétition dans le chat gaspille contexte et temps. À l’inverse, placer des transcriptions de sessions de plusieurs pages dans les instructions encombre le prompt et dégrade l’attention du modèle.

Une approche pratique consiste à garder un MISTAKES.md léger à la racine du dépôt. Il ne contient que les incidents reproductibles, les causes vérifiées et les actions de prévention. Ces éléments sont ensuite promus vers les tests du projet, les règles de linter et la configuration persistante.

---

1. MISTAKES.md ou transcription de session

Ne confondez pas un journal d’incidents avec une transcription brute du terminal :

Dimension	Transcription de session	Journal d’incidents MISTAKES.md
Volume	Des milliers de lignes d’appels d’outils et d’étapes intermédiaires	5 à 10 lignes structurées par incident
But	Débogage et audit d’une seule exécution	Base de référence pour empêcher les récidives
Secrets	Peut capturer variables d’environnement ou tokens bruts	Strictement interdit : aucun identifiant ni secret
Durée de vie	Artefact éphémère	Documentation durable jusqu’à automatisation

MISTAKES.md doit rester concis pour que Claude Code l’ingère au début d’une session sans consommer un volume excessif de tokens de contexte.

---

2. Anatomie d’un enregistrement d’incident

Chaque entrée contient quatre champs obligatoires :

1. Incident : ce qui a cassé, et dans quelles conditions exactes : code d’erreur, commande, outil.
2. Impact : effet en aval : build cassé, migration corrompue, suite de tests interrompue.
3. Root Cause : source technique confirmée ; si elle ne l’est pas, la marquer explicitement [Hypothesis].
4. Prevention : règle ou vérification concrète qui empêche la répétition.

Exemple d’enregistrement

### ERR-014 : échec d’une migration PostgreSQL lors d’un DROP COLUMN sans CASCADE

- **Incident** : Claude Code a exécuté `ALTER TABLE orders DROP COLUMN customer_ref;` dans la migration 0042.
- **Impact** : le déploiement de staging a échoué à cause de la vue dépendante `v_active_orders`.
- **Root Cause** : les vues qui référencent des tables de base exigent une recréation explicite avec cascade ou des mises à jour préalables.
- **Prevention** : toute migration DDL supprimant une colonne doit vérifier les vues dépendantes via `pg_depend` avant exécution.

[!IMPORTANT] Politique zéro secret : ne committez jamais de chaîne de connexion réelle, clé privée, token ou extrait .env dans MISTAKES.md. Gérez les clés API Claude Code par variables d’environnement locales.

Pour une configuration Claude Code fiable avec un fournisseur API, utilisez votre propre clé API et suivez le guide d’intégration Claude Code de BetterToken.

---

3. Seuil de promotion : du journal au test ou à la règle

Toute faute ponctuelle ne mérite pas une règle permanente. Promouvez les entrées vers des garde-fous automatisés avec un seuil clair :

Incident survenu
  │
  ├─> Première fois : consigner une entrée à 4 champs dans MISTAKES.md
  │
  └─> Deuxième fois (récurrence) :
        │
        ├─> Vérifiable mécaniquement ?
        │     └─> OUI : ajouter un test unitaire, une règle ESLint ou un hook pre-commit
        │
        └─> NON : ajouter une instruction négative stricte dans CLAUDE.md / AGENTS.md

1. Première occurrence : ajoutez un enregistrement concis à MISTAKES.md.
2. Deuxième occurrence : si le problème peut être détecté de façon déterministe, écrivez un test ou une règle de linter. Les garde-fous automatisés sont plus efficaces que les prompts textuels.
3. Contrôles non mécaniques : formulez une règle négative explicite dans CLAUDE.md, par exemple « Ne jamais exécuter jest sans —runInBand dans CI ».
4. Archivage : lorsqu’un test ou hook est déployé, archivez ou supprimez l’entrée de MISTAKES.md pour éviter que le fichier grossisse.

---

4. Vérifier lors de la tâche suivante

Pour confirmer que le nouveau garde-fou fonctionne :

1. démarrez une nouvelle session Claude Code ;
2. fournissez un prompt qui déclenchait auparavant l’échec ;
3. vérifiez que l’agent respecte la règle, ou qu’il est arrêté par le hook pre-commit ;
4. s’il contourne les instructions textuelles, transformez la contrainte en wrapper de commande strict ou en contrôle automatisé.

Cette boucle de retour transforme des échecs de développement aléatoires en une fondation d’ingénierie robuste et auto-améliorée.