Comment vérifier le code écrit par Claude Code ? Le protocole des 4 portes

TL;DR — vérifier le code d’un agent en une minute

• Le problème : un agent s’arrête quand le travail *a l’air* fini. En 2025, 66 % des développeurs citent comme première frustration les solutions IA « presque justes, mais pas tout à fait » (Stack Overflow Developer Survey 2025).
• La règle unique : ne jamais accepter une affirmation, toujours exiger une preuve exécutable — sortie de test, code de retour de build, capture d’écran, diff.
• Les 4 garde-fous documentés par Anthropic : la vérification demandée dans le prompt, la condition /goal ré-évaluée à chaque tour, le hook Stop qui bloque la fin du tour, et le sous-agent de revue en contexte neuf.
• Notre protocole maison : 4 portes successives — syntaxe, build, déploiement, page réelle. Franchir une seule porte ne prouve rien.
• Le piège n° 1 : un HTTP 200 n’est pas une preuve de publication. Sur nos sites en application monopage, une page inexistante répond 200 avec 1,6 Ko de coquille vide.

Vérifier le code écrit par Claude Code, c’est lui imposer une preuve exécutable plutôt que de croire son résumé. Une preuve exécutable, c’est n’importe quoi qui produit un *réussi* ou un *échoué* que l’agent peut lire lui-même : une suite de tests, le code de retour d’un build, un linter, un script qui compare une sortie à un fichier de référence, ou une capture d’écran confrontée à une maquette. C’est mot pour mot la doctrine de la documentation officielle d’Anthropic en 2026, qui consacre une section entière au sujet : *« Donnez à Claude une vérification qu’il peut lancer »*.

La raison est structurelle, pas morale. Un agent de code ne ment pas : il conclut. Il s’arrête quand le travail a l’air fini, et sans vérification exécutable, « a l’air fini » est le seul signal dont il dispose. C’est vous qui devenez alors la boucle de vérification — et chaque erreur attend patiemment que vous la remarquiez. La documentation d’Anthropic nomme d’ailleurs ce piège dans sa liste des échecs courants : *the trust-then-verify gap*, l’écart entre une implémentation plausible et une implémentation correcte.

Cet article donne deux choses : ce que la doc officielle décrit réellement (et rien de plus), puis le protocole en 4 portes que nous appliquons quotidiennement sur un parc d’une vingtaine de sites dont le contenu est écrit et publié par des agents — avec les seuils chiffrés qui nous servent de garde-fous.

Pourquoi le code écrit par une IA a-t-il l’air juste sans l’être ?

Les chiffres sont têtus. L’édition 2025 du Stack Overflow Developer Survey mesure 84 % de développeurs qui utilisent ou prévoient d’utiliser des outils d’IA, mais seulement 32,7 % qui font confiance à la justesse de leur sortie, contre 45,7 % qui s’en méfient activement. La première frustration citée touche 66 % des répondants : les réponses « presque justes, mais pas tout à fait ». La deuxième en découle mécaniquement : 45,2 % trouvent que déboguer du code généré par IA prend plus de temps.

Ce profil d’erreur est particulier. Une erreur humaine est souvent grossière et visible : ça ne compile pas, ça plante. Une erreur d’agent est plausible : le code compile, la fonction existe, la signature est correcte, le nom de variable est bien choisi — et le comportement est faux dans le cas limite que personne n’a testé. C’est exactement le type de défaut qu’une relecture rapide ne détecte pas, parce que la relecture rapide cherche des anomalies de forme.

« Le rôle premier de l’IA est celui d’un amplificateur : elle magnifie les forces et les faiblesses existantes d’une organisation. » — DORA, State of AI-assisted Software Development, 2025

C’est la formule qui résume le mieux le sujet. Si votre discipline de vérification était déjà molle avant l’IA, un agent ne la corrigera pas : il produira simplement dix fois plus de code non vérifié dans le même temps.

Que dit la documentation officielle d’Anthropic sur la vérification ?

La doc Claude Code de 2026 décrit quatre niveaux de garde-fou, du plus léger au plus contraignant. Ils ne s’excluent pas : ils se cumulent selon l’enjeu.

Trois détails de la doc méritent d’être connus, parce qu’ils changent la façon de s’en servir.

1. Le hook Stop est un vrai verrou, mais pas infini. Il exécute votre script à la fin de chaque tour et empêche l’agent de conclure tant que la vérification échoue. Anthropic documente explicitement la soupape : Claude Code outrepasse le hook et met fin au tour après 8 blocages consécutifs. Autrement dit, un hook Stop n’est pas une boucle infinie de correction — c’est un budget de 8 tentatives. Si votre vérification n’est pas franchissable en 8 essais, elle est mal calibrée.

