# Déboguer du code avec l’IA : une méthode pratique

URL: https://agentvera.dev/fr/blog/debug-code-with-ai/ · Publié: 2026-10-27

Déboguez avec l’IA de façon fiable : reproduisez d’abord, donnez à l’agent le test qui échoue et les logs, bissectez avec git, trouvez la cause, verrouillez le correctif.

**En bref:**

- Un agent IA débogue bien quand il peut lancer le bug lui-même : partez d’une reproduction, d’un test qui échoue ou d’une commande exacte, pas d’une description du symptôme.
- Donnez-lui la stack trace complète et les logs, laissez-le bissecter avec git bisect run, ajouter des logs temporaires, et demandez la cause racine avant tout correctif.
- Terminez par un test de régression qui échoue avant le correctif et passe après, et arrêtez l’agent dès qu’il devine ou assouplit les tests.

**Pour déboguer du code avec l’IA, donnez à l’agent un moyen de reproduire le bug, l’erreur complète et les logs, et une règle claire : trouver la cause racine avant de modifier quoi que ce soit.** Un agent de code comme Claude Code ou Codex peut lancer vos tests, lire des stack traces, bissecter votre historique git et ajouter des logs, ce qui en fait un excellent partenaire de débogage. Il échoue aussi de façon prévisible : il devine quand il ne peut pas lancer le cas qui échoue, et il « corrige » les symptômes en interceptant les erreurs ou en assouplissant les tests.

Ce guide propose une méthode qui exploite le premier point et protège du second : reproduire, fournir les preuves, réduire le champ, expliquer, corriger, verrouiller avec un test, et savoir quand tout arrêter.

## Pourquoi les agents se trompent en débogage

La plupart des mauvais correctifs de l’IA viennent des mêmes endroits :

- **Pas de reproduction.** L’agent lit le code, se fait une théorie et applique un correctif. Rien ne prouve que la théorie était juste.
- **Des preuves partielles.** Vous collez la dernière ligne de l’erreur. La frame utile, trois niveaux plus bas dans la pile, n’atteint jamais le modèle.
- **Corriger le symptôme.** Une vérification de null, un `try/catch` ou une nouvelle tentative fait disparaître l’erreur, alors que l’état incorrect qui l’a causée est toujours là.
- **Déplacer les poteaux.** Le test échoue, alors l’agent modifie le test.
- **Des sessions longues et polluées.** Après cinq tentatives ratées, la conversation est pleine de théories fausses, et le modèle continue de construire dessus.

Chaque étape ci-dessous vise l’un de ces points.

## Étape 1 : reproduire le bug d’abord

Avant que l’agent ne touche au code, il lui faut une commande qui montre le bug. Ce peut être un test qui échoue, un appel `curl`, un script ou une page dans le navigateur. L’essentiel est que n’importe qui, agent compris, puisse la lancer et voir l’échec.

Si vous en avez déjà une, mettez-la en tête du prompt :

```text
Ceci échoue :

  pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Total attendu 90, obtenu 81. Ne modifie encore aucun code.
Lance le test, confirme que tu vois le même échec et dis-moi ce que tu vois.
```

Si vous n’avez pas de reproduction, faites-en la première tâche :

```text
Des utilisateurs signalent qu’enregistrer un brouillon deux fois crée deux brouillons.
Écris un test qui échoue et reproduit ce problème. Ne corrige rien.
Arrête-toi quand le test échoue pour la bonne raison.
```

« Pour la bonne raison » compte. Un test qui échoue à cause d’une faute de frappe dans le test ne prouve rien. Demandez à l’agent de montrer la sortie de l’échec et d’expliquer pourquoi elle correspond au signalement. Pour les bugs intermittents, faites-lui lancer la reproduction en boucle (par exemple 50 fois) et indiquer la fréquence des échecs, pour savoir plus tard si un correctif a vraiment aidé.

## Étape 2 : donner à l’agent toutes les preuves

