Une bonne story n'est pas une longue

Quand un agent revient avec quelque chose qui rate la cible, la réaction naturelle est d'écrire davantage la prochaine fois : plus de détails, plus de contexte, plus de prose. Mais la longueur est un mauvais indicateur de qualité. Une spec digne d'une RFC ne rend pas un agent plus affûté — passé un certain point, la pure taille joue contre lui, car « les limites de la fenêtre de contexte et le 'budget d'attention' du modèle viennent s'y opposer ». Le meilleur réflexe est de découper les grandes tâches en plus petites plutôt que de tout entasser dans un seul prompt géant. [1]

L'objectif n'a jamais été un ticket plus long. Il s'agit de supprimer l'ambiguïté qui, sinon, ressurgit sous forme de code médiocre et de revue bruyante — comme le formule un éditeur d'outils pour agents. [2] Une story se juge sur un seul critère : l'agent revient-il avec ce que vous vouliez dire ? Tout le reste n'est que décoration.

Si cela compte davantage aujourd'hui, c'est que le lecteur a changé. Une user story a toujours été un déclencheur de conversation — un développeur la lit, va voir la personne qui l'a écrite, pose six questions et comble le reste grâce à ce qu'il sait du code base et de l'équipe. [3] Un agent ne peut aller voir personne. Il lit ce qui est écrit, comble chaque trou avec sa meilleure supposition et construit exactement ce qu'il a deviné. [3]

Et quand la story laisse place à l'interprétation, l'agent interprétera — la faute en revient rarement au modèle, mais au contrat qu'on lui a confié. [4] Le modèle est rarement la variable que vous contrôlez. La story, elle, l'est. [5]

La story la plus solide pour un agent ne commence pas par une liste de tâches mais par une mission claire. Énoncez l'objectif et quelques exigences centrales à haut niveau, et laissez l'agent développer les détails à partir de là — les modèles excellent à développer une directive solide, mais il leur faut une mission claire pour ne pas dériver. [1] Votre rôle dans la story est de transmettre la vision ; le rôle de l'agent est tout le reste.

