Modèle de notes de débogage

La façon coûteuse de déboguer est de passer directement à un changement. Vous tombez sur une trace de pile rouge, essayez quelque chose, le test échoué devient vert, et vous passez à autre chose. Deux jours plus tard, la même défaillance refait surface sur une entrée légèrement différente, car le changement a atténué le symptôme sans jamais confirmer la cause. Aucun raisonnement n'a été consigné, donc la prochaine personne, souvent vous, recommence à zéro.

Un modèle de notes de débogage corrige cela en transformant une chasse en un enregistrement. C'est la surface de travail du débogage basé sur les hypothèses, la pratique consistant à traiter chaque cause suspectée comme une affirmation que vous prédisez puis testez, de la même manière qu'un scientifique mène une expérience avant de croire au résultat. Cette discipline n'est pas du folklore. Dans une expérience contrôlée randomisée UIST 2023 avec 16 développeurs professionnels, un outil de débogage basé sur les hypothèses a amélioré le taux de réussite de correction des défauts par un facteur de cinq et réduit le temps de débogage par un facteur de trois, comparé aux débogueurs par points d'arrêt et à la recherche sur le web. Le gain vient du fait de forcer la confirmation de la cause avec des preuves avant tout changement de code.

Les assistants augmentent les enjeux dans les deux sens. Ils traduisent une trace cryptique en langage clair plus rapidement que vous ne le pouvez, et ils listent plus d'hypothèses que vous ne le feriez seul. Ils produisent aussi une cause principale classée avec confiance qui peut être erronée concernant votre code, car faire correspondre des motifs à travers des millions de dépôts publics est une opération différente du raisonnement causal à l'intérieur d'une seule base de code. La note est l'endroit où vous gardez le modèle honnête : vous enregistrez ce qu'il a classé en premier, puis vous enregistrez la vérification qui a réellement décidé. Sans cela, une explication plausible passe comme si elle était prouvée. C'est la même boucle que les outils de débogage modernes ont commencé à automatiser. Cursor Debug Mode, livré en décembre 2025, génère plusieurs hypothèses, ajoute des instructions de log qui diffusent vers un serveur de débogage local, vous fait reproduire le bogue, puis lit les données d'exécution capturées pour identifier la véritable cause avant de faire une correction ciblée. Les champs de ce modèle sont cette boucle écrite, qu'un outil l'exécute pour vous ou que vous l'exécutiez manuellement.

Considérez le coût concrètement. Une développeuse nommée Maya possède un petit module utilitaire dans un service Node. Une API partenaire envoie des horodatages comme "2026-03-14T10:00+02:00", et parseDate() génère une erreur sur la forme de décalage. Demandez à un assistant une correction immédiate et il peut envelopper l'analyse dans un try/catch et retourner une date de secours. L'exception disparaît, le test évident réussit, et une heure silencieusement incorrecte s'écoule maintenant dans chaque exportation. La trace s'est tue; le bogue s'est caché. Une note remplie l'aurait attrapé, car le champ Preuve n'a nulle part où écrire "J'ai confirmé que le décalage a été analysé correctement."

La note se rentabilise également dans les cas qui traînent. Un bogue qui prend une heure et trois faux départs est un cas où le modèle vous aurait empêché de réessayer une hypothèse que vous aviez déjà réfutée, car le champ Preuve enregistre ce que chaque vérification a écarté. Et la deuxième fois qu'une trace similaire apparaît, la note fait la différence entre cinq minutes de reconnaissance et une nouvelle heure de redécouverte. La section suivante parcourt chaque champ pour qu'une bonne entrée soit évidente par rapport à une faible.

Le modèle comporte neuf champs, et chacun résiste à un raccourci spécifique. Remplissez les trois premiers par observation, puis obtenez le reste par investigation.

• Symptôme. Énoncez le comportement observé de manière factuelle, attendu versus réel, sans cause supposée. Une entrée solide : parseDate() génère une exception sur les entrées avec un décalage horaire; attendu une Date, obtenu une exception. Une entrée faible : le parseur de date est brisé sur des entrées bizarres. La faible introduit une théorie ("brisé") et cache le déclencheur ("bizarres"), ce qui biaise tout ce qui suit.
• Reproduction. Capturez l'entrée exacte, la commande et les conditions, et indiquez si c'est constant ou intermittent. Les directives de rapport de bogue sont claires ici : reproduisez-le au moins deux fois avant d'écrire quoi que ce soit, et partez d'un état connu. Une entrée solide nomme la valeur littérale et le chemin : parseDate("2026-03-14T10:00+02:00") dans src/utils/date.ts, constant, uniquement sur les décalages +HH:MM. Une faible dit se produit parfois avec les données des partenaires, ce que vous ne pouvez pas relancer et donc pas utiliser pour confirmer un correctif.
• Environnement. Notez le runtime et la version, le système d'exploitation, les versions clés des dépendances, et la branche ou le commit. De nombreux bogues "non reproductibles" sont dus à un écart de version, et c'est ici que cela apparaît.
• Hypothèses. Listez les causes probables classées par ordre de probabilité, chacune formulée comme une affirmation testable. Le classement est important car il force un engagement que vous pouvez réfuter, plutôt qu'une couverture générale. Si un assistant les a générées, collez son ordre tel quel pour voir plus tard si le modèle avait raison.
• Preuve. C'est le champ qui sépare le vrai débogage de la supposition. Notez le seul contrôle que vous avez effectué pour l'hypothèse principale et exactement ce qu'il a montré, et nommez l'alternative qu'il a écartée. Une entrée solide : journalisé offsetMinutes avant utilisation; il a imprimé NaN, donc la regex n'a jamais correspondu; une erreur de signe donnerait quand même un nombre, donc la théorie du mauvais signe est écartée. Une entrée faible : regardé, semble être la regex. "Semble être" n'est pas une preuve, et cela laisse les alternatives en vie.
• Cause confirmée. Nommez l'hypothèse que la preuve a soutenue, et celles qu'elle a éliminées. Si vous ne pouvez pas remplir cela sans vague, vous n'avez pas terminé l'investigation, peu importe à quel point l'explication semblait convaincante.
• Correctif. Décrivez le plus petit changement qui résout la cause, par fichier et une description en une ligne. Visez le correctif à la cause que la preuve a indiquée, pas à la ligne où l'erreur est apparue. Un try/catch qui avale l'exception n'a pas sa place ici.
• Test. Notez le test de régression qui échoue avant le correctif et réussit après, et où il se trouve. Un correctif sans test échouant puis réussissant est une supposition qui a simplement calmé le symptôme. Ce champ est la preuve que la cause était réelle.
• Nettoyage et notes. Listez l'instrumentation temporaire que vous avez retirée, le prompt qui a trouvé la cause, et tout suivi. Des outils comme Cursor Debug Mode retirent leurs propres déclarations de log une fois le correctif vérifié; faites de même à la main pour que les lignes de débogage n'atteignent jamais le diff.

