chimera-write-the-check-before-the-code

Un critère écrit après l'implémentation décrit l'implémentation. Écrivez d'abord la vérification qui échoue, observez son échec, puis construisez.

PatronProvenance: cleanStatut: activev0.1.0 · Apache-2.0

Conférée par la personne qui a relu la fiche, et non revendiquée par le fichier lui-même. Une fiche que l'agent distille au cours d'une exécution ayant consommé du contenu non fiable naît contaminée et reste en attente de relecture avant d'être un jour récupérée.

Quand elle vient à l'esprit

avant d'implémenter une fonctionnalité
définir ce qui compte comme terminé
écrire le test après le code
aucun critère d'acceptation sur la tâche

C'est dans À éviter et Vérifier que se trouve d'ordinaire la valeur. À faire est la section que tout le monde écrit.

Le corps de la fiche ci-dessus est une traduction. L'original anglais est ce que la CLI importe, ce que l'agent lit à l'exécution et ce que l'empreinte ci-dessous atteste.

Déclencheur

Vous vous apprêtez à implémenter quelque chose dont le « fini » n'est pas encore observable — une fonctionnalité, une correction de bug, un refactor qui prétend préserver le comportement. Cela mord le plus fort quand l'auteur et le seul relecteur sont le même processus : un agent qui travaille seul, ou un commit solitaire que personne d'autre ne lira.

Cela ne s'applique pas à un spike. Une exploration dont le but est de découvrir ce qui est seulement possible n'a pas encore de critère d'acceptation, et en inventer un d'avance ne fait que vous ancrer à la première idée. Écrivez la vérification quand le spike se termine et que le vrai travail commence.

Cette carte parle de la vérification qui n'existe pas encore. Sa jumelle, chimera-prove-the-test- discriminates, parle d'une vérification qui existe déjà et qui est peut-être vide — vous allez chercher celle-là après un correctif, pour montrer que le test échoue sans lui. Même instinct, extrémités opposées du travail.

À faire

Avant de toucher à l'implémentation, écrivez le critère sous une forme qui peut échouer : un test, une assertion, une commande dont le code de sortie bascule, une requête avec une ligne attendue. La prose n'est pas une vérification — « l'endpoint devrait être plus rapide » n'en est pas une ; « p95 sous 200 ms sur le jeu de fixtures, mesuré par la commande de bench existante » en est une.
Dites d'où vient l'observation. De la machine, pas de votre lecture du diff.
Lancez la vérification maintenant, contre le code non modifié. Elle doit échouer. Si elle passe, ou bien le comportement existe déjà — auquel cas arrêtez-vous, il n'y a rien à construire — ou bien la vérification ne teste pas ce que vous croyez.
Lisez le message d'échec. Elle doit échouer pour la raison voulue, pas sur une erreur d'import, une fixture manquante ou une faute de frappe dans le nom du test. Un rouge venu de la mauvaise cause est un vert déguisé.
Livrez la vérification avant l'implémentation, dans son propre commit. Une fois l'implémentation en place, la vérification devient modifiable pour lui correspondre, et elle le sera.
Implémentez. C'est fini quand la vérification passe — pas quand le code a l'air terminé.

À éviter

Écrire l'assertion après coup, à partir de la sortie :


normalize("  Foo ")        # -> "foo"

# test transcribed from that observation
assert normalize("  Foo ") == "foo"

Cette assertion ne peut pas échouer face au code dont elle a été recopiée. Elle enregistre un comportement au lieu d'une exigence, et elle reste donc verte à travers chaque bug sur lequel l'implémentation est cohérente avec elle-même. Si l'exigence était une normalisation NFKC et que vous avez livré strip().lower(), ce test vous donnera raison pour toujours.

Évitez aussi le critère qui n'est qu'une reformulation du changement — « fini quand la fonction est ajoutée », « fini quand la migration s'exécute ». Les deux sont satisfaits par un corps vide.

Vérifier

Deux questions binaires, toutes deux répondables depuis le dépôt :

Avez-vous vu la vérification échouer avant que l'implémentation n'existe ? S'il n'y a aucun moment où elle a été rouge, vous n'avez aucune preuve qu'elle peut le devenir.
La vérification serait-elle encore correcte si la fonctionnalité avait été construite d'une tout autre façon ? Une vérification qui nomme des détails internes — un appel privé, une ligne de journal, une chaîne SQL exacte — est épinglée à votre solution plutôt qu'à l'exigence, et elle bloquera le prochain refactor sans rien attraper.

Concrètement : git log montre la vérification livrée en même temps que l'implémentation ou avant, et annuler le seul commit d'implémentation fait passer la suite au rouge.

Risque

Une exigence que vous ne comprenez pas encore ne peut pas être épinglée par une vérification écrite d'avance. Vous écrirez une assertion précise sur la mauvaise chose, puis vous implémenterez pour la satisfaire — pire que de n'avoir aucune vérification, parce que cela blanchit un malentendu en une suite verte à laquelle un relecteur fera confiance. Quand le critère est réellement inconnu, c'est un signal pour aller demander, une question à la fois, pas pour deviner sous forme de test.

Il y a aussi un coût simple. Pour une correction de faute de frappe ou une modification de documentation, écrire la vérification d'abord est un cérémonial que personne ne paie. La carte gagne sa place quand le comportement est assez porteur pour que quelqu'un souffre d'un « fini » erroné.

L'utiliser

La fiche est une donnée. Clonez le dépôt et importez-la par son chemin — ce qui arrive par le réseau est traité comme contaminé et retenu pour approbation, ce qui est le comportement souhaitable et la raison pour laquelle il n'y a pas d'installateur en une ligne ici.

$git clone https://github.com/brcampidelli/chimera-agent.git

$chimera skills-import chimera-agent/skills/chimera-write-the-check-before-the-code/SKILL.md

Intégrité

SHA-256 du fichier tel qu'il est publié. Qui l'importe peut vérifier que ce qu'il a reçu correspond à ce que cette page affichait.

95d0a1b750e25af7651e85d26106a91f02f563ab1a1422edc4133d16942b67d7

Lire la fiche dans le dépôt →