Come abbiamo costruito Libretto con agenti AI

Da dove siamo partiti

Per i primi mesi Libretto è cresciuto come cresce un prototipo: in fretta e in avanti. Ad aprile i commit sono stati 662, a giugno 90, d’estate qualche centinaio al mese. Il codice funzionava, il sito si costruiva, l’editor si apriva. Quello che mancava era un modo per sapere se un cambiamento lo stava migliorando o peggiorando.

Il 6 ottobre abbiamo contato. Il controllo dei tipi trovava 636 errori nell’applicazione e 549 nei test: 1.185 in tutto. knip, che cerca file, export e dipendenze che nessuno usa, ne segnalava 483. Nessuno di quei numeri fermava qualcosa. Un agente poteva aggiungere dieci errori di tipo e il suo lavoro arrivava in produzione come gli altri.

I primi limiti

Il primo limite è stato un cricchetto. L’idea è semplice: il conteggio di oggi diventa il massimo consentito. Un cambiamento che lo supera non passa; uno che lo abbassa deve abbassare anche il limite, nello stesso commit. Il numero può solo scendere, e chi lo fa scendere lo fissa per tutti quelli che vengono dopo. Non chiede di sistemare tutto in un giorno: chiede di non peggiorare mai.

Lo stesso giorno sono arrivati i confini tra livelli. Libretto ha quattro parti, l’amministrazione, il codice condiviso, i temi dei siti e il server, e non tutte possono dipendere da tutte: un tema non deve importare l’amministrazione, il server non deve importare né l’una né gli altri. Il 6 ottobre le regole erano una fotografia; il 7 sono diventate errori. Oggi sono 17, e l’elenco delle eccezioni ammesse è vuoto.

Il terzo limite riguarda i dati, non il codice. Una pagina di Libretto è un albero di nodi, e dal 7 ottobre ogni scrittura su quell’albero passa da un’unica funzione di controllo, validateTree. Se un nodo finisce nel posto sbagliato, la scrittura viene rifiutata con il motivo, e l’albero resta com’era. Vale per l’editor e vale per gli agenti, che dal 13 ottobre lavorano sui siti anche attraverso un’interfaccia MCP.

Più agenti, una porta sola

Con i limiti in piedi abbiamo aumentato il ritmo. Il 15 ottobre abbiamo deciso di far girare tre lavori in parallelo, non di più: ognuno nella sua copia del codice, con il suo database, così che due agenti non si pestassero i piedi. Il giorno dopo i commit sono stati 216, e tredici rami sono stati uniti al ramo principale.

Ogni unione abbassava i numeri: il commento del cricchetto in CI tiene il conto, riga per riga. Il 16 ottobre, il giorno delle tredici unioni, gli errori di tipo sono scesi da 491 a 262. Il 20 ottobre erano 234, l’80 per cento in meno rispetto al 6. I problemi segnalati da knip, nello stesso periodo, sono scesi da 483 a 37.

Il grafico qui sotto è il cricchetto di knip. Non ha salite: ogni gradino è un cambiamento che ha tolto qualcosa e ha abbassato il limite con sé.

Gli agenti anche come utenti

Gli agenti non scrivono solo il codice di Libretto: lo usano. Attraverso l’interfaccia MCP un agente legge un sito, cerca le operazioni che gli servono e le manda in lotti. Le stesse regole valgono anche qui, perché un sito costruito da un agente deve reggere quanto uno costruito da una persona.

Un lotto si può prima provare: la prova esegue ogni controllo e poi annulla, e la pubblicazione in prova è sempre rifiutata. Quando un lotto viene applicato, la risposta contiene le revisioni e la chiamata per annullarlo. Pubblicare un sito è un’operazione a parte, che va confermata in modo esplicito, e l’agente la chiede solo quando una persona ha dato il via. Dal 25 ottobre, quando uno strumento non permette qualcosa, l’agente non cerca una scorciatoia: apre un ticket per chi mantiene la piattaforma, con quello che manca.

Cosa si è rotto

I limiti hanno tenuto quasi sempre. Le volte in cui non hanno tenuto ci hanno insegnato più delle altre.

