Dans mon précédent article, je vous ai montré pourquoi la vérification est le fondement de tout ce que je fais avec les agents, et comment commencer à créer vos propres compétences de vérification. La leçon clé était que si un agent ne peut pas vérifier son propre travail, rien d'autre n'a d'importance. Vous restez le goulot d'étranglement, et votre journée entière sera consacrée à surveiller vos agents.
https://x.com/poteto/status/2094457600259842065
Mais une fois que la vérification fonctionne, la question suivante est : comment déterminer ce qu'il faut construire ?
https://x.ai/bot/plugin/9717366
Dans cet article, je vais vous expliquer comment je mène la recherche, la planification, le prototypage et l'architecture avec pstack. C'est le flux de travail exact qui me permet de livrer des milliers de PR par mois en production tout en maintenant une qualité de code exceptionnellement élevée.
Fin du mois d'août avec 2 462 PR en production
L'art de superviser quelqu'un de plus intelligent que soi
À l'époque ancienne de 2024, pour apporter un changement dans un système, il fallait d'abord en lire suffisamment pour se construire un modèle mental de son fonctionnement. Selon la taille et la complexité de la base de code, cela pouvait prendre des heures, voire des jours ou des mois. Pour un petit changement, une compréhension locale d'un sous-système pouvait suffire. Mais pour refactoriser le cœur, il fallait probablement avoir un modèle mental de l'ensemble pour le faire correctement et efficacement.
Les agents suppriment évidemment cette barrière. Vous pouvez apporter des modifications aux systèmes très facilement en donnant simplement des instructions à votre agent, et il le fera, quelle que soit votre connaissance du code. Mais maintenir une qualité de code et une expérience utilisateur élevées reste difficile, surtout si vous n'êtes pas déjà un expert du domaine qui sait quoi chercher et demander.
Même si les modèles de pointe sont devenus très performants, j'observe encore deux modes d'échec récurrents :
- Ils sont incapables de comprendre pleinement votre intention car elle est sous-spécifiée ou mal spécifiée.
- Ils n'ont pas assez de contexte pour effectuer le travail correctement.
Ces deux problèmes sont liés. Bien utiliser les agents revient à savoir comment alimenter la fenêtre de contexte de l'agent avec un contexte de haute qualité. Vous pouvez certainement écrire du code qui fonctionne sans le faire, mais je constate que les résultats et la qualité sont bien meilleurs lorsque j'ai fait le travail de fournir à mes agents tout ce dont ils ont besoin pour faire un travail de haute qualité.
Dans vos propres mots
Les modèles de pointe sont des codeurs très compétents. Alors qu'avec les anciens modèles, je pouvais donner des instructions très spécifiques sur ce que je voulais, presque en les micro-gérant, les derniers modèles sont capables d'écrire un code meilleur que vous ou moi. Il y a donc un équilibre subtil à trouver entre dire à l'agent ce que je veux qu'il accomplisse, tout en lui donnant la liberté de le résoudre d'une manière à laquelle je n'aurais pas pensé.
C'est l'art de superviser quelqu'un de plus intelligent que soi, sur une base de code que vous n'avez pas écrite vous-même, et où les humains ne peuvent plus avoir le modèle mental complet de la base de code dans leur tête.
Une technique que j'aime utiliser est l'incitation indirecte. Au lieu de dire exactement à l'agent ce que je veux, j'essaie de le lui faire exprimer plutôt - dans ses propres mots.
Par exemple, lorsque quelqu'un signale un problème dans Slack, je demande souvent à l'agent de lire le fil de discussion et de reformuler le problème dans ses propres mots avant de faire quoi que ce soit d'autre.
Par exemple, je pourrais dire :
/poteto-mode lis ce fil Slack. reformule dans tes propres mots et en langage clair ce que tu penses être le problème sous-jacent
Cela permet trois choses :
Premièrement, cela force l'agent à compresser une conversation bruyante en un énoncé de problème structuré. Deuxièmement, cela me permet de détecter immédiatement les malentendus. Si l'agent se focalise sur une fausse piste dans le fil, je peux le corriger rapidement avant qu'il ne commence à écrire du code.
Et troisièmement, je ne l'ai pas potentiellement conduit sur une mauvaise voie en énonçant mes propres hypothèses et suppositions qui pourraient être incorrectes ou limiter ce que l'agent pourrait autrement accomplir.
Construire un modèle mental
Demander à l'agent de se reformuler d'une manière que vous puissiez comprendre est une partie importante du travail avec quelqu'un de plus intelligent que vous. C'est l'inspiration derrière /teach, une compétence qui aide votre agent à vous expliquer les choses de manière intuitive. Je l'utilise chaque fois que j'ai besoin de m'assurer que mon agent fait quelque chose qui a du sens pour moi.
Sous le capot, /teach fait appel à /how et /why.
/how trace les mécanismes d'exécution. Lorsque vous demandez /how, l'agent évalue la complexité du sous-système. Si le sous-système s'étend sur plusieurs répertoires ou services, il lance des agents explorateurs parallèles sur des modèles rapides et efficaces comme Grok.
/how la virtualisation est-elle implémentée ?
/why enquête sur la motivation et l'intention. Le code vous dit ce qui se passe. Il dit rarement pourquoi quelqu'un l'a écrit de cette façon. Lorsque vous exécutez /why, pstack interroge les preuves historiques à travers plusieurs sources en parallèle : l'historique Git et les commentaires de révision de PR, les tickets Linear, les documents de conception Notion, les conversations Slack, les moniteurs Datadog, les erreurs Sentry, la lignée du code et les événements de l'entrepôt d'analyse.
/why sommes-nous encore bloqués sur une ancienne version de Node.js ?
J'utilise /teach chaque fois que je veux que l'agent reformule quelque chose afin que je puisse mieux comprendre et faire confiance à son travail.
/teach-moi pourquoi tu as implémenté cela de cette façon et pas <autre façon>. quels étaient les compromis que tu as faits et pourquoi ?
En pratique, j'ai également constaté que les recherches effectuées par la compétence /teach ne sont pas seulement utiles aux humains, mais aussi aux agents. Même avec les derniers modèles de pointe (cela dépend aussi de la qualité du harnais), en général, je trouve qu'ils affirment encore souvent les choses avec confiance sans les étayer par des données ou sans lire le code nécessaire pour construire un modèle mental de son fonctionnement. Donc, cet acte de vous enseigner ce qu'il va faire et pourquoi finit par aider l'agent aussi.
Apprendre de l'histoire
Beaucoup de mes projets s'étendent sur plusieurs conversations. Par exemple, il y a quelques mois, je travaillais sur la correction de bugs de virtualisation et de problèmes de performance signalés dans Cursor. J'ai réalisé qu'à chaque fois que je commençais une nouvelle conversation, je devais essentiellement repartir de zéro pour reconstruire le contexte riche que mon agent avait auparavant lorsqu'il résolvait un problème similaire.
Ce que j'ai réalisé, c'est que vos transcriptions passées sont souvent une mine d'or pour un contexte riche. pstack est livré avec la compétence /recall pour extraire votre contexte récent de l'historique des conversations, afin que même les nouveaux agents aient le contexte nécessaire pour revenir à un bon état.
/recall le travail que j'ai fait hier sur la virtualisation, puis lis ce rapport de bug sur Slack
Utiliser /teach, /recall, /how et /why est ainsi que je maintiens mes propres modèles mentaux de la base de code à jour, compressés sous une forme que je peux facilement comprendre et retenir. Et cela aide aussi les agents !
Travailler à rebours
Une fois que vous comprenez le problème, comment spécifiez-vous la solution ?
À mon avis, la plupart des harnais qui ont des modes de planification ont tendance à trop spécifier les détails d'implémentation et à sous-spécifier tout le reste. C'est pourquoi, dans pstack, j'ai dit avec malice que "je ne crois pas à la planification". La vérité est que je planifie, mais je le fais à travers le code.
Pour certains types de travail, comme la création de code ou de packages partagés que d'autres utiliseront, je suis un grand partisan du développement piloté par le README. Si vous n'êtes pas familier avec cela, c'est une technique de développement qui était populaire à l'époque, où vous commencez par rédiger votre README en premier. Cela vous obligeait à mettre votre chapeau d'expérience développeur, en commençant par décrire les API à un utilisateur hypothétique, et en travaillant à rebours jusqu'à l'implémentation et l'architecture.
Par exemple, lorsque je construisais Dune, notre framework client interne pour les applications de bureau, j'ai commencé par écrire un tutoriel pour celui-ci, afin de comprendre ce que serait la construction d'une application avec. Ou du moins, j'ai essayé. C'était une vraie lutte pour que l'agent produise quelque chose de bon ou de lisible. J'ai donc d'abord dû passer du temps à aiguiser mon couteau, en créant la compétence /technical-writing.
La première version du README sans la compétence /technical-writing était pénible à lire car elle mélangeait différents objectifs. Elle essayait d'être un tutoriel, un guide pratique, une explication architecturale et une référence API dans le même document, écrite avec le verbiage IA habituel et une prose maniérée.
/technical-writing utilise le framework Diátaxis pour séparer la documentation en quatre modes distincts :
- Tutoriel : Apprendre en faisant. Une leçon qui guide un nouveau venu à travers une série d'étapes pour construire quelque chose de visible.
- Guide pratique : Étapes pour résoudre un problème spécifique et concret pour un utilisateur expérimenté.
- Référence : Descriptions techniques sèches, complètes et faisant autorité des machines, API et indicateurs de configuration.
- Explication : Discussion de haut niveau qui clarifie et illumine le contexte, les choix de conception et les compromis.
Il utilise également /unslop, ce qui produit une documentation très lisible.
Écrire un plan de cette façon est très utile car cela donne également à vos agents une cible et un objectif concrets contre lesquels ils peuvent vérifier leur propre travail. Et bien sûr, il est aussi beaucoup plus facile de comprendre exactement ce que l'agent va construire.
De nombreuses compétences de pstack se combinent ici dans la phase de conception. Par exemple :
(1) /recall mon travail de correction des bugs de virtualisation et des problèmes de performance des 7 derniers jours. utilise /how et /why pour comprendre comment fonctionne notre implémentation actuelle de la virtualisation.
(2) ensuite, utilise la planification /poteto-mode et /technical-writing pour concevoir un nouveau moteur de virtualisation qui élimine catégoriquement le scintillement et la saccade. commençons par écrire un tutoriel sur la façon dont j'utiliserais ce nouveau package pour virtualiser une application React
(3) après avoir écrit le plan, /teach-moi et prouve-moi pourquoi cette nouvelle approche est supérieure à notre moteur actuel
La technique ici consiste vraiment à extraire un contexte intéressant et riche qui donne à vos agents la capacité de voir le problème de la même manière que vous - pas seulement comme une petite tranche :
- La première partie de l'invite rappelle le contexte passé et présent pertinent sur la façon dont la virtualisation est implémentée dans mon application.
- La deuxième partie guide l'agent pour utiliser ce contexte, comme les bugs qu'il a déjà corrigés, afin de proposer une nouvelle conception qui élimine complètement ces problèmes.
- La dernière partie consiste à demander à votre agent de vous prouver que ce nouveau package est supérieur. C'est là que des outils de haute qualité comme les compétences de vérification sont importants à avoir.
Mesurer cent fois, couper une fois
Lors de la planification, deux des erreurs les plus courantes que je vois sont :
- Accepter la première conception de l'agent.
- Surcuisiner le plan sans preuve empirique.
Quand les humains écrivaient du code, nous collaborions souvent entre nous sur des documents de conception. C'étaient des documents qui parlaient de l'architecture de haut niveau, des alternatives envisagées, des compromis et de toute note d'implémentation inhabituelle. Il était très courant de passer par plusieurs itérations de ces documents avant d'arriver à une conception arrêtée.
Avec les agents, bien que nous puissions sauter la cérémonie du document de conception, je vois souvent l'erreur d'accepter la première chose que l'agent vous renvoie. Avec pstack, nous pouvons plutôt pousser l'approche "mesurer deux fois, couper une fois" à sa limite, en utilisant des agents parallèles.
Nous faisons cela en utilisant le playbook de prototypage.
Dans pstack, les playbooks ne sont pas des compétences, mais des fichiers de référence à l'intérieur de /poteto-mode. Ces playbooks sont chargés conditionnellement (pour l'efficacité des tokens) en fonction du type de tâche sur laquelle vous travaillez. Ces 23 playbooks (à partir de la version 0.15.0) contiennent chacun un flux de travail que j'utilise lorsque j'effectue une tâche.
Contrairement aux compétences, les playbooks sont automatiquement utilisés par l'agent dans le cadre de /poteto-mode. Par exemple :
/poteto-mode prototype quelques options pour le nouveau menu déroulant /poteto-mode corrige ce bug /poteto-mode évalue ce changement de compétence
Le prototypage est l'un de mes playbooks pstack préférés. Il vous donne plusieurs tentatives pour un objectif et aide l'agent à raisonner sur la meilleure option. C'est utile non seulement pour le prototypage visuel, mais aussi pour prototyper différentes solutions pour des fonctionnalités, des corrections de bugs, etc.
/poteto-mode prototype quelques options pour <demande de fonctionnalité>. utilise /control-app* et prends des vidéos/captures d'écran pour que je les examine et choisisse
\ remarque : /control-app est la compétence de vérification que nous avons créée dans [Partie 1*](https://x.com/poteto/status/2094457600259842065
Lors du prototypage de changements visuels, l'agent construit des esquisses jetables dans votre application ou dans un répertoire de brouillon. S'il teste une interaction UI, il place deux ou trois variantes derrière un simple commutateur. Ensuite, il pilote l'interaction avec la compétence /control-app, prend des captures d'écran de chaque variante et mesure le timing ou la disposition réels.
Le prototypage, c'est de la planification, mais avec du code. Il permet aux agents la liberté d'explorer l'espace du problème et de leur donner une chance de vous surprendre avec quelque chose auquel vous n'auriez pas pensé vous-même. Les prototypes permettent aux agents de répondre à leurs propres questions avec des preuves empiriques au lieu d'attendre mon avis.
Architecturer des changements plus importants
En tant qu'ingénieur à l'ère des agents, il est plus important de passer mon temps sur l'architecture, le choix des bonnes structures de données et la réflexion sur la façon dont les systèmes que je construis fonctionneront ensemble. Mes agents remplissent les détails d'implémentation.
Une autre compétence utile fournie avec pstack est /architect. Elle structure la conception en phases distinctes et disciplinées :
- Ancrer le problème. L'agent exécute /how et /why sur les systèmes concernés pour construire un modèle mental précis de la propriété et des contraintes existantes.
- Esquisser. L'agent entre dans une arène d'architecture. Il lance des candidats indépendants en parallèle, souvent sur différentes familles de modèles. Chaque candidat reçoit le briefing d'ancrage et rédige un ensemble de conception complet : l'esquisse d'utilisation de l'appelant, les définitions de types de base, les signatures de fonctions publiques et une justification concise. Cela se fait généralement en esquissant juste les signatures de types, qui dérivent de la façon dont nous voulons que les sites d'appel ressemblent. Chaque candidat doit évaluer la profondeur de l'interface, examiner les modes de défaillance sur les modèles faibles et filtrer par rapport à notre catalogue de signaux d'alarme de conception.
- Évaluation croisée et synthèse. Un agent d'évaluation croisée utilisant un modèle différent de l'agent principal évalue les candidats par rapport à une grille stricte.
- Implémenter à partir de l'esquisse. L'agent remplace les corps d'esquisse par une logique réelle. Si l'agent découvre pendant l'implémentation qu'une fonction a besoin de paramètres inattendus ou d'état supplémentaire, il signale la divergence.
- Jeter quand la conception est erronée. Si, pendant l'implémentation, nous constatons que les esquisses étaient erronées, lagent jette tout et recommence.
Le but ici est de donner à l'agent une mini-boucle autonome où il peut synthétiser plusieurs conceptions concurrentes de différentes familles de modèles en une approche optimale, et veiller à être rigoureux et à ne pas avoir peur de jeter sa conception si elle s'avère erronée sur la base de preuves empiriques. Si la même solution de contournement apparaît sur des sites d'appel non liés, ou si les types nécessitent des échappatoires comme 𝚊𝚗𝚢 ou des casts forcés, c'est une preuve empirique que l'architecture est erronée.
/architect cette nouvelle <demande de fonctionnalité>
La grande leçon ici est qu'il est bien plus efficace de planifier avec du code en utilisant le prototypage /poteto-mode et /architect.
C'est aussi pourquoi je ne prends jamais la peine d'examiner des plans abstraits de manière contradictoire. Les agents commencent à halluciner des risques théoriques et à inventer des cas limites complexes pour se prémunir contre des problèmes qui ne se produiront jamais. Ne surcuisinez pas vos plans quand ils sont encore abstraits : laissez l'agent répondre aux questions ouvertes par lui-même grâce au prototypage et à la vérification de son propre travail.
D'accord, mais je veux vraiment un document de planification
Bien que pstack ne soit pas livré avec une compétence de planification, il est livré avec un playbook de planification multi-phase. Je l'utilise généralement après que l'agent a proposé une conception qui me satisfait, comme un moyen de créer un plan d'exécution tactique.
/poteto-mode transforme cette conception en un plan
Chaque tâche du plan est structurée autour de la preuve et de la vérification. Le playbook indique aux agents que les tests seuls ne sont pas une vérification suffisante. Ce n'est vérifié que lorsque le code a été réellement exécuté et que son fonctionnement a été vérifié.
Chaque plan est vérifié par un script automatisé qui valide sa structure et son formatage. Une fois approuvé, le plan s'exécute élément par élément. Chaque PR est petite, autonome et facile à réviser.
Pour les très grands projets (comme ceux qui pourraient me prendre une semaine entière), je peux parfois décider de valider temporairement les plans dans la base de code afin que d'autres agents soient au courant du travail en cours. Mais je les supprime généralement une fois terminé pour ne pas laisser la base de code dans un état de confusion. Je ne trouve pas utile de conserver les plans en permanence.
Le flux de travail en pratique
Pour voir comment toutes ces pièces s'assemblent, examinons trois exemples concrets de la façon dont j'utilise ces flux de travail.
Exemple 1 : Enquêter sur un bug ambigu
Lorsqu'un problème apparaît en production et que la cause racine n'est pas claire :
/poteto-mode enquête sur la raison pour laquelle les workers en arrière-plan échouent périodiquement avec des erreurs de timeout. donne-moi une ventilation de ce que nous savons, des données que tu as utilisées et de tes meilleures hypothèses.
L'agent explore le code, vérifie les métriques et les commits historiques en parallèle, et vous donne ses meilleures suppositions éclairées sur l'endroit où le problème pourrait se situer.
Exemple 2 : Concevoir une nouvelle frontière de service
Lors de l'introduction d'un nouveau sous-système dont d'autres modules dépendront :
/poteto-mode nous devons ajouter une limitation de débit pour les webhooks externes. /architect ceci d'abord, et réponds à toutes les questions ouvertes avec des prototypes. laisse-moi réviser avant de continuer.
L'agent ancre l'architecture de webhook existante, lance des candidats de conception concurrents sur plusieurs modèles, évalue avec des prototypes jetables et produit une interface propre et vérifiée.
Exemple 3 : Exécuter une migration multi-PR
Lors de l'exécution d'une refactorisation complexe sur de nombreux fichiers :
/poteto-mode crée un plan pour migrer toute notre bibliothèque UI vers StyleX. divise la migration en petites PR vérifiables. chaque PR doit avoir ses tests de régression visuelle et ses étapes de vérification en direct. je veux que le résultat final soit identique à 100% par rapport à l'original - bugs inclus
L'agent divise le travail en étapes indépendantes, rédige une liste de contrôle vérifiable et prépare chaque unité afin qu'elle puisse être construite, vérifiée et déployée en toute sécurité.
Exemple 4 : Corriger les trucs que les gens signalent sur Slack
Si vous m'avez déjà vu sur Slack dans l'un de nos canaux de problèmes ou de commentaires, vous avez probablement vu ces classiques :
# le fil a déjà suffisamment de contexte
/poteto-mode fais-le
/poteto-mode reproduis ceci avec /control-app. si ça se reproduit sur main, corrige-le et montre-moi une vidéo comme preuve
Beaucoup des compétences dont j'ai parlé ici sont déjà automatiquement utilisées par /poteto-mode, donc la grande majorité du temps, vous pouvez simplement utiliser /poteto-mode et passer à autre chose !
L'art de la planification
Le mode Planification est souvent utilisé comme un moyen de se convaincre que l'agent va faire ce qu'il faut. Mais la réalité est que les plans abstraits ne vous donnent que l'illusion du progrès. Un plan long et détaillé donne l'impression que vous et votre agent avez été très productifs, mais il manque probablement de substance.
pstack vous donne des outils pour combiner une enquête approfondie, des preuves empiriques et une vérification rigoureuse. Lorsque vous planifiez de cette façon, l'ingénierie avec des agents cesse de ressembler à un pari. Elle devient prévisible et reproductible.
https://x.ai/bot/plugin/9717366
Merci d'avoir lu, et restez à l'écoute pour la Partie 3 !