Les agents savent lire des sorties longues et bruyantes. Ne les raccourcissez pas pour eux. Donnez :

- la **stack trace complète**, pas seulement le message ;
- la **commande exacte** et sa sortie complète ;
- les **logs pertinents** autour du moment de l’échec ;
- **ce qui a changé récemment** : une mise à jour de dépendance, un déploiement, une branche fusionnée ;
- les **détails d’environnement** s’ils peuvent compter : OS, version du runtime, feature flags.

Inutile de tout coller dans la conversation. Enregistrez la sortie dans un fichier et indiquez-le à l’agent, ou envoyez-la directement par un pipe. Avec le mode print de Claude Code :

```bash
pnpm test 2>&1 | tail -n 200 > /tmp/test-output.txt
cat /tmp/test-output.txt | claude -p "Explain the root cause of this failure. Don't edit files."
```

Dans une session interactive, `!` lance une commande shell et place sa sortie dans la conversation, dans Claude Code comme dans Codex, par exemple `!pnpm test src/billing`. Pour les logs énormes, demandez à l’agent de faire un `grep` sur l’ID de requête ou le code d’erreur au lieu de lire tout le fichier ; cela économise une bonne partie de la [fenêtre de contexte](/fr/glossary/context-window/ "Qu’est-ce qu’une fenêtre de contexte").

## Étape 3 : réduire le champ avec git bisect

Quand quelque chose marchait avant et ne marche plus, vous n’avez pas besoin de théorie. `git bisect` trouve le premier mauvais commit par recherche dichotomique, et il peut tourner de façon entièrement automatique, ce qui en fait un travail idéal pour un agent.

Écrivez d’abord un petit script qui renvoie 0 quand le code est bon et une valeur non nulle quand il est mauvais :

```bash
#!/bin/sh
# check.sh
pnpm install --frozen-lockfile >/dev/null 2>&1 || exit 125
pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"
```

Puis laissez git parcourir l’historique :

```bash
git bisect start
git bisect bad HEAD
git bisect good v2.3.0
git bisect run ./check.sh
git bisect reset
```

Les codes de sortie sont le contrat, tels que les définit la documentation officielle de `git bisect` : 0 signifie bon, tout code de 1 à 127 sauf 125 signifie mauvais, 125 signifie « impossible de tester ce commit, ignore-le », et toute valeur supérieure interrompt le bisect. C’est pour cela que l’étape d’installation ci-dessus renvoie 125 : un commit qui ne s’installe même pas doit être ignoré, pas compté comme mauvais.

Un prompt qui confie le tout à un agent :

```text
Le test de remise sur facture passe sur le tag v2.3.0 et échoue sur main.
Écris un script de vérification pour git bisect run (exit 125 si le commit
ne peut pas être construit), lance le bisect, puis git bisect reset.
Indique le premier mauvais commit et explique quelle ligne de son diff
provoque l’échec. Ne corrige rien pour l’instant.
```

Vérifiez d’abord que l’arbre de travail est propre, ou faites-le dans un [git worktree](/fr/blog/git-worktree-parallel-agents/ "Git worktrees pour agents en parallèle") séparé pour que les checkouts du bisect n’entrent pas en conflit avec votre propre travail. Si le fichier de test n’existait pas encore dans les anciens commits, copiez-le hors du dépôt et faites lancer cette copie par le script.

## Étape 4 : ajouter des logs, puis les retirer

Quand la stack trace n’explique pas l’état qui a mené à l’erreur, l’agent doit voir les valeurs à l’exécution. Demandez des logs ciblés et temporaires :

```text
Ajoute des logs temporaires qui affichent les articles du panier, la liste des remises
et le total courant à chaque étape de applyDiscounts(). Préfixe chaque ligne
par [DEBUG-1234] pour qu’on puisse les retrouver et les retirer ensuite. Lance le
test qui échoue et montre-moi les lignes de log.
```

