Perché le Software Factory falliscono: riaccendere la luce

Questa è la seconda parte di Perché le fabbriche di software falliscono

La versione video di questo post è disponibile su YouTube: https://www.youtube.com/watch?v=Ib5GBkD555M

Riacendere le luci

Nella prima parte, ho approfondito perché non ci si può fidare dei modelli per mantenere la qualità del codice nel tempo. Perché nessuna quantità di ingegneria dei harness o tokenmaxxing risolverà il problema dell'addestramento dei modelli e dei benchmark. Perché 'modello come giudice' per la qualità del codice non funziona bene come alcuni vogliono farti credere.

Per ora, il giudice sei tu -- quindi rimettiamo la code review al centro.

Abbracceremo la stessa cosa che abbiamo sempre fatto prima dell'AI, cioè fare un po' di pianificazione in anticipo, per ridurre le probabilità di una revisione lunga e difficile.

Troveremo le leve giuste, e useremo l'AI per aiutarci, in 4 fasi:

• Requisiti di Prodotto
• Architettura di Sistema
• Progettazione del Programma
• Sezioni Verticali

Revisione del Prodotto

Tutto inizia con una revisione del prodotto: un breve documento che definisce cosa stiamo costruendo e perché. L'obiettivo è essere in grado di prendere due frasi o un lungo messaggio vocale e trasformarlo in qualcosa di semi-strutturato.

Prima, ci allineiamo sul problema da risolvere -- il reale dolore dell'utente, nei termini dell'utente. Secondo, come si presenta il successo -- cosa possiamo leggere dopo il rilascio per decidere che valeva la pena costruirlo. Idealmente è un risultato per l'utente come "può fare il workflow XYZ in meno tempo" o "raggiunge la milestone di onboarding ABC prima". A volte è di livello più basso come un tasso di errore o un numero di latenza, a volte solo "le richieste di supporto su X smettono".

Cerchiamo di mantenerlo abbastanza ancorato allo spazio del prodotto, non a quello tecnico. Come qualcuno che vive con un piede nel mondo del prodotto e uno nella tecnologia, spesso mi ritrovo a deragliare verso i dettagli tecnici qui. Quando succede, cerco di annotarli per le fasi successive e tornare a ciò che l'utente sperimenta effettivamente. Se le decisioni tecniche bloccano quelle di prodotto, allora impegniamo ciò che abbiamo ed entriamo nell'architettura o facciamo più ricerca prototipale su ciò che è fattibile

E poiché la maggior parte riguarda ciò che l'utente vede, non lo descrivo -- lo prototipo. Un prototipo HTML grezzo dello schermo reale risolve una discussione che tre paragrafi avrebbero solo prolungato.

Ecco uno reale in corso -- il documento definisce la funzionalità con uno schema JSON, poi due prototipi HTML grezzi degli schermi reali:

https://x.com/dexhorthy/status/2078592010852982977

Naturalmente, non tutto riceve una revisione del prodotto. Un piccolo aggiustamento di copia, uno script una tantum, un bug con una riproduzione ovvia -- li inviamo ancora direttamente all'agente in un colpo solo. Questo è per i cambiamenti in cui un fraintendimento dell'agente delle nostre intenzioni è costoso.

Per questo e per tutti i documenti della serie, facciamo revisioni con opt-in dell'autore. Se vuoi risparmiare tempo durante la revisione, scegli la persona che revisionerebbe la PR e esamina con lei le specifiche prodotto/tecnologia, in modo asincrono tramite commenti sul documento (usiamo humanlayer per questo, ma puoi farlo altrettanto facilmente in github/notion/plannotator/etc).

Architettura di Sistema

Una volta risolta la revisione del prodotto, facciamo l'architettura di sistema. Non è particolarmente nuovo ed è qualcosa che anche i vibe coder iniziano a giurare.

Se vuoi risparmiare tempo durante la revisione, scegli la persona che revisionerebbe la PR e esamina con lei le specifiche prodotto/tecnologia prima di arrivare alla parte di codifica.

