Specification-first convergence with an AI coding agent: a case study of dismantling a core architectural invariant across 189 files in a 717k-line codebase with no test oracle and no human code review

Nel mondo del software, i programmi sono costruiti come vaste e intricate città. Essi consistono in milioni di righe di istruzioni che dicono a un computer come comportarsi, come ricordare le cose e come reagire quando un utente clicca su un pulsante. Per decenni, il modo standard per modificare queste città è stato quello di inviare un architetto umano a ispezionare ogni nuovo mattone che un'intelligenza artificiale potrebbe posare. Questa revisione umana è considerata essenziale perché le connessioni tra le diverse parti di un programma sono così profonde e aggrovigliate che un piccolo errore in un angolo può causare un crollo in un altro. Quando un cambiamento è abbastanza grande da toccare centinaia di file contemporaneamente, il compito di controllare il lavoro diventa un collo di bottiglia; nessun singolo essere umano può contenere l'intera mappa dei cambiamenti nella propria mente contemporaneamente. Questa limitazione ha portato molti a credere che, per i cambiamenti architettonici più complessi, l'unica via sicura sia demolire la vecchia struttura e costruirne una nuova da zero, un processo che è lento, costoso e rischioso.

Un recente caso di studio sfida l'idea che la revisione umana sia l'unico modo per garantire la sicurezza in cambiamenti così massicci. Esplora un metodo in cui l'attenzione si sposta dal controllo del prodotto finito al perfezionamento del progetto prima che venga posato un singolo mattone. Invece di chiedere a un'intelligenza artificiale di scrivere codice e poi sperare che un essere umano trovi gli errori, questo approccio chiede alla macchina di scrivere prima una descrizione dettagliata e formale di ciò che intende fare esattamente. Questa descrizione viene poi rigorosamente controllata rispetto al codice esistente, non per vedere se il codice funziona, ma per vedere se il piano stesso abbia senso. Il piano viene raffinato, corretto e congelato finché non smette di produrre riscontri. Solo allora la macchina inizia a costruire, e anche in quel caso, è costantemente auditata rispetto a quel piano congelato. Il risultato è una dimostrazione che un cambiamento architettonico massiccio e complesso può essere completato senza che un singolo essere umano legga mai il codice generato, a patto che il processo di definizione e verifica dell'intento sia abbastanza robusto.

L'esperimento si è svolto all'interno di un'applicazione software proprietaria di grandi dimensioni utilizzata per l'assistenza alla programmazione tramite intelligenza artificiale. Il sistema, scritto in un linguaggio chiamato TypeScript, conteneva oltre 717.000 righe di codice distribuite in quasi 3.650 file. Era un pezzo di software vivo e pulsante, utilizzato quotidianamente, non un modello teorico. Il compito assegnato all'agente di intelligenza artificiale era quello di smantellare una regola fondamentale che aveva governato il sistema sin dalla sua creazione. Questa regola, nota come invariante, garantiva che ogni volta che un utente avviava una conversazione con l'IA, la finestra che visualizzava tale conversazione rimanesse aperta per tutta la durata della richiesta. Se l'utente chiudeva la finestra, la conversazione moriva. L'obiettivo era rompere questa regola: l'utente doveva poter chiudere la finestra, e la conversazione doveva continuare a girare in background, pronta per essere riaperta e ripresa esattamente da dove era stata interrotta, senza perdere alcun dato o ripetere alcuna parola.

Questo specifico cambiamento era considerato quasi impossibile da realizzare attraverso il refactoring standard. Nella valutazione dell'autore, l'interdipendenza del codice era così stretta che modificare il ciclo di vita di una conversazione senza rompere l'intero sistema avrebbe normalmente richiesto una riscrittura completa dei componenti interessati. Il compito comportava la gestione di complessi problemi di temporizzazione, come cosa accade quando una finestra si chiude mentre i dati stanno ancora arrivando, e come ricollegare un utente a uno stream live che è stato in esecuzione senza di lui. Per risolvere questo, l'autore ha impiegato un protocollo in cinque fasi progettato per mantenere l'intelligenza artificiale su un binario rigido. Il processo è iniziato con l'agente che analizzava la richiesta e produceva una specifica formale, un documento dettagliato che descriveva esattamente come avrebbe dovuto funzionare il cambiamento.

La parte più critica del processo è stata la fase di raffinamento. All'agente è stato chiesto di prendere la propria specifica e controllarla rispetto al codice sorgente reale, cercando eventuali contraddizioni o dettagli mancanti. Questo non è stato un controllo una tantum. L'agente ha eseguito quattordici cicli di questo audit. In ogni ciclo, trovava errori nel proprio piano — forse un file che aveva dimenticato di aggiornare, o una dipendenza che aveva frainteso — e riscriveva la specifica per correggerli. Durante questi quattordici round, il piano è stato corretto circa ottantacinque volte, espandendo l'ambito del cambiamento da 110 file a 160 file man mano che venivano scoperte connessioni nascoste. Alla fine del quattordicesimo ciclo, la specifica era congelata. Era un progetto fisso che era stato auditato rispetto alla realtà del codebase finché l'ultimo ciclo non ha restituito alcun riscontro, punto in cui è stato bloccato come riferimento per tutte le fasi successive.

