Soyons honnêtes sur quelque chose que la plupart d'entre nous ne disent pas à voix haute : on révise à peine le code généré par l'IA.

Le diff fait 600 lignes. L'agent a touché 14 fichiers. Tu ouvres la pull request, tu fais défiler les changements, tu plisses les yeux sur quelques fonctions et tu merges. Peut-être que tu lances les tests d'abord. Peut-être pas. Le code a l'air raisonnable. L'agent a dit qu'il avait fini. On shippe.

Ce n'est pas de la paresse. C'est un problème structurel. La revue de code traditionnelle a été conçue pour un monde où un humain écrivait le code et pouvait expliquer son raisonnement quand on lui demandait. Où les diffs faisaient 50-200 lignes parce que c'est ce qu'une personne écrit dans une session concentrée. Où la description du PR disait "J'ai choisi l'approche X à cause de Y" et tu pouvais faire confiance à ce contexte.

Les agents IA ne fonctionnent pas comme ça. Claude Code peut produire 500 lignes de code fonctionnel en deux minutes. La description du PR est souvent juste "implémenter la feature X." Le diff te dit ce qui a changé mais rien sur le pourquoi. Pas de trace des alternatives que l'agent a considérées. Pas d'explication des compromis qu'il a faits. Pas de preuve qu'il a réellement testé quoi que ce soit. Tu révises la sortie d'une boîte noire, et l'outil de revue ne te montre que la sortie.

Cet article décompose pourquoi la revue basée sur les diffs échoue pour la sortie des agents, quelle est la couche réellement manquante, et un pattern concret qui rend le code généré par IA vérifiable sans tripler ton temps de revue.

Le fossé de la revue

Les développeurs sont honnêtes à ce sujet en privé. Dans les fils de discussion de la communauté, le pattern se répète : "Je survole surtout les diffs des agents." "Je vérifie que les tests passent et je merge." "Si ça a l'air à peu près correct, j'approuve."

C'est un comportement rationnel étant donné les contraintes. Quand un collègue humain soumet un PR, tu as du contexte : tu sais sur quoi il travaillait, tu as vu le ticket, peut-être que vous avez discuté de l'approche au standup. Le diff est complémentaire. La vraie revue s'est faite à travers le contexte partagé.

Avec un agent, tu n'as rien de tout ça. L'agent a pris une tâche, est resté silencieux pendant trois minutes et a produit un diff. Le seul contexte est la description d'une ligne que l'agent a laissée sur le PR. Réviser ce diff à partir de zéro, sans contexte sur l'intention ou le raisonnement, prend 5 à 10 fois plus longtemps que réviser un PR humain de même taille. Alors les gens ne le font pas. Ils vérifient ponctuellement quelques zones critiques et approuvent.

Le résultat est prévisible. Des bugs passent à travers qui auraient été détectés avec du contexte. La dérive architecturale s'accumule alors que les agents prennent de petites décisions qui se composent. La qualité du code se dégrade de manière subtile : pas cassé, mais pas tout à fait correct non plus. Gestion d'erreurs incohérente dans un fichier. Une requête de base de données qui fonctionne mais qui scale mal. Une nouvelle fonction utilitaire qui duplique une existante parce que l'agent ne savait pas qu'elle existait.

Aucune de ces défaillances n'est visible dans une revue de diff. Elles ne sont visibles que quand tu comprends ce que l'agent essayait de faire et que tu peux comparer son intention avec son exécution.

Pourquoi les diffs ne suffisent pas

Un diff est un enregistrement de changements textuels. C'est tout. Pour la revue de code humaine, les diffs fonctionnent parce que le réviseur peut inférer l'intention à partir de la reconnaissance de patterns et du contexte partagé. Tu vois un collègue ajouter un bloc try/catch et tu sais qu'il gère le cas d'erreur du rapport de bug de la semaine dernière. Tu le vois renommer une fonction et tu sais qu'il suit la convention de nommage sur laquelle l'équipe s'est mise d'accord.

