Aller au contenu
Chimera
Télécharger
Français

← Skills

chimera-ground-it-in-the-source

Prenez la signature depuis la version installée, pas depuis votre mémoire — une API plausible est indiscernable d'une vraie tant qu'elle n'a pas été exécutée.

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

  • appeler une bibliothèque que je n'ai pas écrite
  • comment s'appelle ce paramètre
  • l'API a changé entre deux versions
  • coder de tête avec un framework
  • AttributeError sur une méthode censée exister

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 à écrire un appel vers la bibliothèque, le framework ou la CLI de quelqu'un d'autre : un nom de méthode, un argument nommé, une clé de configuration, la forme d'une valeur de retour, un flag. Cela vaut d'autant plus que le souvenir semble sûr, car la confiance est produite de la même façon que l'API existe ou non.

Cela ne s'applique pas aux primitives du langage que vous utilisez en permanence, et ce n'est pas une consigne d'aller chercher la documentation avant d'écrire dict.get. La ligne de partage est de savoir si une erreur serait détectée immédiatement par la prochaine chose que vous exécutez.

À faire

  1. Récupérez la version réellement installée, pas celle dont vous vous souvenez d'avoir lu la doc : uv pip show <pkg>, ou python -c "import pkg; print(pkg.__version__)".
  2. Lisez ce qui est installé. python -c "import inspect, pkg; print(inspect.signature(pkg.fn))", ou ouvrez le fichier sous site-packages, ou lancez --help sur le binaire présent dans le PATH. C'est là qu'est l'autorité, parce que c'est le code qui va s'exécuter.
  3. Quand vous vous appuyez sur un article de blog, un README trouvé sur le web ou votre propre souvenir, traitez-le comme une hypothèse et confirmez-le à l'étape 2. Les sites de documentation décrivent la dernière version publiée ; votre lockfile n'y est peut-être pas figé.
  4. Exercez l'appel une fois dans un extrait jetable et affichez la valeur de retour réelle avant d'écrire du code qui indexe votre supposition à son sujet. Les formes imbriquées — ["choices"][0]["message"] — sont là où la mémoire est la moins fiable et la moins susceptible d'échouer bruyamment.
  5. Laissez la preuve à côté du code : la version, et la signature ou la sortie d'aide que vous avez lue. Un commentaire ou le corps de la PR suffit, et cela indique au lecteur suivant contre quoi le code a été écrit.

À éviter

Écrire du texte en forme d'API. L'échec n'est pas une faute de frappe — une faute de frappe lève une exception immédiatement et se corrige en quelques secondes. C'est un nom qui respecte chacune des conventions de nommage de la bibliothèque et qui n'existe pas :

Un cas réel tiré de ce dépôt, et c'est la forme qui compte — la supposition n'était pas absurde, elle était raisonnable :


from chimera.core.checkpoint import WorkspaceGuard, diff_snapshots   # ImportError

# Where it actually is. One grep, before writing the line, would have found it.
from chimera.core.checkpoint import WorkspaceGuard
from chimera.evolution.diff_gate import diff_snapshots

Le coût n'était pas l'exception — une ImportError est bruyante et bon marché. Le coût, c'est que la même supposition confiante portant sur un comportement échoue en silence, et vous ne l'apprenez que lorsque le chiffre qu'elle a produit se révèle faux.

Évitez aussi de vous ancrer sur la mauvaise version. Lire la documentation actuelle d'un paquet figé deux versions majeures en arrière produit du code correct au sujet d'une bibliothèque que vous n'exécutez pas — et le message d'erreur, quand il arrive, désigne votre appel plutôt que le décalage.

Et évitez d'accepter un vérificateur de types au vert comme ancrage quand le paquet ne fournit aucun stub. Face à une dépendance non typée, Any avale tous les attributs que vous inventez ; la vérification annonce un succès parce qu'elle n'avait rien à vérifier.

Vérifier

Pour chaque appel non évident du diff, pouvez-vous montrer où vous l'avez vu — une signature que vous avez affichée, une ligne dans site-packages, un --help que vous avez lancé ? Si la réponse honnête pour l'un d'eux est « ça semblait juste », cet appel n'est pas vérifié, et le dire coûte une phrase.

La vérification la plus forte est exécutable : lancez l'extrait de l'étape 4 sur la version installée et collez sa sortie. Un import qui se résout et un appel qui renvoie la forme attendue sont deux faits différents ; c'est sur le second que vous vous appuyez.

Risque

Appliqué à tout, cela transforme du code de routine en travail de recherche et ralentit le travail sans rien apporter. Dépensez cet effort sur l'appel inconnu, celui qui est sensible à la version, et la forme de retour imbriquée — pas sur les cent lignes autour.

Le risque plus subtil est de s'ancrer trop littéralement. Le code source installé vous montrera volontiers _internal_helper, qui existe, fonctionne aujourd'hui, et n'engage personne. Le source vous dit ce qui est là ; la documentation vous dit ce qui est supporté. Quand les deux divergent, préférez la surface documentée, et si vous allez sciemment au-delà, dites-le dans le commentaire plutôt que de laisser le lecteur suivant supposer que c'était autorisé.

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-ground-it-in-the-source/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.

9a51bb6b117c736dba1de11a166efed09ad200134e153ad553f4701302025398

Lire la fiche dans le dépôt →