Debugging avec des agents IA : de façon systématique, pas au hasard

Les agents debuggent mieux avec une erreur reproductible, de vrais logs et une hypothèse avant le correctif – pas avec « corrige le bug ».

L'erreur la plus fréquente

Beaucoup de gens donnent à un agent juste « Corrige le bug » – sans message d'erreur, sans contexte. L'agent devine alors. Le debugging systématique fonctionne autrement.

Étape 1 : reproduire l'erreur

Donne à l'agent la commande qui déclenche l'erreur et laisse-le provoquer lui-même la panne. La doc de Claude Code recommande exactement cela : dire à l'agent comment reproduire le problème et obtenir une stack trace. Une erreur que l'agent peut déclencher lui-même est aussi une erreur qu'il peut vérifier lui-même après le correctif.

Étape 2 : fournir logs et stack traces

Colle le message d'erreur complet plutôt que de le décrire. Possible aussi via un pipe : cat error.log | claude -p "explique la cause". Précise aussi si l'erreur survient toujours ou seulement parfois.

Étape 3 : hypothèse avant correctif

Laisse d'abord l'agent nommer les causes probables, classées par probabilité – puis en tester une précisément. Important : corriger la cause, pas le symptôme. La doc officielle le formule comme règle de prompt : « address the root cause, don't suppress the error ».

Outils de diagnostic

Pour les problèmes avec Claude Code lui-même, il existe /doctor : un check automatique de l'installation, des réglages, des extensions et de l'utilisation du contexte. Si claude ne démarre même pas, claude doctor aide directement depuis le shell.

EXEMPLE

Prompt : « npm test échoue. Voici la stack trace complète : [coller]. Reproduis l'erreur, nomme la cause la plus probable et écris d'abord un test qui échoue avant de corriger quoi que ce soit. »

🛠️ EXERCICE — À TOI DE JOUER

Introduis volontairement un petit bug dans un projet d'entraînement (par ex. une faute de frappe dans un nom de variable) et fais-le trouver systématiquement par un agent.

Déclenche l'erreur et copie le message d'erreur complet avec la stack trace.
Donne à l'agent le message d'erreur et la commande de reproduction – et exige d'abord une hypothèse, pas encore de correctif.
Ne laisse implémenter le correctif qu'après avoir lu l'hypothèse, et fais vérifier le succès par l'agent avec la même commande.

✅ AUTO-VÉRIFICATION

☐ L'agent a-t-il nommé la bonne cause avant de changer quoi que ce soit ?
☐ A-t-il prouvé le correctif avec la commande de reproduction (sortie montrée), plutôt que de simplement dire « c'est fait » ?
☐ Qu'est-ce qui aurait manqué si tu avais seulement écrit « il y a un bug » ?

QUIZ RAPIDE

Quelle est la première étape la plus sensée quand un agent doit corriger un bug ?