2. Un hook PostToolUse ne peut pas bloquer. Dans la table des codes de sortie, la sortie 2 vaut « erreur bloquante » et renvoie stderr à Claude — mais uniquement pour les événements bloquants (PreToolUse, Stop, PermissionRequest, PreCompact…). Pour PostToolUse, la sortie 2 affiche le message à l’utilisateur sans que Claude le voie. C’est la confusion la plus fréquente quand on veut « faire tourner les tests après chaque édition » : le hook lance bien les tests, mais il ne peut pas empêcher l’agent de continuer. Si vous voulez un verrou, c’est Stop qu’il faut viser. Notre guide pratique des hooks détaille la mécanique complète.

3. Le relecteur ne doit pas être l’auteur. La doc recommande un sous-agent de revue en contexte neuf : il ne voit que le diff et les critères, pas le raisonnement qui a produit le changement, donc il juge le résultat pour lui-même. Anthropic accompagne la recommandation d’un avertissement précieux : un relecteur à qui l’on demande de trouver des manques en trouvera toujours, même quand le travail est sain — d’où la consigne de ne signaler que ce qui affecte la correction ou les exigences énoncées, sous peine de sur-ingénierie. Nous détaillons ce mode de délégation dans notre guide des sous-agents.

Et en amont, il y a le mode plan : explorer, planifier, puis coder. Ce n’est pas de la vérification de code à proprement parler, c’est de la vérification d’intention — s’assurer qu’on ne résout pas parfaitement le mauvais problème. La doc précise l’arbitrage honnêtement : le mode plan ajoute de la charge, et si vous pouvez décrire le diff en une phrase, sautez-le.

Le protocole des 4 portes : notre grille de vérification

Voici la partie que vous ne trouverez pas dans la documentation, parce qu’elle vient de l’exploitation. Nous faisons publier du contenu quotidiennement par des agents sur une vingtaine de sites. Chaque étape ci-dessous a été ajoutée après un incident réel, pas par précaution théorique.

Le principe qui tient tout : une porte franchie ne prouve rien sur les suivantes. Un commit poussé n’est pas un build réussi. Un build réussi n’est pas un déploiement. Un déploiement n’est pas une page lisible.

La porte 1 est née d’un cas précis, et il est instructif. Un script de génération de pages statiques analysait notre fichier de données avec des expressions régulières attendant des clés non entourées de guillemets. L’agent, très raisonnablement, avait produit du JSON strict — clés entre guillemets. Résultat : l’expression régulière ne trouvait pas l’entrée, le script passait à la suivante sans erreur, le build finissait en vert, et l’article n’existait tout simplement pas en ligne. Aucune alarme nulle part. C’est le pire scénario de tous : un échec silencieux qui coche toutes les cases de succès.

D’où la règle que nous avons gravée dans nos consignes : un parseur ne doit jamais ignorer une entrée en silence. S’il ne comprend pas, il doit échouer bruyamment. La même logique vaut pour vos hooks de vérification : un contrôle qui n’émet rien quand tout casse est indiscernable d’un contrôle qui n’émet rien parce que tout va bien.

Comment savoir si c’est vraiment en ligne ? Le piège du HTTP 200

C’est la porte 4, et c’est celle qui trompe le plus de monde. Un code 200 ne prouve pas qu’une page existe. Sur une application monopage avec une règle de repli qui renvoie l’index pour toute URL inconnue, chaque adresse imaginable répond 200. Vous pouvez tester une URL contenant une faute de frappe : 200. Vous pouvez tester une page jamais écrite : 200.

Nous utilisons trois contrôles cumulés, avec des seuils issus de mesures réelles sur notre parc.

Un exemple chiffré tiré de notre parc : sur un de nos sites, une page d’article servait 9,5 Ko de coquille vide aux robots — le contenu n’apparaissait qu’après exécution du JavaScript. Après ajout d’une génération statique en fin de build, la même URL sert 20,8 Ko de contenu réel. Le code HTTP était 200 avant comme après. Seule la mesure du poids et la présence effective du texte dans la source ont révélé la différence.

Le contrôle le plus rentable est le plus bête : comparer le HTML de la page à celui de la page d’accueil. S’ils sont identiques, vous regardez un repli, pas votre article. Ce test-là attrape en une commande la quasi-totalité des fausses publications.

Quel garde-fou choisir selon le risque ?

Tout empiler coûte cher en temps de mise en place. Notre arbitrage :

• Tâche exploratoire, vous êtes devant l’écran : la vérification dans le prompt suffit. Demandez la commande de test et l’itération dans le même message, et exigez la preuve — la sortie de la commande, pas un résumé. Relire une sortie de test est plus rapide que relancer le test soi-même.
• Tâche multi-fichiers, vous surveillez d’un œil : mode plan en amont, puis sous-agent de revue adversariale sur le diff avant de considérer que c’est terminé. Le contexte neuf est ce qui rend la revue utile.
• Exécution non surveillée, ou publication automatique : hook Stop avec un script de vérification déterministe, plus le protocole des 4 portes en aval. C’est le seul montage où l’agent ne peut pas conclure à tort sans que quelque chose s’en aperçoive.
• Le tout dans une chaîne d’intégration : le mode non interactif avec sortie JSON permet de brancher l’agent dans un pipeline et de traiter son résultat comme n’importe quelle étape de build — avec la même exigence de code de retour.

