Boucles de vérification Claude Code : tableau du banc, checklist Stop hook et sources

TL;DR

• La recommandation d'Anthropic est juste sur le fond : le modèle qui dispose d'une boucle de feedback produit un meilleur travail. Le problème, c'est qui exécute la boucle. Sur 116 runs, le /verify intégré a renvoyé PASS 24 fois sur 24, y compris sur un changement qui cassait une exigence énoncée.
• Un modèle qui vérifie son propre changement partage son angle mort. Haiku 4.5 a raté le même cas de champ unique dans 11 runs sur 11, dans toutes les configurations avec le même modèle, et son propre /verify a coché le mauvais cas.
• Sur Opus 5.5, /verify a coûté 2,5x ($0.96 contre $0.39) sans changer aucun résultat. Opus seul a eu 12 sur 12 et a lancé la suite de tests de lui-même dans 11 de ces runs.
• Un skill de projet est optionnel pour le modèle : il s'est déclenché dans 10 runs sur 24, 0 sur 6 avec Haiku. Un Stop hook s'est déclenché à chaque run pour environ 20 % de plus sur Opus.
• La vérification qui a marché venait de quelqu'un d'autre que l'auteur : le même /verify lancé par Opus a dit FAIL 3 fois sur 3 sur le changement de Haiku et a nommé le bug. Branché en Stop hook, il a fait corriger le bug à Haiku 3 fois sur 3, à $1.36 par tâche contre $0.76 pour Opus seul.
• À copier : un Stop hook pour la partie déterministe, un vérificateur qui n'est pas l'auteur pour le jugement, et pas de /verify sur Opus pour du travail bien spécifié.

Ce que disent les mesures

L'affirmation d'Anthropic : « Si Claude a cette boucle de feedback, il multipliera par 2-3 la qualité du résultat final. » s4 Le blog en tire un workflow d'adoption en 5 étapes : choisir votre contrôle manuel le plus répété, essayer le /verify intégré, écrire la procédure en langage clair dans un skill, la rendre déterministe, puis la déplacer en CI. s1 Depuis la v2.1.215, « Claude n'exécute plus de lui-même les skills /verify et /code-review ; invoquez-les avec /verify ou /code-review quand vous les voulez. » s3

Les retours du terrain portent sur des vérifications annoncées mais non exécutées. L'issue #96416 est un verdict de revue avec 19 points soulevés, 5 vérifiés, et un « accept as-is » rendu quand même. s6 L'issue #97039 est une affirmation « held up » après des vérifications partielles malgré une checklist chargée. s7 « Le build passe » et « prêt pour la production » sont deux barres différentes, et chaque raté coûte 2-3 tours de relance. s8

Notre banc a noté chaque « done » avec des tests d'acceptation cachés que l'agent n'a jamais vus. 112 runs de tâches + 4 runs /verify inter-modèles = 116 runs, $66.29 de dépense en équivalent API. Faux « done » : 12 sur 112, dont 11 de Haiku sur T6 dans toutes les configurations A à E, et 1 de Sonnet sur T6 avec le skill, où ses propres nouveaux tests échouaient et où le skill ne s'est jamais déclenché. s1

Le /verify intégré a dit Verdict: PASS dans 24 runs sur 24 avec les trois modèles (23 exploitables, 1 pass sans libellé), y compris sur le T6 cassé de Haiku. Sur Opus, il a coûté $0.96 contre $0.39 sans lui (2,5x) et 125 s contre 75 s ; il n'a changé aucun résultat. s3

Le skill de projet écrit selon le workflow en 5 étapes a été invoqué dans 10 runs sur 24 : Opus 8/12, Sonnet 2/6, Haiku 0/6. Le Stop hook s'est déclenché à chaque run, à $0.47 contre $0.39 sur Opus (+20 %). s19