Lisez une note bien remplie et vous pouvez répondre à une question sans faire confiance à quiconque : pourquoi croyez-vous cette cause, et qu'est-ce qui vous aurait prouvé le contraire ? Si la note ne peut pas répondre à cela, c'est une histoire, pas une investigation. Les pièges qui font qu'une note semble terminée tout en laissant cette question sans réponse viennent ensuite.

Chaque piège ci-dessous donne l'impression de progresser tout en brisant discrètement le dossier, donc le correctif se trouve dans le même élément.

• Ignorer la Reproduction. Remplir Correctif et Test sur un bogue que vous ne pouvez pas déclencher à la demande signifie que vous ne pouvez pas dire si le changement a fonctionné ou si l'échec ne s'est simplement pas produit. Construisez d'abord la reproduction, même un script d'une ligne, et réutilisez-le comme test de régression.
• Considérer une explication confiante comme une Preuve. La cause la mieux classée par l'assistant est lue comme un fait, donc le champ Preuve obtient une paraphrase de l'hypothèse au lieu d'un contrôle. Écrivez seulement ce qu'une sonde a réellement montré, et nommez l'alternative qu'elle a écartée.
• Le correctif en rafale. Laisser un agent modifier cinq fichiers en poursuivant une théorie laisse le champ Correctif incapable de dire quel changement importait ou ce qui a été cassé d'autre. Changez une chose, relancez la reproduction, puis enregistrez-la.
• Symptôme plutôt que cause. Une valeur par défaut ou une erreur avalée fait taire la trace sans aborder pourquoi la valeur était incorrecte. Le champ Cause confirmée est le garde : s'il nomme la surface, pas la source, le bogue reviendra.
• Laisser l'instrumentation derrière. Les lignes de log et les serveurs de débogage ajoutés pendant la chasse sont du bruit dans le diff et peuvent fuir des données. Le champ Nettoyage existe pour que le retrait soit une étape que vous cochez, pas une réflexion après coup.
• La dépendance hallucinée. Un assistant peut "corriger" un bogue en important un package qui n'existe pas. L'étude USENIX Security 2025 a généré 576 000 échantillons de code et a trouvé que 19,7 % des 2,23 millions de packages qu'ils ont référencés n'existaient pas, et 58 % de ces noms inventés réapparaissaient à travers les exécutions, donc les attaquants les enregistrent pour attendre le prochain développeur qui copie la suggestion. Avant qu'un nouvel import n'atterrisse dans Correctif, confirmez que le package se résout à une entrée réelle et prévue sur le registre.

Un véritable cas limite étire le formulaire simple : le bogue non déterministe. Les conditions de course et les échecs de synchronisation ne se reproduisent pas à la demande, donc un seul passage réussi ne prouve rien. Ici, le champ Preuve devrait contenir une instrumentation qui capture l'ordre des événements et l'état partagé à travers plusieurs reproductions, jusqu'à ce que le mauvais entrelacement apparaisse dans les données capturées, plutôt qu'un seul passage chanceux.

En équipe, la note cesse d'être une aide personnelle et devient un artefact partagé. Une responsable nommée Priya fait d'une note complétée une partie de la définition de fait pour un correctif de bogue, afin que la prochaine personne qui voit une trace similaire trouve le raisonnement, pas juste le correctif. La même note appartient à la description du PR, qui devrait enregistrer qu'un assistant a proposé le correctif et le prompt qui a trouvé la cause, afin qu'un réviseur puisse répéter la vérification au lieu de faire confiance au diff. Gardez les correctifs petits pour la même raison que vous gardez les hypothèses uniques : un diff ciblé sous quelques dizaines de lignes est un que le réviseur peut réellement lire, tandis qu'un changement tentaculaire enterre la véritable correction.

Le principe durable à retenir, quelle que soit la taille de l'équipe : confirmez la cause avec des preuves avant de modifier le code, et verrouillez le correctif avec un test qui échouait il y a un instant. Pour votre prochain vrai bogue, remplissez Symptôme et Reproduction avant de demander un seul correctif, puis consultez le guide Debugging with AI pour la boucle complète d'analyse d'abord et Reviewing AI Code Safely pour la lecture finale sur le diff.