Nel mio ultimo post, ti ho mostrato perché la verifica è il fondamento di tutto ciò che faccio con gli agenti e come iniziare a creare le tue skill di verifica. La lezione principale era che se un agente non può verificare il proprio lavoro, nient'altro ha importanza. Rimani tu il collo di bottiglia e passerai l'intera giornata a fare da babysitter ai tuoi agenti.
https://x.com/poteto/status/2094457600259842065
Ma una volta che la verifica funziona, la domanda successiva è: come fai effettivamente a capire cosa costruire?
https://x.ai/bot/plugin/9717366
In questo post, ti guiderò attraverso il mio metodo per fare ricerca, pianificazione, prototipazione e architettura con pstack. Questo è esattamente il flusso di lavoro che mi permette di spedire migliaia di PR al mese in produzione mantenendo una qualità del codice straordinariamente alta.
Concludere il mese di agosto con 2.462 PR in produzione
L'arte di supervisionare qualcuno più intelligente di te
Ai vecchi tempi del 2024, per apportare qualsiasi modifica a un sistema, dovevi prima leggere abbastanza codice per costruire un modello mentale di ciò che stava accadendo. A seconda delle dimensioni e della complessità del codebase, potevano volerci da ore a giorni e persino mesi. Con una modifica piccola, potevi cavartela con una comprensione solo locale di un piccolo sottosistema. Se invece stavi rifattorizzando il core, probabilmente avevi bisogno di un modello mentale di come funzionava l'intero sistema per eseguire il refactoring in modo corretto ed efficace.
Gli agenti ovviamente rimuovono questa barriera. Puoi apportare modifiche ai sistemi molto facilmente semplicemente dando istruzioni al tuo agente e lui lo farà, indipendentemente da quanto tu sappia o meno del codice. Ma mantenere alta la qualità del codice e dell'esperienza utente è ancora difficile, specialmente se non sei già un esperto del dominio che sa cosa cercare e cosa chiedere.
Anche se i modelli all'avanguardia sono diventati molto capaci, ci sono ancora 2 modalità di fallimento che osservo costantemente:
- Non sono in grado di comprendere appieno la tua intenzione perché è specificata in modo insufficiente o poco chiaro.
- Non hanno abbastanza contesto su come eseguire correttamente il lavoro.
Entrambi questi problemi sono correlati. Usare bene gli agenti si riduce a quanto bene sei in grado di preparare la finestra di contesto dell'agente con un contesto di alta qualità. Puoi certamente scrivere codice che funziona senza farlo, ma trovo che i risultati e la qualità siano molto migliori quando ho fatto il lavoro di fornire ai miei agenti tutto ciò di cui hanno bisogno per svolgere un lavoro di alta qualità.
Con le tue parole
I modelli all'avanguardia sono programmatori molto capaci. Mentre con i modelli più vecchi potevo dare istruzioni molto specifiche su cosa volevo che facessero, quasi microgestendoli, gli ultimi modelli sono in grado di scrivere codice meglio di te o di me. Quindi c'è un equilibrio sottile che voglio trovare tra dire all'agente cosa voglio che ottenga, dandogli al contempo la libertà di risolverlo in modi a cui potrei non aver pensato.
Questa è l'arte di supervisionare qualcuno più intelligente di te, su un codebase che non hai scritto tu stesso, e dove gli umani non possono più contenere l'intero modello mentale del codebase nella loro testa.
Una tecnica che mi piace usare è il prompt indiretto. Invece di dire all'agente esattamente cosa voglio, cerco di farglielo tirare fuori invece - con le sue stesse parole.
Ad esempio, quando qualcuno segnala un problema in Slack, spesso chiedo all'agente di leggere il thread e riformulare il problema con le sue parole prima di fare qualsiasi altra cosa.
Ad esempio, potrei dire:
/poteto-mode leggi questo thread di Slack. riformula con le tue parole e in inglese semplice quello che pensi sia il problema sottostante
Questo realizza tre cose:
In primo luogo, costringe l'agente a comprimere una conversazione rumorosa in una dichiarazione del problema strutturata. In secondo luogo, mi permette di cogliere immediatamente i fraintendimenti. Se l'agente si fissa su una pista falsa nel thread, posso correggerlo rapidamente prima che inizi a scrivere codice.
E in terzo luogo, non l'ho potenzialmente portato sulla strada sbagliata esprimendo le mie ipotesi e supposizioni che potrebbero essere errate o limitare ciò che l'agente potrebbe altrimenti ottenere.
Costruire un modello mentale
Chiedere all'agente di riformularsi in un modo che tu possa capire è una parte importante del lavorare con qualcuno che è più intelligente di te. Questa è stata l'ispirazione per /teach, una skill che aiuta il tuo agente a spiegarti le cose in modo intuitivo. La uso ogni volta che devo assicurarmi che il mio agente stia facendo qualcosa che ha senso per me.
Sotto il cofano, /teach chiama /how e /why.
/how traccia la meccanica a runtime. Quando chiedi /how, l'agente valuta la complessità del sottosistema. Se il sottosistema si estende su più directory o servizi, genera agenti esploratori paralleli su modelli veloci ed efficienti come Grok.
/how è implementata la virtualizzazione?
/why indaga motivazione e intenzione. Il codice ti dice cosa succede. Raramente ti dice perché qualcuno l'ha scritto in quel modo. Quando esegui /why, pstack interroga le prove storiche attraverso più fonti in parallelo: cronologia Git e commenti di revisione delle PR, ticket Linear, documenti di design Notion, conversazioni Slack, monitor Datadog, errori Sentry, lignaggio del codice ed eventi del data warehouse analitico.
/why siamo ancora bloccati su una vecchia versione di node.js?
Uso /teach ogni volta che voglio che l'agente riformuli qualcosa in modo che io possa capire meglio e fidarmi del suo lavoro.
/teach mi spieghi perché l'hai implementato in questo modo e non <in altro modo>. quali sono stati i compromessi che hai fatto e perché?
In pratica, ho anche scoperto che la ricerca fatta dalla skill /teach non è utile solo per gli umani, ma anche per gli agenti. Anche con gli ultimi modelli all'avanguardia (questo dipende anche dalla qualità dell'harness), in generale trovo che spesso affermino ancora le cose con sicurezza senza supportarle con dati o leggere effettivamente il codice necessario per costruire un modello mentale di come funziona. Quindi questo atto di insegnarti cosa farà e perché finisce per aiutare anche l'agente.
Imparare dalla storia
Molti dei miei progetti si estendono su più conversazioni. Ad esempio, qualche mese fa stavo lavorando alla correzione di bug di virtualizzazione e problemi di prestazioni che le persone segnalavano in Cursor. Mi sono reso conto che ogni volta che iniziavo una nuova chat, dovevo praticamente ricominciare da capo a costruire il ricco contesto che il mio agente aveva prima quando stava risolvendo un problema simile.
Quello che ho capito è che le tue trascrizioni passate sono spesso una miniera d'oro per un contesto ricco. pstack include la skill /recall per estrarre il tuo contesto recente dalla cronologia delle chat, così anche gli agenti nuovi hanno il contesto giusto di cui hanno bisogno per tornare a un buono stato.
/recall il lavoro che ho fatto ieri sulla virtualizzazione e poi leggi questo bug report su slack
Usare /teach, /recall, /how e /why è come mantengo aggiornati i miei modelli mentali del codebase, compressi in una forma che posso facilmente capire e ricordare. E aiuta anche gli agenti!
Lavorare a ritroso
Una volta compreso il problema, come specifichi la soluzione?
Secondo me, la maggior parte degli harness che hanno modalità di pianificazione tendono a specificare eccessivamente i dettagli di implementazione e a specificare poco tutto il resto. Ecco perché in pstack, ho detto maliziosamente che "non credo nella pianificazione". La verità è che pianifico, ma lo faccio attraverso il codice.
Per certi tipi di lavoro, come la creazione di codice o pacchetti condivisi che altri useranno, sono un grande sostenitore dello sviluppo guidato dal readme. Se non lo conosci, è una tecnica di sviluppo che era popolare ai vecchi tempi, in cui si iniziava creando prima il readme. Questo ti costringeva a indossare il cappello dell'esperienza dello sviluppatore, dove inizi descrivendo le API a un utente ipotetico e lavori a ritroso verso l'implementazione e l'architettura.
Ad esempio, quando stavo costruendo Dune, il nostro framework client interno per app desktop, ho iniziato scrivendo prima un tutorial per esso, in modo da capire come sarebbe stato costruire un'app con esso. O almeno ci ho provato. È stata una vera lotta far sì che l'agente producesse qualcosa di buono o leggibile. Quindi ho dovuto prima passare un po' di tempo ad affilare il mio coltello, creando la skill /technical-writing.
La prima bozza del readme senza la skill /technical-writing era dolorosa da leggere perché mescolava obiettivi diversi. Cercava di essere un tutorial, una guida pratica, una spiegazione architetturale e un riferimento API tutto nello stesso documento, scritto con la solita brodaglia AI e prosa manierata.
/technical-writing utilizza il framework Diátaxis per separare la documentazione in quattro modalità distinte:
- Tutorial: Imparare facendo. Una lezione che guida un nuovo arrivato attraverso una serie di passaggi per costruire qualcosa di visibile.
- Guida pratica: Passaggi per risolvere un problema specifico e reale del mondo per un utente esperto.
- Riferimento: Descrizioni tecniche asciutte, complete e autorevoli di macchinari, API e flag di configurazione.
- Spiegazione: Discussione di alto livello che chiarisce e illumina il background, le scelte progettuali e i compromessi.
Usa anche /unslop, quindi produce una documentazione molto leggibile.
Scrivere un piano in questo modo è molto utile perché dà anche ai tuoi agenti un obiettivo e un traguardo concreto rispetto al quale possono verificare il proprio lavoro. E, naturalmente, è anche molto più facile capire cosa esattamente l'agente costruirà.
Molte delle skill di pstack si combinano qui nella fase di progettazione. Ad esempio:
(1) /recall il mio lavoro sulla correzione di bug di virtualizzazione e problemi di prestazioni degli ultimi 7 giorni. usa /how e /why per capire come funziona la nostra attuale implementazione della virtualizzazione.
(2) poi usa /poteto-mode planning e /technical-writing per ideare un nuovo motore di virtualizzazione che elimini categoricamente lo sfarfallio e il tremolio. Iniziamo scrivendo un tutorial su come userei questo nuovo pacchetto per virtualizzare un'app React
(3) dopo aver scritto il piano, /teach me e dimostrami perché questo nuovo approccio è superiore al nostro motore attuale
La tecnica qui consiste essenzialmente nell'estrarre un contesto interessante e ricco che dia ai tuoi agenti la capacità di vedere il problema come lo vedi tu - non solo come una piccola fetta:
- La prima parte del prompt richiama il contesto passato e presente rilevante su come la virtualizzazione è implementata nella mia app.
- La seconda parte guida l'agente a usare quel contesto, come i bug che ha risolto in precedenza, per ideare un nuovo design che elimini completamente quei problemi.
- L'ultimo pezzo è chiedere al tuo agente di dimostrarti che questo nuovo pacchetto è superiore. È qui che strumenti di alta qualità come le skill di verifica sono importanti da avere.
Misura cento volte, taglia una volta
Quando si pianifica, due degli errori più comuni che vedo sono:
- Accettare il primo progetto dell'agente.
- Cuocere troppo il piano senza prove empiriche.
Quando gli umani scrivevano codice, spesso collaboravamo tra loro tramite documenti di progettazione. Questi erano documenti che parlavano di architettura di alto livello, alternative considerate, compromessi e eventuali note di implementazione insolite. Era molto comune passare attraverso più iterazioni di questi documenti prima di arrivare a un progetto definitivo.
Con gli agenti, sebbene possiamo saltare la cerimonia del documento di progettazione, vedo spesso l'errore di accettare la prima cosa che l'agente ti restituisce. Con pstack, possiamo invece portare l'approccio "misura due volte, taglia una volta" al suo limite, usando agenti paralleli.
Lo facciamo usando il playbook di prototipazione.
In pstack, i playbook non sono skill, ma file di riferimento all'interno di /poteto-mode. Questi playbook vengono caricati condizionalmente (per efficienza dei token) a seconda del tipo di attività su cui stai lavorando. Questi 23 playbook (a partire dalla 0.15.0) contengono ciascuno un flusso di lavoro che uso quando svolgo un'attività.
A differenza delle skill, i playbook vengono utilizzati automaticamente dall'agente come parte di /poteto-mode. Ad esempio:
/poteto-mode prototipa alcune opzioni per il nuovo menu a discesa /poteto-mode correggi questo bug /poteto-mode valuta questa modifica della skill
La prototipazione è uno dei miei playbook preferiti di pstack. Ti dà molti tentativi per un obiettivo e aiuta l'agente a ragionare sull'opzione migliore. Questo è utile non solo per la prototipazione visiva, ma anche per prototipare diverse soluzioni per funzionalità, correzioni di bug e così via.
/poteto-mode prototipa alcune opzioni per <richiesta di funzionalità>. usa /control-app* e fai video/screenshot per me da rivedere e scegliere
\ nota: /control-app è la skill di verifica che abbiamo creato nella [Parte 1*](https://x.com/poteto/status/2094457600259842065
Quando si prototipano modifiche visive, l'agente costruisce bozze usa e getta nella tua app o in una directory di prova. Se sta testando un'interazione dell'interfaccia utente, mette due o tre varianti dietro un semplice interruttore. Quindi guida l'interazione con la skill /control-app, fa screenshot di ogni variante e misura i tempi effettivi o il layout.
La prototipazione è pianificazione, ma con il codice. Permette agli agenti la libertà di esplorare lo spazio del problema e di dare loro la possibilità di sorprenderti con qualcosa a cui non avresti pensato tu stesso. I prototipi permettono agli agenti di rispondere alle proprie domande con prove empiriche invece di aspettare il mio contributo.
Architettare cambiamenti più grandi
Come ingegnere nell'era agentica, è più importante spendere il mio tempo sull'architettura, scegliere le strutture dati giuste e pensare a come i sistemi che costruisco lavoreranno insieme. I miei agenti riempiono i dettagli di implementazione.
Un'altra skill utile fornita con pstack è /architect. Struttura la progettazione in fasi distinte e disciplinate:
- Fondamenta del problema. L'agente esegue /how e /why sui sistemi interessati per costruire un modello mentale accurato della proprietà e dei vincoli esistenti.
- Bozza. L'agente entra in un'arena architetturale. Genera esecutori candidati indipendenti in parallelo, spesso attraverso diverse famiglie di modelli. Ogni esecutore riceve il briefing di base e redige un pacchetto di progettazione completo: lo schizzo d'uso del chiamante, le definizioni dei tipi principali, le firme delle funzioni pubbliche e una motivazione concisa. Questi vengono solitamente realizzati abbozzando solo le firme dei tipi, che derivano da come vogliamo che appaiano i siti di chiamata. Ogni esecutore deve valutare la profondità dell'interfaccia, esaminare le modalità di fallimento sui modelli deboli e verificare rispetto al nostro catalogo di bandiere rosse di progettazione.
- Valutazione incrociata e sintesi. Un agente di valutazione incrociata che utilizza un modello diverso dall'agente principale valuta i candidati rispetto a una rubrica rigorosa.
- Implementazione rispetto alla bozza. L'agente sostituisce i corpi segnaposto della bozza con logica reale. Se l'agente scopre durante l'implementazione che una funzione necessita di parametri imprevisti o stato aggiuntivo, evidenzia la discrepanza.
- Butta via quando il progetto è sbagliato. Se durante l'implementazione scopriamo che le bozze erano sbagliate, l'agente butta via tutto e ricomincia da capo.
Il punto qui è dare all'agente un mini-ciclo autonomo in cui può sintetizzare più progetti concorrenti di diverse famiglie di modelli in un approccio ottimale, e fare attenzione ad essere rigoroso e non aver paura di buttare via il suo progetto se si scopre che l'architettura che ha ideato è sbagliata sulla base di prove empiriche. Se la stessa soluzione alternativa appare in siti di chiamata non correlati, o se i tipi richiedono valvole di sfogo come 𝚊𝚗𝚢 o cast forzati, questa è una prova empirica che l'architettura è sbagliata.
/architect questa nuova <richiesta di funzionalità>
La grande lezione qui è che è molto più efficace pianificare con il codice usando la prototipazione /poteto-mode e /architect.
È anche il motivo per cui non mi preoccupo mai di rivedere i piani astratti in modo avversariale. Gli agenti iniziano ad allucinare rischi teorici e inventare casi limite complessi per proteggersi da problemi che non accadranno mai. Non cuocere troppo i tuoi piani quando sono ancora astratti: lascia che l'agente risponda alle domande aperte da solo attraverso la prototipazione e la verifica del proprio lavoro.
Ok, ma voglio davvero un documento di pianificazione
Anche se pstack non viene fornito con una skill di pianificazione, include un playbook di pianificazione multifase. Di solito lo uso dopo che l'agente ha ideato un progetto di cui sono soddisfatto, come un modo per creare un piano di esecuzione tattico.
/poteto-mode trasforma questo progetto in un piano
Ogni singola attività nel piano è strutturata attorno alla prova e alla verifica. Il playbook dice agli agenti che i test da soli non sono una verifica sufficiente. È verificato solo quando ha effettivamente eseguito il codice e verificato che funzioni.
Ogni piano viene controllato da uno script automatizzato che ne convalida la struttura e la formattazione. Una volta approvato, il piano viene eseguito elemento per elemento. Ogni PR è piccolo, autonomo e facilmente revisionabile.
Per progetti davvero grandi (come uno che potrebbe richiedermi un'intera settimana), a volte posso decidere di impegnare temporaneamente i piani nel codebase in modo che altri agenti siano a conoscenza del lavoro in corso. Ma di solito li cancello quando ho finito per non lasciare il codebase in uno stato di confusione. Non trovo utile tenere i piani in giro permanentemente.
Il flusso di lavoro nella pratica
Per vedere come tutti questi pezzi si incastrano, esaminiamo tre esempi concreti di come richiedo questi flussi di lavoro.
Esempio 1: Ricerca di un bug ambiguo
Quando appare un problema in produzione e la causa principale non è chiara:
/poteto-mode indaga perché i worker in background falliscono periodicamente con errori di timeout. dammi una ripartizione di cosa sappiamo, quali dati hai usato e le tue migliori ipotesi.
L'agente esplora il codice, controlla le metriche e i commit storici in parallelo e ti fornisce le sue migliori ipotesi plausibili su dove potrebbe trovarsi il problema.
Esempio 2: Progettare un nuovo confine di servizio
Quando si introduce un nuovo sottosistema da cui dipenderanno altri moduli:
/poteto-mode dobbiamo aggiungere il rate limiting per i webhook esterni. /architect questo prima e rispondi a qualsiasi domanda aperta con i prototipi. fammi rivedere prima di procedere.
L'agente fonda l'architettura dei webhook esistente, avvia esecutori di progettazione concorrenti su più modelli, esegue benchmark con prototipi usa e getta e produce un'interfaccia pulita e verificata.
Esempio 3: Eseguire una migrazione multi-PR
Quando si esegue un refactoring complesso su molti file:
/poteto-mode crea un piano per migrare l'intera libreria UI a StyleX. suddividi la migrazione in PR piccole e verificabili. ogni PR deve avere i suoi test di regressione visiva e passaggi di verifica dal vivo. voglio che il risultato finale sia identico al 100% rispetto all'originale - bug inclusi
L'agente suddivide il lavoro in passaggi indipendenti, scrive una checklist verificabile e prepara ogni unità in modo che possa essere costruita, verificata e rilasciata in sicurezza.
Esempio 4: Sistemare le cose che le persone segnalano su Slack
Se mi hai mai visto su Slack in uno dei nostri canali di problemi o feedback, probabilmente avrai visto questi classici:
# il thread ha già contesto sufficiente
/poteto-mode fallo
/poteto-mode riproduci questo con /control-app. se si riproduce su main, sistemalo e mostrami un video come prova
Molte delle skill di cui ho parlato qui sono già utilizzate automaticamente da /poteto-mode, quindi la stragrande maggioranza delle volte puoi semplicemente usare /poteto-mode e andare avanti con la tua vita!
L'arte della pianificazione
La modalità di pianificazione viene spesso utilizzata come un modo per convincerti che l'agente farà la cosa giusta. Ma la realtà è che i piani astratti ti danno solo l'illusione del progresso. Un piano lungo e dettagliato fa sembrare che tu e il tuo agente siate stati molto produttivi, ma probabilmente manca di sostanza.
pstack ti fornisce gli strumenti per combinare indagine approfondita, prove empiriche e verifica rigorosa. Quando pianifichi in questo modo, l'ingegneria con gli agenti smette di sembrare un azzardo. Diventa prevedibile e ripetibile.
https://x.ai/bot/plugin/9717366
Grazie per aver letto, e resta sintonizzato per la Parte 3!
