couche-de-verification

Prouver qu'une modification effectuée par un agent fonctionne avant de la valider, et construire les vérifications qui rendent cette preuve peu coûteuse. Exécute la modification dans l'application réelle, choisit le bon test (de bout en bout, par propriété ou différentiel), exécute seulement les vérifications de fiabilité déclenchées par le diff, s'arrête après trois cycles de correction et passe la main à un humain, appose un tampon indiquant comment chaque commit a été vérifié, et transforme chaque échec en règle. Configure également la couche elle-même dans un dépôt – une compétence `verify`, une carte des fonctionnalités, une liste de vérification de fiabilité déclenchée par diff, un REVIEW.md, un gate de commit – et empêche la modification de modifier ses propres juges.

Qu'est-ce que couche-de-verification ?

La compétence **Couche de Vérification** est conçue pour les agents d'IA (comme Claude Code, Cursor, Codex) qui effectuent des modifications de code et doivent prouver leur bon fonctionnement avant validation. Elle repose sur un principe central : une modification est terminée uniquement lorsque des preuves solides le démontrent, et une modification ne peut jamais modifier son propre juge. Cette compétence guide l'agent à travers un processus rigoureux : exécuter la modification dans l'application réelle, sélectionner le type de test approprié (de bout en bout pour les flux utilisateur, par propriété pour les cas aux limites, différentiel pour les réécritures), exécuter uniquement les vérifications de fiabilité pertinentes déclenchées par le diff, et s'arrêter après trois cycles d'échec pour laisser un humain décider. Elle impose également des règles strictes comme ne jamais affaiblir un juge, lire les juges depuis la branche de base, et ne pas sauter les tests instables mais en trouver la cause racine. Pour la mise en place initiale, elle propose une méthode complète : création d'une compétence `verify` locale, d'une carte des fonctionnalités, de tests de bout en bout, d'une liste de vérification de fiabilité, d'un REVIEW.md, d'une application locale et d'un gate de commit. Enfin, elle détaille comment transformer un bug passé à travers les mailles en une nouvelle règle, avec un processus de validation par un humain et un élagage régulier pour éviter l'accumulation de règles inutiles.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kleenpulse/verification-layer/tree/main

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. Apposez un tampon sur chaque commit indiquant comment il a été vérifié, y compris none. Un none honnête peut être recherché plus tard. Un tampon manquant ne le peut pas.
  9. 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.
  10. 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.
  11. 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

SituationTestCe qu'il prouve
Un flux utilisateur (si vous n'écrivez qu'un seul test, écrivez celui-ci)De bout en boutUn 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 limitesPar 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érentielL'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-retourEncoder, puis décoder, retourne l'original
InvariantQuelque chose tient toujours (un solde n'est jamais négatif)
IdempotenceLe faire deux fois équivaut à le faire une fois
ÉquivalenceLa 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 e2e pour 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)

  1. 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.

  2. Exécutez les vérifications peu coûteuses. Compilation, lint, vérification de types, tests rapides. Corrigez les échecs. C'est le premier cycle.

  3. Exécutez la modification. Utilisez la compétence verify du 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.

  4. 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.

  5. Ajoutez le test manquant. Utilisez le tableau ci-dessus. Confirmez que le nouveau test échoue sans votre modification et réussit avec.

  6. 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.

  7. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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 ?".

  5. 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.

  6. Application locale. Un hook qui exécute les tests lorsque l'agent a terminé, ou un objectif qui exige une suite réussie.

  7. 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 :

    ModeComportement
    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.

  1. 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.
  2. 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.
  3. 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.
  4. Faites approuver par un humain. Le propriétaire du code décide si la règle est intégrée. Vous proposez ; il approuve.
  5. 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, Nit ou Pré-existant. Arrêtez le réglage lorsque plus de rappel ne s'adapterait qu'à l'évaluation.
  6. Élagage. Les suites de tests, les listes de vérification et les fichiers de règles .md ne 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é pinned au 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 verify du 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 était undefined et le comparateur a levé une exception. Corrigé en définissant par défaut false au 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

  1. Votre rapport a une ligne "fini signifie" écrite du côté de l'utilisateur.
  2. L'application a été démarrée et le chemin modifié a été exercé, ou le rapport dit "non exécuté" avec la raison.
  3. 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.
  4. Aucun .skip, .only, xit, sleep, retry ou timeout augmenté n'a été ajouté pour faire passer un test (recherchez chacun dans le diff).
  5. 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.
  6. Chaque nouveau test a été vu échouer sans la modification.
  7. 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é.
  8. Le message de commit a un tampon Verified-By:, et chaque mot correspond à quelque chose que vous avez réellement exécuté.
  9. Les preuves ont été recueillies sur le HEAD actuel, pas sur un commit antérieur.
  10. Chaque nouvel élément de liste de vérification ou règle nomme l'incident ou la PR qui le sous-tend.

Skills associés