Debug-Methodical — Debugging en 4 phases
Skill inspiré de
obra/superpowers.
Objectif : forcer une méthode rigoureuse au lieu de "try random fixes until it works".
Règle d'or : un bug sans reproduction stable est un bug mal compris. Ne JAMAIS fixer avant de reproduire.
Les 4 phases (strictes, dans l'ordre)
Phase 1 : REPRODUCE
Objectif : exécuter le bug à volonté, dans un environnement contrôlé.
Checklist :
Sortie : test automatisé qui échoue en exposant le bug (test de régression).
Signal rouge : "ça marche sur ma machine" / "parfois ça fail" → reproduction insuffisante, retour Phase 1.
Phase 2 : ISOLATE
Objectif : identifier la cause racine, pas juste un symptôme.
Techniques :
- Bisect : pour trouver le commit fautif
- Binary search dans le code : commenter la moitié, puis itérer
- Print-driven debugging : logs aux frontières (entrée/sortie fonctions)
- Debugger : breakpoints, step-through, variable watch
- Diff environnements : que diffère-t-il entre "qui marche" et "qui casse" ?
- Question the premise : l'hypothèse initiale est-elle correcte ?
Checklist :
Signal rouge : "je pense que c'est X" sans preuve → retour isolate avec instrumentation.
Phase 3 : FIX
Objectif : corriger la cause racine avec le minimum de changement.
Checklist :
Signaux rouges :
- Fix qui ajoute un pour masquer l'erreur → traite le symptôme, pas la cause
- Fix qui nécessite de modifier les tests existants de façon suspecte
- Fix qui "marche" sans que tu saches pourquoi
Phase 4 : VERIFY
Objectif : prouver que le fix marche ET n'a rien cassé d'autre.
Checklist :
Règle de régression : le test écrit en Phase 1 reste dans la codebase
pour toujours. Un bug fixé ne doit JAMAIS réapparaître (voir
).
Anti-patterns critiques
| Anti-pattern | Pourquoi c'est mal |
|---|
| Shotgun debugging | Changer 10 trucs au hasard, aucun apprentissage |
| Fix du symptôme | Bug revient sous une autre forme |
| Skip reproduction | Fix impossible à valider |
| Skip verification | "ça devrait marcher" — preuve ou pas fini |
| Pas de test de régression | Bug réapparaît dans 3 mois |
| Fix avec générique | Masque d'autres bugs |
| Commit mélangé fix + refactor | impossible |
Techniques avancées
Pour bugs de concurrence
- Forcer les interleavings (sleep stratégique, stress test)
- Thread dumps / profiler
- Vérifier les invariants atomiquement
Pour bugs d'intégration
- Snapshot du payload exact (HAR, logs)
- Reproduire avec ou client minimal
- Vérifier versions exactes des dépendances
Pour flaky tests
- Run 100x pour mesurer le taux de flakiness
- Identifier la dépendance (temps, ordre, ressource partagée)
- Ne JAMAIS marquer un test sans ticket de correction
Intégration Claude Craft
- — bug fix en mode TDD (test qui échoue d'abord)
- — correction automatisée des bugs QA
- — registre des tests de régression
- Skill — découper le debug en phases atomiques
- Rule 07 (testing) — bug fix = test de régression obligatoire
Ressources
- obra/superpowers
- Rule
.claude/rules/07-testing.md
- Command ,
Date de dernière mise à jour : 2026-04-15
Version : 1.0.0