derive-instead-of-transcribing
Tout ce qui est recopié à la main depuis un autre fichier est correct exactement une fois. Si cela peut être généré, générez-le, et faites échouer le build quand la copie a vieilli.
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
- documenter une liste de commandes
- copier des valeurs d'un projet à l'autre
- garder deux fichiers synchronisés
- écrire une page de référence
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
Deux endroits de votre système détiennent la même information : une config et sa documentation, un schéma et ses types côté client, une palette et le site qui l'utilise, une liste de commandes et une page de référence.
Cela ne s'applique pas quand la seconde copie est délibérément différente — un guide de démarrage soigné n'est pas une copie obsolète de la référence, c'est de la prose avec un rôle différent.
À faire
- Choisissez laquelle des deux est la source. En général celle que le programme lit réellement à l'exécution.
- Générez l'autre, en committant le fichier généré pour que les diffs soient revuables.
- Ajoutez une étape de CI qui régénère et échoue si la copie committée diffère, en indiquant la commande exacte à exécuter dans le message d'erreur.
- Estampillez le fichier généré avec la version ou le commit dont il a été généré, pour qu'un lecteur sache ce qu'il décrit.
À éviter
Maintenir la copie synchronisée en s'en souvenant. Ça fonctionne tant qu'une seule personne garde les deux fichiers en tête, et ça s'arrête dès la première semaine où quelqu'un d'autre touche l'un des deux.
Évitez aussi la version à moitié faite : générer le fichier sans le verrouiller par une vérification. Un artefact qui est parfois régénéré est pire qu'un fichier écrit à la main, parce qu'il porte l'autorité d'être généré tout en étant tout aussi obsolète.
Et évitez de générer de la prose. Le matériel de référence se génère bien ; l'explication non, et une page de descriptions de champs développées mécaniquement est une page que personne ne lit.
Vérifier
Modifiez la source, ne régénérez pas, et poussez. La CI doit passer au rouge et vous dire quoi exécuter.
Lisez ensuite le fichier généré pour la chose que vous avez changée et confirmez qu'elle y est — la barrière prouve que le fichier est à jour, pas que le générateur a capturé le champ qui vous intéresse.
Risque
Un artefact généré que personne ne peut lire va à l'encontre du but recherché ; si la sortie n'a de sens que pour une machine, il lui faut une couche de rendu, ce qui fait encore plus de code à maintenir.
Il y a aussi un coût de couplage. Le consommateur dépend désormais de la forme du producteur, et un refactor d'un côté casse un build de l'autre. C'est généralement le but recherché — mais cela signifie que la barrière doit être facile à satisfaire, sinon quelqu'un la désactivera pendant un refactor sans rapport et oubliera de la réactiver.
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.gitchimera skills-import chimera-agent/skills/derive-instead-of-transcribing/SKILL.mdInté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.
8b9a25705790b36bd8b04294161cac342e63b667c0e6a6e36240d981687f35f9