C'est pourquoi le format classique de user story a perduré : il condense trois éléments d'intention en une phrase — « en tant que [type d'utilisateur], je veux [un objectif], afin de [une raison] ». La troisième proposition, celle que tout le monde omet, est celle qui porte la vision :

« Sans elle, l'agent optimise pour la demande littérale de fonctionnalité. Avec elle, l'agent peut raisonner sur les cas limites. » [6]

Observez ce qui se passe sans elle. « Corriger le bug de connexion » est une instruction complète pour un humain qui était présent quand le bug a été signalé. Pour un agent, c'est une suggestion — il pourrait revenir avec une pull request de 400 lignes touchant le flux de réinitialisation de mot de passe, le middleware de session et un feature flag, alors que le vrai correctif était une faute de frappe dans un message d'erreur. [4] La vision dans cette story — qui est bloqué, ce qui devrait se passer à la place, pourquoi cela compte — est ce qui aurait permis de choisir la bonne implémentation dès le premier essai.

Un lecteur humain comble les trous avec du jugement, de la mémoire et un message Slack peu coûteux. Un agent les comble avec ses valeurs par défaut — et il choisira volontiers trois tentatives quand vous en vouliez cinq, ou verrouillera les comptes d'une manière qui permet à n'importe qui de bloquer tous vos clients. [3] Le savoir-faire consiste à nommer les décisions où une valeur par défaut erronée vous coûterait cher. Un test simple pour chaque décision ouverte : « Serais-je agacé si l'agent devinait ? » Si oui, cela doit figurer dans la story. [7]

Ce qui est hors périmètre compte autant que le périmètre. Une courte liste « à ne pas toucher » — les comportements, fichiers et limites que l'agent doit laisser tranquilles — est souvent la phrase la plus utile de toute la story, car sans elle l'agent traite un nettoyage utile comme une autorisation. [8] Des non-objectifs explicites l'empêchent de corriger des choses que personne n'a demandées. [9] Ou, selon les mots d'un développeur : « Cinq lignes dans le ticket évitent deux heures de revue. » [4]

Une story qui transmet bien cela se lit comme un petit contrat : le problème, le résultat attendu, les critères d'acceptation, les contraintes et ce qui est hors limites. Pas parce qu'un modèle serait magique — mais parce que chaque champ est un trou qui serait sinon comblé par une supposition.

L'habitude la plus rentable est d'écrire d'abord les critères d'acceptation et de les laisser recentrer le reste de la story. [7] Les critères d'acceptation sont un comportement observable — ce qui doit être vrai après le changement — pas une reformulation de la demande. « Le formulaire s'envoie » est un souhait ; « soumettre avec un jeton expiré affiche l'écran de session expirée et n'efface pas le message en cours de rédaction » est une vérification.

Les meilleures vérifications sont celles que l'agent peut exécuter lui-même : la commande à lancer, le test qui doit passer, les cas d'échec à couvrir. Une fois écrites, elles fournissent « des critères d'acceptation qui définissent le terminé à la fois pour l'agent et pour la personne » — « une source de vérité unique à partir de laquelle l'agent construit et contre laquelle le relecteur vérifie ». [10]

Définissez aussi le passage de relais. Demandez à l'agent, dans chaque story, de « résumer les fichiers modifiés, les vérifications exécutées, les échecs rencontrés et tout risque restant » dans sa pull request. [9] Cela coûte une ligne dans la story et rend chaque revue plus rapide.

Une autre astuce pour garder la vision honnête : faites transformer votre intention par l'agent en un premier brouillon de spec, puis corrigez ce brouillon. Si la reformulation de la story par l'agent ne correspond pas à ce que vous vouliez dire, le trou est dans votre story — et il est bien moins coûteux de le trouver avant la pull request. [1]

Les agents n'ont pas besoin d'une prose décrivant votre architecture — ils peuvent lire le code. Ce qu'ils ne peuvent pas déduire, c'est quelles parties de celui-ci cette story touche. Pointez plutôt que de décrire : référencez les fichiers à modifier, les motifs existants à reproduire, les conventions à respecter. [7] Un exemple de cinq lignes dans la story enseigne davantage à l'agent qu'un paragraphe expliquant la règle.

Et gardez le travail à la taille d'une story — quelque chose qui peut être construit et vérifié en une seule après-midi — et découpez tout ce qui est plus gros au niveau de la story, avant l'envoi, pas en cours d'exécution. [7] Des stories plus petites et plus nettes sont aussi ce qui rend possible de faire tourner plusieurs agents en parallèle — voyez notre guide sur les agents de codage en parallèle.

Voici le même ticket Linear, écrit deux fois.

Cette dernière vérification est le test « serais-je agacé si l'agent devinait ? » en action : non précisé, un agent raisonnable pourrait facilement n'afficher le message de verrouillage que pour les comptes réels — et révéler ainsi quels e-mails sont enregistrés.

Tout ce qui figure dans ce guide — la mission, les non-objectifs, les critères d'acceptation, les fichiers à regarder — c'est ce que le rédacteur de stories d'Aerunit rédige pour vous. Vous décrivez le travail ; Aerunit lit vos dépôts et propose des tickets Linear avec périmètre, critères d'acceptation et non-objectifs, en pointant le code concerné. Vous éditez, approuvez, et la story est prête pour un agent.

Aerunit lit chaque dépôt qu'une story touche avant de la rédiger, de sorte que le travail multi-dépôts obtient un plan cohérent : une story parente plus un sous-ticket par dépôt concerné. Et les conventions et instructions réutilisables de votre équipe sont enregistrées une fois comme contexte partagé et compétences, puis injectées dans chaque story et chaque exécution d'agent — vous n'avez donc plus à répéter « reproduire le motif existant » dans chaque ticket, et les agents ne réinventent pas vos motifs.