Con il piano bloccato in posizione, l'agente è passato alla fase di implementazione. Gli è stato ordinato di generare le modifiche al codice necessarie per corrispondere alla specifica congelata. L'agente ha rifiutato di apportare modifiche parziali, identificando correttamente che una migrazione a metà opera avrebbe rotto il sistema. Invece, ha eseguito il lavoro in tre passaggi distinti e confermati. Una volta scritto il codice, è iniziata la fase di verifica. Proprio come il piano era stato controllato rispetto al codice, il nuovo codice veniva ora controllato rispetto alla specifica congelata. L'agente ha eseguito diciassette cicli di questo audit, confrontando il codice effettivo sullo schermo con le regole scritte nella specifica. In ogni ciclo, trovava e correggeva deviazioni, sistemando sottili difetti architettonici che un essere umano avrebbe potuto mancare. Attraverso questi diciassette round, l'agente ha corretto 116 difetti nel codice stesso. Il processo si è interrotto solo quando due audit consecutivi hanno restituito zero errori, confermando che il codice corrispondeva al piano entro il criterio di convergenza definito.

L'intera operazione ha toccato 189 file, con un totale di 288 file modificati includendo l'estrazione del vecchio codice. Le modifiche hanno comportato oltre 34.000 nuove righe di codice e la cancellazione di più di 16.000 righe. Sorprendentemente, questa massiccia ristrutturazione è stata completata in tre giorni. Il costo dell'elaborazione dell'intelligenza artificiale richiesto per il compito è stato di 2.430 dollari statunitensi. Durante l'intero periodo di tre giorni, il programma non è mai stato eseguito una sola volta da un essere umano. La prima volta che il software è stato effettivamente eseguito è stato dopo il diciassettesimo ciclo di verifica, quando l'autore ha finalmente testato il nuovo comportamento.

Il risultato è stato un successo. Quando il programma è stato avviato, il nuovo comportamento funzionava esattamente come descritto nella specifica. Un utente poteva avviare una conversazione, chiudere la finestra e la conversazione continuava a girare in background. Quando l'utente riapriva la finestra, la conversazione riprendeva istantaneamente, senza perdita di dati e senza duplicazione di testo. Un nuovo pulsante di stop è apparso nella barra laterale, permettendo all'utente di interrompere il processo in background se necessario. I test automatizzati esistenti, che venivano eseguiti sul software da anni, non hanno mostrato fallimenti, indicando che il nuovo sistema non aveva rotto nessuna delle vecchie funzionalità. Il software è stato rilasciato al pubblico come versione 2.3.0 e, nelle circa trenta sessioni d'uso che sono seguite al rilascio, non sono stati osservati bug.

Questo caso di studio non sostiene che l'intelligenza artificiale possa ora sostituire gli ingegneri umani in tutti gli scenari, né suggerisce che questo metodo funzioni per ogni tipo di problema. L'autore nota con cura che questo è stato un singolo caso specifico su un singolo codebase, e che i risultati non possono essere automaticamente estesi ad altri sistemi o compiti. Lo studio esclude esplicitamente l'idea che un insieme preesistente di test potesse aver risolto questo problema, perché il comportamento desiderato non esisteva prima del cambiamento. Non c'era una risposta "corretta" da controllare nel vecchio codice; la correttezza doveva essere definita da zero. Lo studio riconosce anche che il processo si è basato su un modello di intelligenza artificiale specifico e potente, e che i risultati potrebbero differire con modelli più deboli.

La significatività del lavoro risiede nella sua dimostrazione di un nuovo modo per gestire la complessità. Spostando l'onere del controllo qualità dall'ispezione del prodotto finale alla definizione e verifica rigorosa del piano, i ricercatori hanno dimostrato che una macchina può navigare in un campo minato di codice interdipendente senza l'intervento umano. La chiave non è stata l'infallibilità della macchina, ma il fatto che il processo ha permesso di catturare i propri errori ripetutamente prima che diventassero permanenti. La specifica è stata sfidata quattordici volte, e il codice è stato controllato diciassette volte, creando un ciclo di autocorrezione che ha guidato il sistema verso un match tra intento e realtà basato su una regola di arresto empirica. I log di questo intero processo, che superano le 1.500 pagine, sono stati pubblicati affinché chiunque possa ispezionarli, offrendo una visione trasparente di come una macchina possa smantellare una regola architettonica fondamentale e ricostruirla, mattone dopo mattone, senza mai aver bisogno che un essere umano le sorvegli le spalle.