In questa fase ci allineiamo su come servizi, endpoint, schemi, code e archivi comunicano tra loro, senza entrare nei dettagli della progettazione del programma. Per massimizzare la larghezza di banda della comunicazione umano-agente, utilizziamo pesantemente visualizzazioni qui - ad esempio diagrammi di sequenza:

Forme dei contratti / endpoint:

Modelli di dati e trasformazioni:

Mermaid va bene qui ma a volte può essere eccessivo e a volte indurti in un falso senso di allineamento. L'architettura è una leva piuttosto alta e ci sono molti potenziali tic negativi del modello che puoi prevenire durante questa fase. Ma è insufficiente per produrre codice di alta qualità. Per questo abbiamo bisogno della progettazione del programma.

Progettazione del Programma

Dopo l'architettura facciamo questa cosa che penso sia criminalmente sottovalutata nel coding agentico: progettazione del programma.

La maggior parte delle persone presume che una volta che l'architettura è giusta, il modello possa semplicemente cucinare. Puoi andare avanti e farlo, ma potresti non apprezzare ciò che ottieni.

Ma ciò che vedo funzionare bene è che prima che qualcuno (umano o agente) scriva l'implementazione, scendiamo di un livello dall'architettura nella forma del codice: i tipi, le firme dei metodi, la disposizione del programma e gli stack di chiamate.

La prima versione della nostra abilità di progettazione del programma faceva schifo. Era difficile da leggere, era estenuante. Abbiamo provato Mermaid, che ha il suo posto, ma ciò che amiamo davvero sono visualizzazioni leggere in pseudocodice:

Alberi di stack di chiamate, per qualsiasi cambiamento di orchestrazione o flusso di controllo. Usa la sintassi diff quando la parte interessante è ciò che cambia:

Dillon Mulroy parla di usare grafi di chiamate come parte del suo processo di pianificazione, e penso che sia esattamente giusto.

Diff di alberi di file - per rimanere in contatto con la disposizione del tuo codebase e dove si trovano le cose

Tipi e firme di metodi per le nuove funzioni chiave -- le cose troppo interne per un documento di architettura ma che un agente potrebbe comunque sbagliare

Nessuna di queste richiede molto tempo per essere prodotta (il modello le abbozza, tu discuti con esso), e ognuna di esse è una decisione che altrimenti prenderesti implicitamente durante la code review -- nel momento più costoso possibile per cambiare idea.

Sezioni verticali

Poi adoriamo fare ciò che chiamo 'sezioni verticali' - io e Matt Pocock abbiamo parlato di sezioni verticali o 'tracer bullets' in una live stream nel gennaio 2026 - questo è anche chiamato - tracer bullets

I modelli amano ciò che chiamo 'piani orizzontali' - fare le cose in ordine di stack:

1. Migrazioni del Database
2. Livello Servizi
3. API
4. Frontend

In pratica, ciò significa che non c'è un vero modo per 'toccare' la soluzione mentre procedi. Puoi testare le cose con il codice, ma per quasi tutte le funzionalità che ho mai costruito, leggere i test era un inizio, ma tirare su qualcosa in un browser o colpirlo con curl mentre lavoravo era sempre una parte frequente del flusso di lavoro.

Prima dell'AI, era raro che qualcuno scrivesse più di 2000 righe di codice o anche 500 righe senza controllare qualcosa lungo il percorso.

Mi ci è voluto un po' per notare la differenza rispetto a ciò a cui ero abituato - quando scrivevo codice prima dell'AI, iniziavo sempre dal centro e lavoravo verso l'esterno. In modo approssimativo:

1. Creare il contratto API e servire dati mock, testare con curl
2. Creare il frontend per consumare dati mock, iterare+rifinire nel browser
3. Collegare l'API al livello dei servizi (i servizi servono dati/comportamento mock)
4. Aggiungere migrazioni del database, collegare i servizi al database
5. Aggiungere un sacco di logica di business
6. Aggiungere un sacco di gestione degli errori

E testavo/iteravo/rifinivo in ogni passo.

Se tengo molto al codice o sono scettico sulla capacità del modello di fare un buon lavoro in questa parte del codebase, rivedo il codice anche in ogni passo. Controllare 100-200 righe e reindirizzare è molto più economico