L'angle mort est une seule exigence, T6 exig. 4 : un seul update qui donne la même valeur unique à plusieurs documents trouvés doit lever DuplicateKeyError. Haiku l'a raté dans 11 runs sur 11, dans toutes les configurations (plain, /verify, skill, hook, tests d'abord). Le /verify de Haiku a vérifié « update d'un doc vers l'email d'un autre » et n'a jamais essayé un update touchant plusieurs documents. La règle tests d'abord n'a pas aidé : 3/3 ratent toujours l'exig. 4, et un a aussi cassé l'exig. 3. s1

Le même changement de Haiku, /verify lancé par un autre modèle : Sonnet a dit PASS (1/1), Opus a dit FAIL 3/3, chaque run nommant le même cas, un update écrivant la même valeur dans plusieurs documents, à $0.39 à $0.47 par vérification. En Stop hook sur Haiku (configuration F), le vérificateur Opus a fait corriger le bug dans 3 runs sur 3 ; tous les trois ont atteint le plafond de 60 tours en corrigeant, pour une moyenne de $1.36 par run T6 vérificateur compris, contre $0.76 pour Opus écrivant T6 seul avec 0 faux « done ». s19

Mesures

Banc : Claude Code 2.1.283 en headless (claude -p), répertoire de config isolé, même prompt par tâche, plafond de 60 tours. Dépôt : msiemens/tinydb @ 18d73a1 (Python, 226 tests). Six demandes de fonctionnalité T1 à T6 avec 5 exigences énoncées chacune (T5 : 6). Des tests d'acceptation cachés, un par exigence énoncée et jamais montrés à l'agent, notent chaque run ; la suite du dépôt tourne aussi. Un faux « done » est un run qui termine en annonçant l'achèvement alors qu'un test caché ou la suite du dépôt échoue.

Configurations : A plain (la demande seule) ; B /verify (A, puis le /verify intégré en second tour) ; C skill verify (un skill de projet invocable par le modèle, écrit selon le workflow en 5 étapes) ; D Stop hook (prove-it.py : bloque l'arrêt tant que la suite est rouge, et bloque le premier arrêt en demandant une ligne de preuve par exigence) ; E tests d'abord (une règle CLAUDE.md : un test qui échoue par exigence avant tout code) ; F hook vérificateur Opus (claude -p /verify --model opus sur le changement, bloque sur un verdict non PASS, 2 tours max).

Limites : un seul dépôt (une petite bibliothèque Python bien testée), six demandes bien spécifiées, 1 à 3 répétitions par cellule, runs headless. Les tests cachés ne vérifient que ce que la demande énonce.

À faire lundi

• Écrivez vous-même un test d'acceptation par exigence énoncée, avant de lire le « done » du modèle. Les tests cachés du banc ont attrapé ce que chaque vérification par le même modèle a manqué.
• Ajoutez un Stop hook qui lance votre suite de tests et renvoie une décision block tant qu'elle est rouge. Il se déclenche à chaque run ; un skill, non.
• Faites coûter au premier arrêt d'une tâche une ligne de preuve par exigence (le pattern prove-it.py) : une commande et sa sortie, pas une phrase.
• Confiez le contrôle de jugement à un modèle qui n'a pas écrit le changement : claude -p /verify --model opus sur le diff, bloquant sur un verdict non PASS, plafonné à 2 tours.
• Sur Opus 5.5 avec une demande bien spécifiée, arrêtez de taper /verify par habitude. Il a coûté 2,5x et n'a rien changé en 12 runs ; gardez-le pour une zone sans tests ou une chasse à un bug existant.
• Si vous déléguez à Haiku 4.5 pour le coût, budgétez le vérificateur : $1.36 par tâche avec le hook Opus contre $0.76 pour Opus seul.
• Consignez chaque nouvel essai d'un correctif raté dans un registre et arrêtez la boucle dès une répétition, pour qu'un hook bloquant ne brûle pas de tokens sur le même mauvais patch.
• Relisez vos exigences pour le cas multi-lignes : « un update qui touche plusieurs documents » est la forme du cas que 11 runs Haiku sur 11 n'ont jamais essayé.

Aller plus loin

• Le workflow en 5 étapes et l'échelle de maturité, du contrôle manuel à la CI : les barreaux du haut (CI et gates de PR) sont là où va la partie déterministe une fois votre hook au point en local. s1
• Sémantique du Stop hook : une décision block avec une raison renvoie le tour au modèle ; lisez le contrat des codes de sortie et du JSON avant d'écrire votre propre gate. s19
• Groundtruth, un Stop hook qui refuse la fin du tour tant que les checks ne passent pas : la version déterministe de l'idée, à lire comme implémentation de référence. s5
• regressionledger, le côté coût : un hook qui empêche la boucle de retenter le même correctif raté, la pièce qui manquait à notre Stop hook quand les runs ont atteint le plafond de 60 tours. s10

Sources

• Building verification loops in Claude Code with skills, Anthropic blog. Pourquoi le lire : le workflow en 5 étapes et l'échelle sur lesquels le skill du banc a été construit.
• Building verification loops in Claude Code, official Claude channel. Pourquoi le lire : trois minutes sur ce que fait /verify au premier lancement, avant de décider de le garder.
• Claude Code CHANGELOG, GitHub. Pourquoi le lire : la v2.1.215 est le moment où /verify est devenu invocable uniquement par l'utilisateur, ce qui change sa fréquence d'exécution chez vous.
• Boris Cherny: give Claude a way to verify its work, X. Pourquoi le lire : l'affirmation « 2-3x la qualité », dans sa formulation exacte.
• Groundtruth, GitHub. Pourquoi le lire : un vrai gate Stop hook à copier plutôt que d'écrire le vôtre de zéro.
• Issue #96416, GitHub. Pourquoi le lire : une transcription datée d'un verdict de revue qui a vérifié 5 points sur 19 et accepté quand même.
• Issue #97039, GitHub. Pourquoi le lire : le même échec deux jours plus tard avec une checklist chargée : la checklist n'est donc pas le remède.
• AI coding agents can verify some of their work now, dev.to. Pourquoi le lire : l'énoncé le plus clair de l'écart entre « le build passe » et « prêt pour la production ».
• Saguaro, GitHub. Pourquoi le lire : le débat revue dans la boucle contre revue au niveau de la PR, avec le contre-argument dans les commentaires.
• regressionledger, GitHub. Pourquoi le lire : le problème de coût des retries que crée un hook bloquant, et une façon de le plafonner.
• SPICE simulation to oscilloscope to verification with Claude Code, personal blog. Pourquoi le lire : une boucle de vérification dont l'oracle est un instrument physique.
• Hooks reference, code.claude.com. Pourquoi le lire : le contrat de décision block que votre Stop hook doit respecter.

FAQ

Le /verify intégré attrape-t-il des bugs ?

Pas dans ce banc. Il a renvoyé PASS dans 24 runs sur 24 avec Opus 5.5, Sonnet 5 et Haiku 4.5, y compris sur un changement de Haiku qui cassait une exigence énoncée. Sa seule trouvaille utile était un bug amont préexistant sans lien avec le changement.

Pourquoi un vérificateur plus fort aide-t-il un auteur plus faible ?

Le contrôle de Haiku a testé le cas auquel il avait déjà pensé. Opus, avec le même changement et le même /verify, a essayé un update touchant plusieurs documents et a dit FAIL 3 fois sur 3. Sonnet a dit PASS. Le vérificateur doit voir un cas que l'auteur n'a pas vu.

Vaut-il mieux vérifier Haiku avec Opus, ou écrire avec Opus ?

Écrire avec Opus. Le hook vérificateur Opus sur Haiku a coûté en moyenne $1.36 par run T6 et a atteint le plafond de 60 tours à chaque fois ; Opus écrivant T6 seul a coûté $0.76 en moyenne avec 0 faux « done ».