Un mot sur le coût, puisque c’est souvent l’objection. Un hook Stop est un script shell : il ne consomme aucun jeton. Une revue par sous-agent, elle, consomme un contexte complet — mais dans une fenêtre séparée, ce qui protège votre conversation principale. Faire vérifier par l’agent qui a écrit revient moins cher en jetons, et ne vaut presque rien en fiabilité : il est juge et partie.

Les erreurs qui passent quand même toutes les portes

Aucun protocole n’est étanche. Voici celles qui nous ont coûté le plus cher.

1. Le contrôle qui ne surveille que le succès. Un filtre qui guette uniquement le message de réussite reste muet pendant un plantage, un blocage ou une sortie inattendue. Or le silence ressemble exactement à « ça tourne encore ». Tout contrôle doit couvrir les états d’échec autant que l’état de succès.
2. Le composant importé mais jamais rendu. Nous avons vécu cinq versions d’une application où un avis de conformité était bien importé dans le code — et plus jamais affiché, parce qu’un ancien parcours d’interface avait été remplacé. Un import n’est pas un rendu : cherchez l’usage réel, pas la déclaration.
3. La course entre deux commits. Deux poussées à quelques secondes d’écart peuvent déclencher un seul build, qui prend le dépôt dans un état intermédiaire. La parade est simple : un commit atomique multi-fichiers plutôt que deux commits rapprochés.
4. La vérification lancée trop tôt. Sur les hébergements à build asynchrone, un contrôle exécuté dix secondes après le push mesure l’ancien déploiement. Un faux négatif ici est aussi coûteux qu’un faux positif : il vous fait « corriger » quelque chose qui n’était pas cassé.
5. La confiance accordée à un résumé. L’agent dit « les tests passent ». Demandez la sortie. C’est la recommandation explicite de la doc d’Anthropic : faire produire la preuve plutôt que l’affirmation.

Ce protocole n’a rien de spécifique à la publication de contenu : c’est la même grille qui vaut pour un déploiement d’application, une migration de base ou un correctif en production. Si vous industrialisez ce type de boucle agent-vérification, iaCockpit explore le même terrain côté pilotage d’agents en production.

FAQ

Faut-il faire relire le code par le même agent qui l’a écrit ?

Non, ou alors seulement en dernier recours. Un agent qui relit son propre travail est biaisé en faveur du code qu’il vient de produire, et son contexte contient déjà le raisonnement qui l’a mené à cette solution. La documentation d’Anthropic recommande un sous-agent en contexte neuf, qui ne voit que le diff et les critères, précisément pour que celui qui juge ne soit pas celui qui a fait.

Un hook peut-il bloquer un agent tant que les tests ne passent pas ?

Oui, mais uniquement avec l’événement Stop, pas PostToolUse. Le hook Stop exécute votre script à la fin de chaque tour et empêche la conversation de se terminer si la vérification échoue. Attention à la limite documentée : Claude Code outrepasse le hook et met fin au tour après 8 blocages consécutifs. Un hook Stop est donc un budget de 8 tentatives de correction, pas une boucle infinie.

Un code HTTP 200 prouve-t-il qu’une page est bien publiée ?

Non, et c’est le faux positif le plus courant. Une application monopage avec une règle de repli renvoie 200 pour n’importe quelle URL, y compris celles qui n’existent pas. Il faut trois contrôles cumulés : le poids du HTML brut (moins de 10 Ko signale généralement une coquille vide), la présence effective du texte dans la source, et une comparaison avec la page d’accueil — un HTML identique révèle un repli.

Le mode plan améliore-t-il vraiment le taux de réussite ?

Il réduit surtout le risque de résoudre parfaitement le mauvais problème, ce qui est le mode d’échec le plus coûteux car il n’est détecté qu’à la fin. La documentation officielle recommande de séparer exploration, planification et exécution quand la tâche touche plusieurs fichiers ou que vous êtes incertain de l’approche, et de le sauter quand le diff tient en une phrase. C’est un arbitrage, pas une règle absolue.

Combien de temps coûte la mise en place d’un protocole de vérification ?

La version prompt est gratuite et s’applique dès la prochaine tâche. Un hook Stop avec un script de test tient en une vingtaine de lignes de shell et se rentabilise dès la première exécution non surveillée. Le protocole complet en 4 portes demande quelques heures pour être scripté proprement, mais il remplace un travail de relecture manuelle qui, lui, se paie à chaque publication.

*Article publié le 3 août 2026. Sources officielles vérifiées à cette date.*