qui, lo farei.

La maggior parte dei modelli all'avanguardia non progetterà un piano del genere senza guida umana, ed è difficile generalizzare per codebase o anche per compito, quindi preferisco rimanere nel giro qui. Fidati. Se potessi esternalizzare il pensiero

30 minuti di pianificazione risparmiano ore di revisione

E quindi abbiamo alcuni passaggi in cui sostengo che gli umani debbano essere nel giro, se vuoi mantenere un livello di qualità vicino a quello umano senza schiavizzare su montagne di codice spazzatura cercando di pulirlo dopo i fatti. (cioè vuoi davvero andare veloce)

1. Progettazione del Prodotto
2. Architettura di Sistema
3. Progettazione del Programma
4. Sezioni Verticali

Ovviamente non facciamo tutto questo processo per ogni cosa che rilasciamo (vedi la sidequest qui sotto). Immagino che la distribuzione sia approssimativamente:

• Circa il 40% dei compiti viene risolto in un colpo solo o con 1-2 round di feedback leggero
• per compiti medi, facciamo progettazione prodotto/sistema tutto in un unico documento di piano, e non ci preoccupiamo di suddividere il lavoro in fasi
• per cose grandi, facciamo tutti i passaggi. salteremo la parte prodotto per cose dove non ha senso, come grandi refactoring.

E nella maggior parte dei casi, invierò un modello a fare 1-3 sezioni alla volta, e rivedrò il codice man mano. È molto più facile reindirizzare all'inizio, che si tratti degli interni o della funzionalità effettiva, che finire dall'altra parte di 2000+ righe di codice senza idea di cosa è rotto.

Probabilmente senti di avere troppe pull request

Non hai troppe PR. Hai troppe PR brutte.

Abbiamo tutti revisionato molte PR che necessitavano di rilavorazione, fin da molto prima dell'AI.

Ma una grande PR è una gioia da revisionare. Scorri ogni file, il codice è pulito, segue tutte le tue decisioni/discussioni/opinioni duramente conquistate su come dovrebbe essere il software.

D'altra parte, se una Pull Request necessita anche solo del 20% di rilavorazione (ed è generoso, direi che la maggior parte delle PR one-shot dell'AI tendono al 50%), è sia un onere intellettuale che un onere emotivo sia per il mittente che per il revisore. (Anche se il mittente è un'AI, qualcuno probabilmente ha avviato questo lavoro o ha rifinito il risultato dell'AI o, perlomeno, tiene al risultato).

Per risparmiarti tempo (siamo quasi alla fine), ho divagato di più su questo in una side quest:

"dove va il tempo"

una teoria dei vincoli (edizione 2026)

È facile essere un po' giù per la tesi centrale qui: 'per ora siamo bloccati a leggere il codice'.

Ero piuttosto entusiasta per un mondo in cui potevamo semplicemente chiedere cose e lasciare che i modelli cucinassero e non leggere il codice e ottenere bellissimo software di produzione che si evolve nel tempo e non va a puttane.

Ma ciò che ho fatto del mio meglio per esporre qui non sono altro che vincoli. I modelli sono bravi in alcune cose, non così bravi in altre. Come ottimizzi il tuo processo alla luce di questi vincoli?

I modelli sono bravi in alcune cose, non così bravi in altre. Come ottimizzi il tuo processo alla luce di questi vincoli?

È possibile che tu sia troppo impegnato a cercare di muoverti 10-100 volte più velocemente e a convincerti che la qualità del codice non conta più, quando potresti abbracciare i vincoli e muoverti 2-3 volte più velocemente, in sicurezza.

Il mio consiglio conclusivo qui è fondamentalmente:

1. Impara bene i vincoli, sviluppa intuizione lavorando molto con i modelli
2. Ottimizza i sistemi nell'arena di questi vincoli
3. Cerca le leve
4. Leggi il dannato codice

Questo è tutto. Se vuoi restare per il pitch, continua a scorrere immagino. Spero che questo ti aiuti a evitare il disastro o almeno che ti sia divertito a guardare qualche animazione carina.