L’astuce, c’est le préfixe. Une fois le bug compris, une seule instruction fait le ménage :

```bash
git grep -n "DEBUG-1234"
```

Les agents s’en sortent aussi bien avec les débogueurs quand ils sont scriptables : `node --inspect` avec un point d’arrêt est peu pratique pour un agent en terminal, mais une courte session `python -m pdb`, une assertion supplémentaire ou un script ponctuel qui appelle la fonction avec l’entrée fautive donnent généralement la même réponse plus vite.

## Étape 5 : la cause racine avant le correctif

C’est la règle la plus importante. Demandez à l’agent d’expliquer le bug **avant** d’écrire un correctif, et lisez l’explication :

```text
Avant de modifier le moindre code, explique la cause racine :
1. Quel état est incorrect, et où devient-il incorrect pour la première fois ?
2. Pourquoi le code produit-il cet état ?
3. Pourquoi les tests existants ne l’ont-ils pas détecté ?
Propose ensuite le plus petit correctif possible et attends mon accord.
```

Une bonne réponse désigne une ligne précise et une condition précise (« la remise est appliquée à la fois dans `addItem` et dans `checkout` depuis que le commit a1b2c3 a déplacé l’appel »). Une réponse faible reste vague (« il y a peut-être un problème dans la gestion des remises ») ou saute directement à un correctif défensif. Si vous obtenez ce genre de réponse, l’agent n’a pas encore trouvé la cause ; renvoyez-le à l’étape 3 ou 4.

Le plan mode de Claude Code est utile ici, car l’agent peut lire et lancer des commandes en lecture seule, mais pas modifier de fichiers avant votre accord. Lancez-le avec `claude --permission-mode plan`, ou appuyez sur Shift+Tab pour y passer. [Le plan mode de Claude Code](/fr/blog/claude-code-plan-mode/ "Plan mode de Claude Code") le détaille. Dans Codex, `/plan` joue un rôle similaire.

## Étape 6 : corriger et verrouiller avec un test de régression

Laissez maintenant l’agent corriger, avec des contraintes :

```text
Applique le correctif. Règles :
- Ne modifie et n’ignore aucun test existant.
- N’intercepte pas l’erreur pour la faire taire.
- Ajoute un test de régression nommé d’après le bug, qui échoue sans
  le correctif et passe avec. Prouve les deux : annule le correctif, lance le
  test, remets le correctif, relance-le.
- Lance toute la suite de tests à la fin.
```

C’est la partie « prouve les deux » qui rend le test fiable. Un test de régression qui serait passé avant le correctif n’est que de la décoration. Pour obtenir des tests utiles d’un agent, voir [comment écrire des tests unitaires avec l’IA](/fr/blog/write-unit-tests-with-ai/ "Écrire des tests unitaires avec l’IA").

Relisez ensuite le diff vous-même, à la recherche des correctifs de symptôme habituels :

| Motif dans le diff | Pourquoi c’est suspect |
| --- | --- |
| Nouveau `try/catch` qui logue et continue | L’erreur est masquée, l’état incorrect reste |
| Optional chaining ou `?? default` ajouté à l’endroit du crash | Traite les données manquantes comme normales au lieu de demander pourquoi elles manquent |
| Nouvelles tentatives ou timeouts plus longs | Masque souvent une race condition |
| Type élargi en `any` ou `unknown` | Fait taire le compilateur au lieu de corriger le type |
| Attente du test modifiée | Les poteaux ont été déplacés |

Parfois, l’un de ces motifs est le bon correctif. La question à se poser est de savoir si l’agent a expliqué pourquoi.

## Bugs du navigateur : donnez un navigateur à l’agent

