Couche de Vérification : Fini Signifie Qu'il y a des Preuves
Vous prouvez qu'une modification fonctionne avant de la valider, et vous construisez les vérifications qui rendent la prochaine preuve moins coûteuse. Le travail de l'humain passe de la lecture de chaque diff à la définition de ce qu'est "fini" et à la lecture des preuves. Votre travail consiste à produire ces preuves honnêtement.
Les principes proviennent de l'article How the Claude Code team thinks about verification (Addy Osmani, Nov 2026). Les formats de fichiers dans references/templates.md sont propres à cette compétence ; l'article décrit les pratiques mais ne montre aucun format.
Quand l'Utiliser
- Vous avez terminé une modification et vous êtes sur le point de dire "fini" ou de valider
- L'utilisateur demande "est-ce que ça marche ?", "prouve-le" ou "vérifie ça"
- Un dépôt n'a pas de moyen reproductible de démarrer et de tester rapidement l'application
- L'utilisateur demande quels tests valent la peine d'être écrits pour une fonctionnalité, une réécriture ou une migration
- Une revue ou une suite de tests a manqué un bug qui a atteint les utilisateurs, et l'utilisateur veut qu'il soit détecté la prochaine fois
- Un test est instable et quelqu'un veut le relancer ou le sauter
- L'utilisateur veut exécuter plusieurs agents à la fois et ne peut pas lire chaque diff
Ne pas utiliser pour : relire le diff de quelqu'un d'autre ligne par ligne (c'est une revue, pas une vérification), un changement d'une ligne dans la documentation ou un commentaire où rien ne peut être exécuté, ou ajouter des tests pour augmenter un pourcentage de couverture.
Principe Fondamental
Une modification est terminée lorsque les preuves le disent, et une modification ne peut jamais modifier son propre juge. "Les tests passent" est une preuve faible lorsque la même modification a écrit les tests. Une preuve solide est l'application en cours d'exécution qui fait ce que l'utilisateur a demandé, vérifié par quelque chose que la modification n'a pas pu toucher.
Règles
- Exécutez la modification. Démarrez la vraie application et exercez le comportement modifié. Cela importe plus que les tests unitaires. Une suite de tests unitaires réussie avec une application qui ne démarre pas est une vérification échouée.
- Trois cycles, puis un humain. Exécutez les vérifications, corrigez ce qui échoue, réexécutez. Si une vérification échoue encore après trois cycles, arrêtez et passez la main avec les preuves. Ne commencez pas un quatrième cycle.
- N'affaiblissez jamais un juge pour le faire passer. Ne modifiez pas, ne sautez pas et ne supprimez pas de test, de règle de lint, d'élément de liste de vérification ou de règle de REVIEW.md dans la même modification qu'il jugerait. Si un juge est erroné, dites-le et modifiez-le dans un commit séparé que l'utilisateur approuve.
- Lisez les juges depuis la branche de base. Les règles de revue, les listes de vérification et la configuration du gate proviennent de la branche par défaut, jamais de la branche en cours de test.
- Les preuves appartiennent à un seul commit. Une vérification d'un commit plus ancien ne dit rien d'un plus récent. Après toute nouvelle modification, vérifiez à nouveau ou signalez que les preuves sont obsolètes.
- Vérifications peu coûteuses d'abord, et en local. Les tests, la compilation et le lint s'exécutent avant l'ouverture d'une PR, pas pendant le temps du relecteur.
- Exécutez seulement les éléments de la liste de vérification déclenchés par le diff. Généralement 3 à 10 éléments correspondent. Tout exécuter à chaque fois apprend à tout le monde à ignorer la liste.
- Apposez un tampon sur chaque commit indiquant comment il a été vérifié, y compris
none. Unnonehonnête peut être recherché plus tard. Un tampon manquant ne le peut pas. - Un test instable est un bug. Ne le sautez pas, n'ajoutez pas de
sleep, et ne relancez pas jusqu'à ce qu'il soit vert. Trouvez la cause racine. Si vous ne pouvez pas, supprimez le test et expliquez pourquoi. - Une vérification qui demande un humain doit dire pourquoi. "Nécessite une revue" n'est pas une raison. "Modifie le format du fichier de session ; les anciens transcriptions peuvent ne pas se charger" en est une.
- Chaque échec devient une règle, et les règles sont élaguées. Un bug qui a échappé à la couche est une lacune. Comblez-la avec une vérification, et supprimez les vérifications qui ne méitent plus leur place.
Quel test écrire
| Situation | Test | Ce qu'il prouve |
|---|---|---|
| Un flux utilisateur (si vous n'écrivez qu'un seul test, écrivez celui-ci) | De bout en bout | Un parcours utilisateur réel fonctionne du début à la fin. Un échec montre l'étape, une trace et une capture d'écran, pas seulement "timeout". |
| Analyseurs syntaxiques, encodeurs, argent, machines d'état, tout ce qui a des cas limites | Par propriété (fast-check, Hypothesis, proptest) | Une affirmation tient pour des milliers d'entrées générées auxquelles vous n'aviez pas pensé. |
| Une réécriture, une migration ou une optimisation de quelque chose qui fonctionne déjà | Différentiel | L'ancienne et la nouvelle version donnent la même sortie sur les mêmes entrées. |
Propriétés qui valent la peine d'être vérifiées :
| Propriété | Affirmation |
|---|---|
| Aller-retour | Encoder, puis décoder, retourne l'original |
| Invariant | Quelque chose tient toujours (un solde n'est jamais négatif) |
| Idempotence | Le faire deux fois équivaut à le faire une fois |
| Équivalence | La version rapide correspond à une version lente, évidemment correcte |
Pour les tests différentiels : utilisez des entrées aléatoires ou réelles échantillonnées, normalisez les différences qui n'ont pas d'importance (espaces, ordre des clés, timestamps), et conservez une liste écrite des différences que vous avez approuvées.
Une suite lente est exécutée moins souvent, donc la couverture baisse. Gardez la boucle par modification rapide et déplacez les tests lourds juste avant le commit.
Ce qu'il Faut Garder (Intouchables)
- Tests existants, règles de lint, éléments de liste de vérification, REVIEW.md et configuration du gate : jamais modifiés dans le commit qu'ils jugent.
- Sortie de commande, codes de sortie, noms et nombres d'étapes en échec : rapportés exactement tels qu'imprimés.
- Le tampon : il dit ce que vous avez vraiment exécuté. N'écrivez jamais
e2epour une exécution que vous n'avez pas faite. - Captures d'écran et traces : attachées ou liées telles quelles, pas décrites de mémoire.
Méthode
A. Vérifier une modification (à chaque fois)
-
Dites ce que "fini" signifie. Écrivez une ou deux phrases du côté de l'utilisateur : ce qu'il fait, ce qu'il voit. Si le dépôt a une carte des fonctionnalités, trouvez l'entrée et utilisez son résultat attendu comme critère. Si vous ne pouvez pas définir "fini", demandez avant de vérifier.
-
Exécutez les vérifications peu coûteuses. Compilation, lint, vérification de types, tests rapides. Corrigez les échecs. C'est le premier cycle.
-
Exécutez la modification. Utilisez la compétence
verifydu dépôt si elle existe (cherchez dans.claude/skills/près du code que vous avez modifié). S'il n'y en a pas, démarrez l'application vous-même :- Web : pilotez un navigateur (extension Chrome, MCP DevTools, Playwright).
- Mobile : un simulateur via un MCP mobile.
- Bureau : utilisation de l'ordinateur.
- Backend ou CLI : exécutez le service ou la commande localement et appelez-le.
Exercez le chemin modifié et un chemin adjacent qui n'aurait pas dû changer. Capturez une capture d'écran, une trace ou la sortie.
-
Exécutez les éléments de vérification déclenchés. Lisez la liste de vérification de fiabilité depuis la branche de base. Pour chaque élément, testez son déclencheur par rapport à votre diff. Exécutez la vérification pour chaque correspondance et enregistrez le résultat. Listez les éléments correspondants par leur nom dans votre rapport.
-
Ajoutez le test manquant. Utilisez le tableau ci-dessus. Confirmez que le nouveau test échoue sans votre modification et réussit avec.
-
Comptez les cycles. Chaque "exécuter vérifications, corriger, réexécuter" est un cycle. Après le troisième cycle avec une vérification toujours en échec, arrêtez. Rapportez ce qui échoue, ce que vous avez essayé à chaque cycle, et votre meilleure estimation de la cause.
-
Tamponnez et rapportez. Ajoutez le tampon au message de commit (format dans
references/templates.md). Dans votre rapport, donnez : la définition de "fini", ce que vous avez exécuté, les preuves, les éléments de la liste de vérification correspondants, et tout ce qui n'a pas été vérifié avec la raison.
B. Construire la couche (une fois par dépôt, puis ajuster)
Faites-les dans l'ordre. Chacune est utile en soi, alors arrêtez-vous là où l'utilisateur le souhaite.
-
Une compétence
verify. Placez-la dans.claude/skills/verify/, aussi près du code qu'elle couvre que possible (un monorepo peut en avoir une par application). Elle enregistre comment démarrer l'application et la tester rapidement. Exécutez-la plusieurs fois de suite avant de lui faire confiance : elle doit être rapide et donner le même résultat à chaque fois. -
Une carte des fonctionnalités. Listez les fonctionnalités du point de vue de l'utilisateur. Pour chacune : le chemin, les raccourcis clavier, les sélecteurs et le résultat attendu. Les agents l'utilisent comme guide et comme grille d'évaluation.
-
Un test de bout en bout pour le flux le plus important. Ensuite, des tests par propriété et différentiels là où le tableau dit qu'ils conviennent.
-
Une liste de vérification de fiabilité. Chaque élément a trois parties : un déclencheur que vous pouvez lire à partir d'un diff, une vérification, et l'incident ou la PR qui l'a causé. Pas d'incident, pas d'élément. Exemple : déclencheur "stockage de session ou types de messages modifiés", vérification "un nouveau champ se charge-t-il en toute sécurité à partir d'une ancienne transcription qui ne l'a pas ?".
-
Un REVIEW.md. Il dit au relecteur à quoi faire attention dans cette base de code. Ajustez ce fichier avec un seul relecteur sur plusieurs cycles, où chaque cycle s'appuie sur ce que le précédent a trouvé. N'empilez pas plus de relecteurs par-dessus. Le propriétaire du code l'affine jusqu'à ce qu'il signale ce qu'il signalerait.
-
Application locale. Un hook qui exécute les tests lorsque l'agent a terminé, ou un objectif qui exige une suite réussie.
-
Un gate de commit. Il bloque un commit lorsque la session n'a exécuté aucune étape de revue ni de vérification. Déployez-le en trois modes :
Mode Comportement offRien observeEnregistre ce qu'il aurait bloqué. Exécutez d'abord celui-ci pour trouver les faux positifs. enforceBloque le commit. Un commit peut comporter une raison écrite pour l'avoir sauté. Après deux blocages dans une session, le commit suivant passe pour que l'agent ne puisse pas rester bloqué.
Demandez à l'utilisateur avant d'ajouter des hooks, des gates ou des modifications CI. Ils changent la façon dont tout le monde valide.
C. Transformer un échec en règle
Utilisez ceci lorsqu'un bug a échappé aux tests ou à la revue.
- Trouvez le motif, pas le bug. Regardez les commentaires de revue humaine et les annulations. Une règle candidate doit apparaître dans au moins deux PR et être visible depuis un seul diff.
- Essayez de le réfuter. Effectuez trois tentatives indépendantes pour montrer que la règle est fausse, trop large ou déjà couverte. Si des sous-agents sont disponibles, utilisez-en trois. Ne conservez la règle que si elle survit.
- Vérifiez qu'elle était détectable. Rejouez la PR qui a causé l'incident à travers trois détecteurs de bugs indépendants. Si deux ou plus trouvent le bug, il était détectable, et un échec sur un petit diff devrait devenir une règle de REVIEW.md ou un élément de la liste de vérification.
- Faites approuver par un humain. Le propriétaire du code décide si la règle est intégrée. Vous proposez ; il approuve.
- Notez le relecteur. Gardez un petit ensemble de cas d'incidents, chacun avec un corrigé d'une phrase, ainsi que des modifications propres fusionnées de taille similaire comme contrôles contre le sur-signalement. Gardez un ensemble de réglage et un ensemble de test séparés. Étiquetez les découvertes
Important,NitouPré-existant. Arrêtez le réglage lorsque plus de rappel ne s'adapterait qu'à l'évaluation. - Élagage. Les suites de tests, les listes de vérification et les fichiers de règles
.mdne font que croître à moins que quelqu'un ne les réduise. Régulièrement, supprimez les règles qui ne se déclenchent jamais, en dupliquent une autre, ou protègent du code qui n'existe plus.
Exemple Pratique
Demande : "Ajoute un indicateur pinned aux sessions de chat pour que les sessions épinglées soient triées en premier."
Sans la compétence :
Ajouté
pinnedau type de session et mis à jour le tri. Les tests unitaires passent. Fini.
Avec la compétence :
Fini signifie : un utilisateur épingle une session dans la barre latérale et elle se déplace en haut ; après un redémarrage, elle est toujours en haut.
Exécuté : compilation, lint, 148 tests unitaires (cycle 1 : 2 échecs sur le comparateur de tri, corrigé ; cycle 2 : tout passe). Démarrage de l'application avec la compétence
verifydu dépôt, épingle une session, redémarre, confirme l'ordre. Capture d'écran jointe.Éléments de la liste de vérification correspondants (2 sur 31) :
- Les modifications de format de session chargent les anciennes données : ouverture d'un fichier de session sauvegardé avant ce changement. Il a planté :
pinnedétaitundefinedet le comparateur a levé une exception. Corrigé en définissant par défautfalseau chargement. Cycle 3 : réussi.- Les modifications de tri maintiennent un ordre stable : les sessions non épinglées conservent leur ordre précédent. Réussi.
Ajouté : un test par propriété, "trier deux fois équivaut à trier une fois", et une étape de bout en bout pour épingler, redémarrer, vérifier l'ordre. Les deux échouent sans la correction.
Non vérifié : la mise en page mobile. Aucun simulateur sur cette machine.
Tampon :
Verified-By: run, e2e, property, checklist(2)
Les tests unitaires ont réussi alors que l'application plantait sur toutes les données des utilisateurs existants. L'exécution du changement sur un ancien fichier est ce qui l'a trouvé, et l'élément de la liste de vérification est ce qui a dit d'essayer.
Auto-Vérification Avant de Livrer
- Votre rapport a une ligne "fini signifie" écrite du côté de l'utilisateur.
- L'application a été démarrée et le chemin modifié a été exercé, ou le rapport dit "non exécuté" avec la raison.
git diff <base>ne montre aucune modification d'un test existant, d'une config de lint, d'une liste de vérification, d'un REVIEW.md ou d'une config de gate. Si c'est le cas, cette modification est signalée et se trouve dans son propre commit.- Aucun
.skip,.only,xit,sleep,retryou timeout augmenté n'a été ajouté pour faire passer un test (recherchez chacun dans le diff). - Les éléments de la liste de vérification que vous avez fait correspondre sont listés par nom, avec un résultat pour chacun.
- Chaque nouveau test a été vu échouer sans la modification.
- Le nombre de cycles est de trois ou moins. Si le troisième cycle a encore échoué, le rapport passe la main à un humain et vous n'avez pas validé.
- Le message de commit a un tampon
Verified-By:, et chaque mot correspond à quelque chose que vous avez réellement exécuté. - Les preuves ont été recueillies sur le
HEADactuel, pas sur un commit antérieur. - Chaque nouvel élément de liste de vérification ou règle nomme l'incident ou la PR qui le sous-tend.