Avec du code généré par agent, tu ne peux pas inférer l'intention parce que tu n'as pas participé au processus de raisonnement. Voici ce qu'un diff de 500 lignes d'un agent te dit réellement :

Quels fichiers ont été modifiés
Quelles lignes ont été ajoutées, changées ou supprimées
La structure syntaxique du nouveau code

Voici ce qu'il ne te dit pas :

Pourquoi cette approche a été choisie. L'agent a peut-être considéré trois implémentations différentes. Il en a choisi une. Tu ne sais pas pourquoi. Peut-être que celle qu'il a choisie est optimale. Peut-être que c'est la première chose qu'il a essayée et ça a suffi. Tu ne peux pas le savoir à partir du diff.

Quelles alternatives ont été écartées. Si l'agent a choisi une stratégie de polling plutôt que des souscriptions WebSocket, était-ce une décision architecturale délibérée ou un accident ? Un diff ne le dit pas.

Si l'implémentation correspond au spec. Tu devrais ouvrir le spec dans une fenêtre et le diff dans une autre et croiser manuellement chaque critère d'acceptation. La plupart des gens ne le font pas.

Ce qui a été testé et comment. Le diff peut inclure de nouveaux fichiers de test. Mais est-ce que l'agent les a exécutés ? Ont-ils passé ? Couvrent-ils les cas limites du spec ? Tu devrais checkout la branche et les exécuter toi-même pour le savoir.

Si l'agent est resté dans le périmètre. Peut-être que la tâche était "corriger le bug de login" et l'agent a aussi refactorisé le middleware d'auth, renommé deux fonctions utilitaires et mis à jour le schéma de config. Tous ces changements semblent corrects isolément. Mais ils n'ont pas été demandés, n'ont pas été spécifiés et n'ont pas été testés par rapport aux critères d'acceptation originaux.

Ce n'est pas un problème avec un outil de diff particulier. L'interface de revue de GitHub, les merge requests de GitLab, Gerrit, git diff dans le terminal. Ils te montrent tous la même chose : ce qui a changé. Pour la sortie d'un agent, "ce qui a changé" est la question la moins importante. La question importante est : est-ce que ce changement fait ce qu'il était censé faire, et rien d'autre ?

La couche manquante : le récit d'implémentation

Ce dont les réviseurs ont réellement besoin, c'est la trace du raisonnement de l'agent. Pas le diff. L'histoire de l'implémentation : ce que l'agent a prévu de faire, ce qu'il a réellement fait et comment il a vérifié le résultat. Appelle ça un récit d'implémentation.

Un bon récit d'implémentation répond à cinq questions :

Quel était le plan ? Avant d'écrire du code, qu'est-ce que l'agent avait l'intention de faire ? Quels fichiers, quelle approche, quel ordre d'opérations ?
Que s'est-il passé pendant l'implémentation ? Le plan a-t-il survécu au contact avec la codebase ? Y a-t-il eu des surprises, des pivots ou des changements de périmètre ?
Quel a été le résultat final ? Pas le diff. Un résumé en langage clair de ce qui a changé et pourquoi.
Comment a-t-il été vérifié ? Les étapes spécifiques que l'agent a prises pour confirmer que l'implémentation fonctionne. Pas "les tests passent" mais "j'ai exécuté le critère d'acceptation #3 en faisant X et j'ai observé Y."
Que devrait vérifier le réviseur ? La propre recommandation de l'agent sur ce qui mérite l'attention humaine. Peut-être qu'il y a une décision de design qui pourrait aller dans les deux sens, ou un compromis de performance qui mérite un second avis.

Rien de tout cela n'existe dans un workflow PR standard. Le champ de description du PR est du texte libre que personne n'impose. Les PRs d'agents ont des descriptions minimales par défaut parce qu'on a dit à l'agent d'implémenter, pas de documenter son raisonnement.

Le fossé n'est pas l'outillage. C'est le processus. L'infrastructure de revue existe. Ce qui manque, c'est un enregistrement structuré de l'intention de l'agent que le réviseur peut vérifier par rapport au diff.

Le pattern plan-comment-done