Les bugs d’interface sont difficiles à décrire par écrit : un bouton qui ne fait rien, une mise en page qui casse après un clic, une erreur qui n’apparaît que dans la console. Avec [Playwright MCP](https://github.com/microsoft/playwright-mcp "Playwright MCP"), l’agent peut ouvrir la page et regarder par lui-même. Ajoutez-le à Claude Code :

```bash
claude mcp add playwright npx @playwright/mcp@latest
```

ou à Codex dans `~/.codex/config.toml` :

```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
```

Des outils comme `browser_navigate`, `browser_click`, `browser_snapshot`, `browser_console_messages` et `browser_network_requests` permettent à l’agent de reproduire le bug pas à pas, de lire les erreurs de la console et de voir quel appel d’API a échoué. Un prompt de débogage :

```text
Démarre le serveur de dev. Ouvre http://localhost:5173/settings, change le
nom affiché et clique sur Save. Rapporte les erreurs de la console et la requête
réseau de l’enregistrement, avec son statut et le corps de la réponse. Ne corrige rien encore.
```

Une fois la cause claire, demandez à l’agent de transformer les étapes en test Playwright pour que le bug reste corrigé. [Les tests navigateur avec un agent IA](/fr/blog/ai-agent-browser-testing/ "Tests navigateur avec un agent IA") détaillent la mise en place.

## Bugs qui n’apparaissent qu’en CI

Quand les tests passent en local mais échouent en CI, la différence vient généralement de l’environnement : fuseau horaire, locale, parallélisme, variables d’environnement manquantes, autre version de Node ou de Python, ou ordre des tests. Donnez à l’agent le log de la CI et le fichier de workflow, et demandez-lui de lister les différences entre la CI et votre machine avant de deviner. Lancer la suite dans un ordre aléatoire ou avec le fuseau horaire de la CI (`TZ=UTC pnpm test`) reproduit souvent l’échec en local. Si les échecs de CI sont une corvée régulière, [corriger automatiquement les échecs de CI avec l’IA](/fr/blog/auto-fix-ci-failures-with-ai/ "Corriger automatiquement les échecs de CI avec l’IA") montre comment automatiser la boucle.

## Quand arrêter l’agent

Un agent continuera d’essayer bien après le moment où il aurait dû s’arrêter. Coupez court quand :

- **Deux ou trois correctifs ont échoué.** Chaque nouvelle tentative repose sur la même théorie fausse.
- **Le diff s’étend.** Il a commencé dans `invoice.ts` et modifie maintenant la configuration, des modules sans rapport ou des fichiers de lock.
- **Il touche aux tests.** Changer une assertion pour qu’elle corresponde à la mauvaise sortie n’est jamais une correction de bug.
- **Il n’arrive pas à reproduire le bug mais le corrige quand même.**
- **L’explication change** d’un tour à l’autre sans nouvelle preuve.

Que faire à la place :

1. Arrêtez le tour (Échap dans Claude Code et Codex).
2. Annulez ses changements. Commitez avant de commencer à déboguer pour que `git restore .` ou `git stash` vous ramène en arrière ; [annuler les changements de Claude Code](/fr/blog/undo-claude-code-changes/ "Annuler les changements de Claude Code") présente les options.
3. Notez ce que vous avez appris : quelles théories étaient fausses et pourquoi.
4. Démarrez une **nouvelle session** avec la reproduction, les faits et les théories écartées. Un contexte propre avec trois bons faits vaut mieux qu’un long contexte avec dix mauvaises hypothèses.

Parfois, la bonne décision est de poser une question plus étroite : « `cart.items` est-il déjà faux quand `checkout()` est appelé ? » est plus facile à résoudre que « corrige le bug du checkout ».

## Déboguer avec AgentVera

[AgentVera](/fr/download/ "Télécharger AgentVera") est une application de bureau pour macOS, Windows et Linux qui exécute Claude Code, Codex, Gemini CLI et d’autres agents CLI côte à côte, dans de vrais terminaux. Plusieurs de ses outils s’intègrent à la méthode ci-dessus :

- **[Send to agent](/fr/features/send-to-agent/ "Send to agent") :** sélectionnez une erreur dans le dock de terminal, la console du navigateur ou les logs Docker et envoyez-la à un agent avec ⌘⇧L, ou cliquez sur le badge Fix d’une erreur détectée. Les longs logs sont limités à 12 000 caractères et gardent leur fin, là où se trouve généralement la stack trace.
- **[Agent browser](/fr/features/agent-browser/ "Agent browser") :** un Chrome avec un profil séparé que les agents pilotent via Playwright MCP, avec des onglets diffusés en direct pour que vous puissiez regarder l’agent reproduire le bug.
- **[Checkpoints](/fr/features/checkpoints-and-replay/ "Checkpoints et replay") :** chaque tour est enregistré dans une ref git cachée, pour voir ce qu’une tentative ratée a modifié et annuler ce tour sans toucher à vos branches ni à votre stash.
- **Deux théories en parallèle :** lancez deux agents dans des worktrees séparés depuis le [panneau Git](/fr/features/git-and-github/ "Git et GitHub"), donnez à chacun une hypothèse différente et gardez le correctif qui tient.
- **[Verify](/fr/features/verify/ "AgentVera Verify") :** avec Pro et Team, des critères comme « le test de régression échoue sans le correctif et passe avec » sont vérifiés par un vérificateur séparé, en lecture seule, à la fin du tour de l’agent.

Une fois le bug corrigé, notez ce que vous avez appris là où la prochaine personne le trouvera ; [rédiger de la documentation avec l’IA](/fr/blog/write-documentation-with-ai/ "Rédiger de la documentation avec l’IA") couvre cet aspect.

## En résumé

Déboguer avec un agent IA fonctionne quand vous le traitez comme un collègue brillant : partez d’une reproduction, partagez toutes les preuves, réduisez la recherche avec `git bisect`, ajoutez des logs pour voir les vraies valeurs et exigez la cause racine avant le correctif. Terminez chaque bug par un test de régression que vous avez vu échouer puis passer. Et quand l’agent commence à deviner, arrêtez-le, annulez et repartez de zéro avec ce que vous avez appris.

## Questions fréquentes

**L’IA peut-elle vraiment déboguer du code, ou devine-t-elle ?** Un agent de code peut vraiment déboguer quand il peut exécuter le code : reproduire le bug, lire la sortie, ajouter des logs et tester une hypothèse. Sans moyen de lancer le cas qui échoue, il ne peut que deviner à la lecture, et c’est de là que viennent la plupart des mauvais correctifs.

**Que dois-je donner à l’agent quand je signale un bug ?** La commande ou le test exact qui échoue, l’erreur complète avec sa stack trace, ce que vous attendiez à la place, et tout ce qui a changé récemment. Une reproduction d’une ligne vaut mieux qu’une longue description du symptôme.

**Un agent peut-il lancer git bisect tout seul ?** Oui. Donnez-lui un bon et un mauvais commit, et un script qui renvoie 0 quand le code fonctionne et 1 quand il ne fonctionne pas. git bisect run extrait alors les commits et lance le script jusqu’à trouver le premier mauvais. Le code de sortie 125 indique à git d’ignorer un commit qui ne peut pas être testé.

**Comment empêcher un agent IA de faire un correctif qui ne fait que masquer le bug ?** Demandez la cause racine en mots simples avant toute modification du code, interdisez de modifier ou d’ignorer les tests existants, et exigez un test de régression qui échoue sans le correctif. Relisez le diff à la recherche de blocs try/catch, de nouvelles tentatives et de types élargis qui font taire l’erreur au lieu d’en supprimer la cause.

**Quand dois-je arrêter l’agent et déboguer moi-même ?** Quand il a essayé deux ou trois correctifs qui n’ont pas marché, quand il se met à modifier des fichiers sans rapport, ou quand il propose d’affaiblir un test ou une assertion. Arrêtez-le, annulez ses changements et recommencez avec une reproduction plus précise ou une question plus ciblée.

---

**À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/