Debug avec Claude Code : la méthode en 4 phases
Le debug Claude Code dérape lorsque l’IA applique des correctifs aléatoires : après 20 minutes, le code gagne en complexité tandis que le bug se déplace simplement. Votre client, par contre, le découvre en production, et c’est votre réputation qui en subit les conséquences. Le skill /investigue définit 4 étapes ainsi qu’un critère de fin, afin de traiter l’origine au lieu du symptôme.
Ce qui se passe sans méthode
Un bug arrive, il arrive toujours. Vous demandez à l’IA de le corriger. Elle essaie quelque chose, ça ne marche pas, elle essaie autre chose, puis elle modifie du code qui n’a rien à voir.
C’est le médecin urgentiste qui traite les symptômes sans diagnostic. Il vous soulage ce soir, et vous revenez avec la même douleur ailleurs. Le symptôme disparaît, la cause reste.
Les 4 phases de /investigue
Chaque phase s’arrête et attend votre validation avant la suivante.
1. Localiser et reproduire
Pas de correctif tant que le bug ne se reproduit pas à coup sûr. Un bug que l’on ne sait pas déclencher, on ne sait pas non plus vérifier qu’il est corrigé.
2. Poser 3 hypothèses sur la cause racine
Trois causes possibles, classées, chacune avec son test concret : « si c’est bien cette cause, voilà ce qu’on va observer ». Chaque hypothèse se confirme ou tombe sur un fait observé.
3. Ajouter des logs ciblés et temporaires
Des logs posés exactement là où l’hypothèse se joue, marqués pour être retrouvés. Ils servent pendant l’analyse, puis ils partent tous en une fois quand le bug est résolu. Rien ne traîne dans le code livré.
4. Un correctif minimal
Le plus petit changement qui supprime la cause, et un message qui l’explique. Aucun refactoring opportuniste au passage : le correctif ne touche que ce qui était cassé.
La règle des 3 strikes
Si les 3 hypothèses sont fausses, on s’arrête. Ce n’est plus un problème de code, c’est un problème d’architecture, et le traiter comme un bug revient à construire sur des fondations fissurées.
Cette règle vous évite l’heure de patchs successifs qui finit en code illisible. Elle vous donne aussi le bon message pour votre client : « le problème vient de la conception, il faut revoir cette partie avant d’y toucher ».
Lancer /investigue dans Claude Code
npx skills add naiersaidane/claude-mastery
Puis /investigue ou une phrase : « débugge ça ». Le skill fait partie d’un cycle de 6, que je déroule dans les 6 Claude Code skills, dans l’ordre d’un projet. Beaucoup de bugs naissent d’un besoin flou : un PRD rempli avant de coder en évite une bonne partie.
Ce que vous pouvez vendre avec ça
Vos premiers clients dans ce domaine sont précisément les structures auxquelles vous avez déjà fourni un outil, qu’il s’agisse d’une PME comptant de 5 à 50 salariés, d’un cabinet ou d’une agence, et qui vous contactent aussitôt qu’un dysfonctionnement survient.
Pour chaque incident, vous fournissez un correctif accompagné d’une note de cinq lignes détaillant la cause, la preuve et les modifications apportées. Le client conserve une trace écrite, tandis que vous disposez d’un historique attestant de la qualité de votre travail.
Pour l’exposer : « Lorsqu’un bug survient, je n’applique pas de correctif au hasard. Je localise l’origine du problème, je vous la présente, puis j’apporte la correction la plus précise. Si le problème réside dans la conception, je vous en informe avant d’intervenir sur le code. » Offrez cette prestation en maintenance mensuelle, immédiatement après la livraison : c’est l’instant où votre client craint le plus que tout ne se brise.