Voici un pattern qui comble le fossé sans ajouter un overhead significatif. Il a trois parties : l'agent commente un plan avant d'écrire du code, il implémente, et il commente un rapport done structuré quand il a fini.

Étape 1 : Le commentaire de plan

Avant que l'agent n'ouvre un fichier, il écrit ce qu'il a l'intention de faire. Des étapes numérotées, les fichiers qu'il va toucher et l'approche qu'il va prendre.

PLAN: Fix WebSocket reconnection dropping messages during
server restart.

1. Add a message buffer to hooks/use-websocket.ts that queues
   outbound messages while the connection is in CONNECTING state
2. On successful reconnection, flush the buffer in order
3. Add a 30-second timeout: if reconnection hasn't succeeded,
   surface an error to the user via the toast system
4. Update the existing reconnection test to verify buffer
   behavior

Files: hooks/use-websocket.ts, components/connection-status.tsx

Test: Unit test for buffer queueing/flushing, manual test by
killing the WS server mid-operation and verifying no messages
are lost on reconnect.

Cela prend à l'agent environ 30 secondes. Le réviseur le lit en moins de 2 minutes. Dans ces 2 minutes, tu détectes des problèmes qui prendraient 20 minutes à trouver dans une revue de diff :

Le périmètre est-il correct ? (Le plan dit 2 fichiers. Si le diff touche 6, quelque chose a dérivé.)
L'approche est-elle solide ? (Un buffer de messages avec flush-on-reconnect est raisonnable. Si l'agent avait proposé de recharger tout l'état depuis le serveur, tu voudrais en discuter d'abord.)
Y a-t-il des étapes manquantes ? (Qu'en est-il des messages envoyés pendant la fenêtre de timeout ? Doivent-ils être abandonnés ou réessayés ?)

Le plan est un checkpoint léger. Révise-le, approuve-le, et l'agent continue avec une compréhension partagée de l'intention.

Étape 2 : Implémentation

L'agent écrit le code. Rien ne change ici. Mais parce que le plan existe, l'agent a une feuille de route qu'il peut suivre plutôt que de prendre des décisions ad hoc en cours de route.

Étape 3 : Le commentaire done

Quand l'agent a fini, il poste un rapport de complétion structuré. Pas "fini." Pas "j'ai implémenté la feature." Un compte rendu détaillé de ce qu'il a réellement fait.

DONE: WebSocket reconnection now buffers outbound messages
during CONNECTING state and flushes on successful reconnect.

Changes:
- hooks/use-websocket.ts: Added messageBuffer ref, queue
  messages when readyState !== OPEN, flush in FIFO order on
  'open' event. Added 30s reconnection timeout.
- components/connection-status.tsx: Shows "Reconnecting..."
  badge during buffer state, switches to error toast after
  timeout.

QA Verification:
1. Start dev server and WebSocket server
2. Open app, verify connection dot is green
3. Kill WebSocket server process
4. Trigger an action that sends a WS message (e.g., update
   a bead status)
5. Restart WebSocket server within 30 seconds
6. Verify: the buffered message is delivered, bead status
   updates in the UI
7. Repeat step 3, but wait >30 seconds before restart
8. Verify: error toast appears after timeout

Acceptance criteria:
- [x] Messages sent during reconnection are not lost (step 6)
- [x] Timeout surfaces user-visible error (step 8)
- [x] No behavior change when connection is stable (step 2)

Commit: f4e2a1b

Maintenant le réviseur a tout ce dont il a besoin. Il lit le plan (ce qui était prévu), lit le commentaire done (ce qui a réellement été construit et comment ça a été vérifié), puis regarde le diff avec le contexte complet. La revue du diff passe de "c'est quoi tout ça ?" à "laisse-moi confirmer que ça correspond à ce que l'agent a dit qu'il a fait."

Checklists de revue pour la sortie d'agents

Même avec le récit d'implémentation, tu as besoin d'une approche systématique. Voici une checklist que j'utilise quand je révise la sortie de Claude Code. Elle prend 5-10 minutes par revue et attrape les catégories de bugs que les diffs seuls manquent.

Alignement avec le spec :

L'implémentation adresse-t-elle chaque critère d'acceptation du spec ?
Y a-t-il des changements qui vont au-delà de ce que le spec demandait ?
Le commentaire done mappe-t-il chaque critère à une étape de vérification ?

Contention du périmètre :

L'agent n'a-t-il modifié que les fichiers listés dans son plan ?
S'il a touché des fichiers supplémentaires, y a-t-il une raison déclarée ?
Y a-t-il des changements de "nettoyage" (renommages, reformatages, refactorisations) qui ne faisaient pas partie de la tâche ?

Couverture de tests :

De nouveaux tests existent-ils pour les nouveaux comportements ?
Les tests testent-ils réellement la bonne chose ? (Les agents écrivent parfois des tests qui passent trivialement parce qu'ils testent le mock, pas l'implémentation.)
L'agent a-t-il affirmé avoir exécuté les tests ? Y a-t-il des preuves ?

Cohérence architecturale :

Les changements suivent-ils les patterns existants dans la codebase ?
Y a-t-il de nouvelles abstractions qui dupliquent les existantes ?
La stratégie de gestion d'erreurs correspond-elle au reste du projet ?

Conscience des dépendances :

Si l'agent a ajouté des dépendances, sont-elles justifiées ?
Les changements cassent-ils une fonctionnalité existante ? (Vérifie les fichiers qui importent les modules modifiés.)
Si la tâche a des dépendances avec d'autres tâches, ces dépendances sont-elles résolues ?

Cette checklist fonctionne avec n'importe quel outil de revue de code. Imprime-la sur un post-it, mets-la dans ton template de PR, ou intègre-la dans ta CLAUDE.md pour que l'agent sache à quel standard il sera mesuré. Le point n'est pas les éléments spécifiques. C'est d'avoir un protocole structuré plutôt que "ça a l'air bien."

Beads comme surface de revue

Le pattern plan-comment-done a besoin d'un endroit où vivre. Si les plans et les commentaires done sont dispersés entre les messages Slack, les descriptions de PR et la sortie du terminal, tu perds la connexion entre le spec, le plan, l'implémentation et la vérification.

C'est le problème que beads résout. Beads est un issue tracker Git-natif et open-source où chaque "bead" porte le cycle de vie complet d'une tâche : le spec comme description, les plans de l'agent comme commentaires, les rapports done comme commentaires et les résultats QA comme commentaires. Le tout attaché à une seule entité, cherchable et permanent.

Voici à quoi ressemble le workflow de revue avec le CLI bd :

Créer la tâche avec le spec :

bd create --title "Fix WebSocket reconnection message loss" \
  --description "## Problem
Messages sent during WebSocket reconnection are silently
dropped...

## Acceptance Criteria
1. Messages queued during CONNECTING state are delivered
   on reconnect
2. 30-second timeout surfaces error to user
3. No behavior change when connection is stable" \
  --type bug --priority p1

L'agent réclame le travail et poste un plan :

bd update bb-f4e2 --claim --actor eng1
bd comments add bb-f4e2 --author eng1 "PLAN: Add message
buffer to WebSocket hook...

1. Queue outbound messages when readyState !== OPEN
2. Flush buffer in FIFO order on 'open' event
3. Add 30s timeout with error toast
4. Update reconnection test

Files: hooks/use-websocket.ts, components/connection-status.tsx"

Tu révises le plan en 2 minutes :

bd show bb-f4e2  # Lire le spec + commentaire du plan

Si le plan semble correct, l'agent continue. Sinon, tu commentes avec des corrections avant qu'aucun code ne soit écrit.

L'agent termine et poste un rapport done :

bd comments add bb-f4e2 --author eng1 "DONE: WebSocket
reconnection now buffers outbound messages...

QA Verification:
1. Kill WS server, trigger action, restart within 30s...

Acceptance criteria:
- [x] Buffered messages delivered on reconnect
- [x] Timeout error visible
- [x] No regression on stable connection

Commit: f4e2a1b"

bd update bb-f4e2 --status ready_for_qa

QA vérifie indépendamment :

bd show bb-f4e2  # Lire les étapes de vérification du commentaire done
# Exécuter chaque étape
bd comments add bb-f4e2 --author qa1 "QA PASS: All 3 criteria
verified. Buffer flushes correctly, timeout fires at 30s,
stable connections unaffected."

Toute la trace de revue est au même endroit. Six mois plus tard, quand quelqu'un demande "pourquoi le WebSocket met les messages en buffer pendant la reconnexion ?", la réponse est dans le bead : le spec explique le problème, le plan explique l'approche, le commentaire done explique ce qui a été construit, et le commentaire QA confirme que ça fonctionne.

Quand la revue en terminal atteint son plafond

Exécuter bd show sur une tâche te donne tout. Mais quand tu révises la sortie de plusieurs agents à travers plusieurs workstreams parallèles, le workflow CLI scale linéairement : un bd show par tâche, un bd list pour voir ce qui est prêt pour la revue, un bd show par plan que tu dois approuver.

C'est là que Beadbox s'inscrit. Beadbox est un dashboard en temps réel qui te montre chaque tâche dans ton workspace avec son statut actuel, son dernier commentaire et sa position dans le pipeline de revue. Tu vois quels agents ont posté des plans qui ont besoin de ton approbation. Lesquels ont posté des rapports done prêts pour ta revue. Lesquels sont encore en cours. Le tout se met à jour en direct alors que les agents écrivent des commentaires et changent les statuts via le CLI bd.

Tu n'as pas besoin de Beadbox pour utiliser le pattern plan-comment-done. Le CLI gère tout le workflow. Mais quand tu as cinq agents qui produisent de la sortie vérifiable simultanément, pouvoir voir la file de revue d'un coup d'oeil plutôt que d'interroger chaque tâche individuellement change la vitesse à laquelle tu avances dans le pipeline.

Beadbox est gratuit pendant la bêta, et le CLI beads sur lequel il tourne est open-source.

Le problème de revue ne se résoudra pas tout seul

Le code généré par IA augmente plus vite que notre capacité à le réviser. Les outils que nous avons ont été construits pour une échelle et un workflow différents. Les PRs GitHub, les diffs IDE, même l'analyse statique sophistiquée : aucun d'entre eux ne traite le problème fondamental, à savoir que réviser du code sans connaître l'intention de l'auteur est dramatiquement plus difficile que le réviser avec.

La solution n'est pas de meilleurs outils de diff. C'est de l'intention structurée : un enregistrement de ce que l'agent a prévu de faire, ce qu'il a réellement fait et comment il a vérifié le résultat. Le pattern plan-comment-done te donne cet enregistrement sans ajouter un overhead significatif. L'agent passe 30 secondes à écrire un plan. Tu passes 2 minutes à le réviser. L'agent passe 60 secondes à écrire un rapport done. Tu révises le diff avec le contexte complet plutôt qu'à partir de zéro.

Cinq principes à retenir :

Exige des plans avant le code. Un commentaire de plan de 30 secondes économise des sessions de revue de 20 minutes. Si le plan est faux, corrige-le avant que le code n'existe.
Exige des rapports done structurés. "Fini" n'est pas un rapport done. Des étapes de vérification, un mapping des critères d'acceptation et des hashes de commit sont un rapport done.
Révise par rapport au spec, pas au diff. Le diff montre ce qui a changé. Le spec dit ce qui aurait dû changer. Croise les références.
Impose des limites de périmètre. Si l'agent a touché des fichiers en dehors de son plan, c'est un signal d'alarme. Des changements non planifiés sont des changements non révisés.
Traite la revue comme un protocole, pas un jugement. Une checklist attrape plus de bugs que l'intuition. "Ça a l'air bien" n'est pas une revue.

Les agents continueront d'accélérer. Les diffs continueront de grossir. La question est de savoir si ton processus de revue scale avec eux, ou si tu continues à plisser les yeux sur des diffs de 600 lignes en espérant le meilleur.

Si tu construis des workflows comme ceux-ci, mets une étoile à Beadbox sur GitHub.

La revue de code IA est cassée. Voici ce qui manque.