06 — Debugger et itérer

@diagram:lesson-contract
duration :: 10 min lecture
deliverable :: Un test manuel documenté dans NOTES.md et une correction ciblée validée
outcome :: Réflexe de collecte du signal avant de demander une correction — sortir de la boucle patch-on-patch

Le réflexe utile

Une erreur n’est pas un signal pour modifier au hasard. C’est un signal pour collecter ce que tu as sous les yeux. Tu rassembles le contexte, puis tu le donnes à l’agent.

Suis cet ordre :

1. ce que tu as fait ;
2. ce que tu vois ;
3. le message d’erreur ;
4. la commande lancée ;
5. le résultat attendu.

Ces cinq points tiennent dans un prompt court :

J'ai ajouté l'historique local.
Maintenant la page est blanche.
Commande lancée : npm run dev.
Console navigateur : [colle l'erreur].
Je veux retrouver l'affichage du formulaire.
Analyse la cause probable avant de modifier.

Les 4 endroits à regarder

@diagram:error-console

1. Terminal

Si l’app ne démarre pas :

npm run dev

Copie l’erreur entière. Les dernières lignes ne contiennent pas toujours la cause.

2. Console navigateur

Quand l’app démarre mais que l’écran reste blanc, ouvre les DevTools :

• Windows/Linux : F12 ou Ctrl+Shift+I
• macOS : Cmd+Option+I

Va dans l’onglet Console et copie le message rouge.

3. Network

Si un appel API échoue, passe à l’onglet Network et relève le status, l’URL, le payload et la réponse. Tu n’as pas besoin de tout comprendre : l’agent sait s’en servir.

4. Git diff

Si ça marchait avant ta dernière modification, le diff te montre ce qui a changé :

git diff

Donne ce diff à l’agent, ou demande-lui de l’analyser.

Demander une correction ciblée

Voici ce qui ne marche pas :

Ça marche plus, corrige tout.

Et voici le prompt qui cadre le travail :

Voici l'erreur et le diff.
Trouve la cause la plus probable.
Corrige uniquement ce qui est nécessaire.
Ne refactorise pas.
Après correction, indique la commande de vérification.

Itérer sans casser plus

Garde la même boucle à chaque passage :

1. Reproduire le bug
2. Capturer le message
3. Formuler l'hypothèse
4. Corriger petit
5. Relancer
6. Commit si c'est stable

Si deux corrections échouent d’affilée, arrête les modifications et demande une analyse plutôt qu’une troisième tentative :

Stop modifications.
Résume ce que tu as essayé, ce qui a échoué, et propose 2 hypothèses avec la vérification associée.

Ajouter un mini-test manuel

Pas besoin d’un framework de test pour vérifier ton app. Une recette écrite dans NOTES.md suffit :

## Test manuel V1
1. Lancer `npm run dev`.
2. Ouvrir l'URL locale.
3. Remplir le formulaire avec "Gourde inox 750 ml".
4. Cliquer Générer.
5. Vérifier titre + description + 5 bullets.
6. Cliquer Copier.
7. Recharger la page et vérifier l'historique.

Une fois la recette en place, demande à l’agent de la relire :

Lis le test manuel dans NOTES.md et vérifie que l'app permet ces étapes.

Check-list de validation

@diagram:checklist
item-1 :: Tu peux reproduire le bug.
item-2 :: Tu as le message terminal ou console.
item-3 :: Tu as décrit ce que tu voulais obtenir.
item-4 :: La correction demandée est ciblée.
item-5 :: Tu as relancé la commande utile.
item-6 :: Tu as mis à jour le test manuel si le comportement change.

Pièges fréquents

• Corriger sans reproduire. Tu risques de masquer le problème au lieu de le régler.
• Coller seulement une capture. Ajoute toujours le texte de l’erreur si possible.
• Accepter un refactor pendant un debug. D’abord réparer, ensuite améliorer.
• Ignorer le diff. Les changements récents contiennent souvent la cause.

Suite conseillée

Passe au module 7 pour structurer ton projet et éviter que les bugs reviennent à chaque nouvelle fonctionnalité.