Un conteggio fatto nel posto sbagliato. Il 21 ottobre un agente ha abbassato il limite degli errori di tipo dell’applicazione a 107. Il numero era giusto sulla sua macchina e sbagliato in CI, che ne contava 111: lo aveva misurato subito dopo una build, quando i tipi generati sono diversi da quelli che la CI controlla. Il cambiamento è stato annullato e il limite è tornato dov’era. Nessun errore era stato aggiunto, ma per un momento il limite chiedeva qualcosa che il codice non era.1

Un controllo che scambiava il silenzio per un successo. Il controllo dei tipi conta le righe di errore che il compilatore stampa. Quando il compilatore finisce la memoria e si ferma, non stampa nessuna riga di errore: il conteggio legge zero, e zero è sotto ogni limite. Lo abbiamo visto il 23 ottobre. Da allora un compilatore che si ferma fa fallire il controllo, invece di farlo passare.

Un rilascio che non aspettava. Fino al 25 ottobre un push sul ramo principale faceva partire due cose insieme: i controlli e il rilascio. Il rilascio aspettava solo la build dell’immagine, non i controlli. Quel giorno abbiamo trovato in produzione un commit con una parte dei test end-to-end rossa. Da allora il rilascio parte solo quando la CI è verde.

Una porta che non si poteva chiudere. La soluzione ovvia sarebbe stata proteggere il ramo principale su GitHub. Sul piano gratuito, per un repository privato, GitHub risponde di no. Così il cancello è diventato uno script: prende un lucchetto, perché si unisca un ramo alla volta; unisce il ramo al principale in una copia dedicata, con il suo database; esegue gli stessi quattordici passi della CI, dal più rapido al più lento, fermandosi al primo rosso; e solo alla fine spinge il risultato, senza forzare. Se nel frattempo il ramo principale si è mosso, il push viene rifiutato e il cancello riparte sul nuovo punto.2

I numeri che restano

Il 25 ottobre il cricchetto è arrivato anche alla complessità: le funzioni con una complessità sopra 15 hanno un elenco con il loro nome, che può solo accorciarsi. Erano 149, oggi sono 143. Il 26 ottobre il limite degli errori di tipo dell’applicazione è sceso a 100. Sono numeri ancora alti, e lo diciamo: un cricchetto dice che le cose non peggiorano, non che sono già buone.

Cosa ci ha insegnato

Un limite vale quanto il conteggio su cui poggia. Se il numero si misura in un posto diverso da quello in cui si controlla, prima o poi i due divergono. Ora si conta dove conta la CI, e uno script legge i limiti direttamente dal file della CI, così che non esistano due versioni dello stesso numero.

Un controllo deve saper distinguere il silenzio da un successo. Zero errori e nessuna risposta sono due cose diverse, e un controllo che non le distingue lascia passare proprio il caso peggiore.

I controlli devono girare su quello che verrà davvero pubblicato. Un ramo verde da solo non dice niente su cosa succede quando incontra il lavoro degli altri: per questo il cancello unisce prima e controlla dopo, e il rilascio aspetta.

E la velocità degli agenti è utile solo dentro questi confini. Tre lavori in parallelo, tredici unioni in un giorno, 274 commit il 25 ottobre: niente di tutto questo sarebbe stato sostenibile senza una porta sola, con gli stessi controlli per tutti, e una persona che decide quando qualcosa va pubblicato.

Il metodo che ne è uscito è scritto, in forma generale, nella pagina Il metodo. I numeri di Libretto sono nella pagina del caso.

Note e fonti

1. Il commit che annulla la riduzione a 107 spiega la causa: i tipi generati dopo una build sono diversi da quelli della CI.
2. Il cancello è scripts/merge-gate.mjs; i suoi quattordici passi sono gli stessi comandi della CI, con i limiti letti dal file della CI.
3. Tutti i numeri vengono dal repository di Libretto, letto il 27 ottobre 2026: git log, .github/workflows/ci.yml, scripts/merge-gate.mjs, .dependency-cruiser.cjs e docs/metrics/ccn-over-15.json.

Se qualcosa qui vi è utile e vi serve una mano per farlo vostro, ci trovate a info@innestidigital.it. Se no, va bene lo stesso.