Développement avec l’IA

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

Guide pour des entrées MISTAKES.md concises, une politique zéro secret, le passage aux tests ou règles et la vérification des garde-fous Claude Code.

BT

BetterToken

Équipe éditoriale
4 min de lecture

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 :

DimensionTranscription de sessionJournal d’incidents MISTAKES.md
VolumeDes milliers de lignes d’appels d’outils et d’étapes intermédiaires5 à 10 lignes structurées par incident
ButDébogage et audit d’une seule exécutionBase de référence pour empêcher les récidives
SecretsPeut capturer variables d’environnement ou tokens brutsStrictement interdit : aucun identifiant ni secret
Durée de vieArtefact éphémèreDocumentation 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](https://docs.bettertoken.ai/ai-tools/claude-code).

---

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.

Prêt à optimiser votre workflow LLM ?

Connectez vos modèles via une API unique, gérez les clés et maîtrisez vos dépenses d’IA.