Grazie per aver letto

-dex

PS Siamo ossessionati da questo

Stiamo costruendo humanlayer.com, un IDE agentico e piattaforma di collaborazione per aiutarti a muoverti 2-3 volte più velocemente mantenendo un livello di qualità del codice umano (o dannatamente vicino all'umano).

Stiamo costruendo verso due idee: 'blocchi di costruzione per la tua fabbrica di software' e 'migliori verificatori per la manutenibilità del software' (forse anche modelli migliori).

HumanLayer è gratuito per piccoli team fino a 3 persone, e se vuoi aiuto per iniziare, puoi venire a trovarci nel nostro discord o scriverci a founders@humanlayer.dev

Un ringraziamento veloce a @calvinfo per l'ispirazione, al mio cofondatore @0xBlacklight, a @swyx e al team di @aiDotEngineer per avermi dato un'arena per esplorare queste idee, e a tutti i nostri incredibili clienti, investitori, amici e familiari che ci incoraggiano.

Se vuoi saperne di più, praticamente non la smetto di parlare di questo, quindi puoi trovare tutti i link di questo post così come alcune altre proiezioni del materiale in podcast, lavagna lunga, ecc, qui sotto.

PPS Altre risorse

Podcast e Articoli:

• Dex e Gergely parlano di context engineering e fabbriche di software su The Pragmatic Engineer - Luglio 2026
• Dex e Matt Pocock parlano di consigli di coding AI evergreen (e ralph loops) - Gennaio 2026

Episodi di AI That Works:

• Benchmarks non provano nulla
• Specifiche di Prodotto per il Coding AI
• Learning Tests per un migliore backpressure
• Applicare i principi dei 12-fattori agenti al coding AI

Link da questo post:

• Keynote: Perché le fabbriche di software falliscono — AI Engineer World's Fair 2026
• La fabbrica di software a luci spente di StrongDM
• OpenAI: Harness Engineering (Feb 2026)
• Ryan Lopopolo su Symphony (talk, Apr 2026)
• Mario a AI Engineer Europe: 'Costruire pi greco in un mondo di schifezze'
• FT: Interruzioni di Amazon da incidenti di coding agent
• Matt Pocock: codebase che cadono a pezzi
• Faros AI: il rapporto sull'accelerazione dell'AI whiplash
• Advanced Context Engineering for Coding Agents (talk 8/25)
• No Vibes Allowed (talk 11/25)
• Everything We Got Wrong About RPI (talk 3/26)
• Awesome-RLVR - Risorse di Reinforcement Learning
• Advanced Context Engineering for Coding Agents (scritto)
• 12-Factor Agents
• Addy Osmani su vibe-coding vs. manutenzione
• Conferenza di Ingegneria del Software NATO, 1968
• DoD DevSecOps Reference Design (PDF)
• La piattaforma di coding agent di Ramp
• Stripe: Minions, coding agent end-to-end one-shot
• WorkOS: Project Horizon
• Brex (Latent Space)
• Dan Shapiro: i cinque livelli verso la fabbrica di software
• Simon Willison sulla fabbrica di software di StrongDM
• 'Bollire l'oceano'
• Shotgun surgery (refactoring.guru)
• John Ousterhout — A Philosophy of Software Design
• Robert C. Martin — Clean Code
• Martin Fowler — Refactoring
• aider
• cline
• codebuff
• SWE-Agent paper (2024)
• OpenAI Codex talk (Nov)
• Calvin French-Owen — AI Council talk
• SWE-bench Multilingual (dataset)
• AIE Worlds Fair 2026 - The Great Loops Debate ('l'hype sta superando la disciplina')
• SWE-Marathon (Abundant AI)
• DeepSWE (Datacurve)
• Frontier Code (Cognition)
• Mutation testing (Wikipedia)
• Dillon Mulroy sui grafi di chiamate nella pianificazione
• Dex × Matt Pocock: sezioni verticali / tracer bullets (livestream, Gen 2026)
• 'Il duro lavoro del pensiero non può essere esternalizzato' (Jake Nations)