Skip to Content
Claude CodePartie 11 — Réviser, debugger, refactorer, industrialiser11.2 — Debugger : /diagnose

Chapitre 11.2 — Debugger : /diagnose

⏱️ TL;DR — Sur un bug difficile, « corrige-moi ça » mène au tâtonnement : l’agent devine, patche au hasard, et casse ailleurs. La skill /diagnose impose une méthode : reproduire → minimiser → hypothétiser → instrumenter → corriger → test de non-régression. On ne corrige qu’une cause observée, jamais supposée, et on verrouille le bug avec un test pour qu’il ne revienne pas. C’est la différence entre « ça a l’air réparé » et « c’est compris et fermé ».

🎯 Objectifs

  • Reconnaître pourquoi « corrige ça » échoue sur un bug tordu.
  • Appliquer la boucle de diagnostic disciplinée (/diagnose).
  • Corriger une cause observée, pas devinée.
  • Verrouiller avec un test de non-régression.

Pourquoi « corrige ça » échoue

Sur un bug simple, l’agent trouve vite. Sur un bug difficile (intermittent, à cause lointaine, dépendant du contexte), lui demander de « corriger » directement le pousse à deviner : il applique un patch plausible, qui masque le symptôme sans traiter la cause — ou en crée un autre. Tu enchaînes les « essaie plutôt ça », le contexte se pollue (5.2), et le bug résiste. Le problème n’est pas l’agent : c’est l’absence de méthode.

La boucle /diagnose

La skill /diagnose structure le débogage en étapes non négociables :

  1. Reproduire : un cas qui déclenche le bug à coup sûr. Sans repro fiable, on debug à l’aveugle. C’est l’étape la plus importante — et la plus sautée.
  2. Minimiser : réduire au plus petit cas qui montre encore le bug. Moins de bruit = cause plus visible.
  3. Hypothétiser : formuler une cause testable (« je pense que deleteTask ne revalide pas parce que… »).
  4. Instrumenter : ajouter des logs/observations pour vérifier l’hypothèse — pas patcher, observer.
  5. Corriger : seulement une fois la cause confirmée par l’observation.
  6. Test de non-régression : un test qui échouait avant, passe après, et restera pour empêcher le retour.

Le cœur : on ne passe à « corriger » qu’après avoir observé la cause. L’instrumentation remplace la devinette.

💡 Réflexe d’architecte — « Pas de correction sans observation. » Si l’agent propose un fix sans avoir montré la cause (un log, une valeur, un état), fais-le reculer : « instrumente d’abord, montre-moi pourquoi ça arrive ». Un fix sur une cause supposée a de fortes chances de masquer le symptôme sans le résoudre — et de te le ramener plus tard, déguisé.

Reproduire d’abord, toujours

⚠️ Piège — Sauter la reproduction (« je vois à peu près, je corrige »). Sans repro fiable, tu ne peux rien vérifier : ni que c’est bien la cause, ni que c’est réparé. Un bug « corrigé » sans repro est un bug qu’on espère corrigé. Le temps passé à obtenir une reproduction stable est le meilleur investissement du débogage — tout le reste en dépend.

Le test de non-régression : verrouiller

Corriger sans test, c’est laisser la porte ouverte au retour du bug (une refacto future le réintroduira). Le test de non-régression transforme un bug résolu en garantie permanente :

  • il échoue sur le code buggé (preuve qu’il cible bien le bug) ;
  • il passe après la correction ;
  • il reste dans la suite → le bug ne peut plus revenir en silence (les hooks P7 le relanceront).

C’est la version « bug » de « exiger la preuve » (5.4) : la preuve que c’est réparé et le verrou contre la récidive, en un seul artefact.

🧭 Sur TaskFlow — Imagine un bug : supprimer une tâche ne rafraîchit pas la liste par intermittence. Avec /diagnose : on reproduit (quel enchaînement ?), on minimise, on instrumente (deleteTask revalide-t-il ?), on observe la cause (revalidation oubliée sur un chemin), on corrige, et on ajoute un test qui vérifie que la liste se met à jour après suppression. Le bug est compris, fermé, et verrouillé — les hooks garderont le test vert.

✏️ Exercices

Exercice 1 — Repro avant tout. Sur ton prochain bug, interdis-toi (et interdis à l’agent) toute correction avant une reproduction fiable. Combien de temps pour la repro ? Le fix a-t-il été plus rapide ensuite ?

✅ Solution

La repro prend parfois l’essentiel du temps — mais une fois qu’elle est là, le fix est rapide et vérifiable. Sans repro, tu « corriges » à l’aveugle et tu re-testes à la main, sans certitude. La discipline « repro d’abord » paraît lente, elle est en fait la plus rapide vers un vrai fix.

Exercice 2 — Le verrou. Sur un bug que tu corriges, écris le test de non-régression avant le fix (il doit échouer), puis corrige (il passe). Le bug est-il maintenant impossible à faire revenir en silence ?

✅ Solution

Un test qui échoue sur le bug puis passe après le fix prouve deux choses : que tu as ciblé la bonne cause, et que la récidive sera attrapée (les hooks P7 relancent la suite). C’est la façon de transformer chaque bug résolu en amélioration permanente de ton filet.

🧠 Quiz de révision

1. Pourquoi « corrige ça » échoue-t-il sur un bug difficile ?

Parce que l’agent devine faute de méthode : il patche un symptôme plausible sans traiter la cause (ou en crée un autre). Le tâtonnement pollue le contexte et le bug résiste.

2. Quelles sont les étapes de la boucle /diagnose ?

Reproduire → minimiser → hypothétiser → instrumenter → corriger → test de non-régression. On ne corrige qu’une cause observée.

3. Pourquoi la reproduction est-elle l’étape clé ?

Parce que sans repro fiable, on ne peut rien vérifier : ni la cause, ni la réparation. Un bug « corrigé » sans repro est seulement espéré corrigé.

4. « Pas de correction sans observation » : qu’est-ce que ça implique ?

Qu’on instrumente (logs, valeurs, états) pour confirmer la cause avant de corriger. Un fix sur cause supposée masque souvent le symptôme sans le résoudre.

5. À quoi sert le test de non-régression ?

À verrouiller le bug : il échoue sur le code buggé, passe après le fix, et reste dans la suite — empêchant le retour silencieux (les hooks le relancent). Preuve + garde-fou en un artefact.

Chapitre suivant : Refactorer sans casser — changer la structure en sécurité.

11.1 — Réviser : /code-review11.3 — Refactorer sans casser