Vai al contenuto

Cosa ho imparato

Ho costruito software con un agente di IA. Ecco cosa ho imparato.

Lavoro con l’IA dal 2022, e con gli agenti da quando hanno iniziato a comparire a metà del 2025. Con loro ho costruito progetti reali: un backend, un’app mobile, un sito web e questa pagina. All’inizio l’agente scriveva in fretta e io revisionavo lentamente. Col tempo ho capito che la qualità non dipendeva dallo scrivere istruzioni migliori, ma dal costruire un ambiente in cui il codice sbagliato non potesse passare.

Questa pagina raccoglie quelle lezioni. Non vende nulla: racconta cosa è andato storto, cosa ho cambiato e perché funziona, in un modo che vale per qualsiasi linguaggio o stack.

L’idea in una frase

Lascia scrivere l’IA, e fai in modo che il progetto dica di no quando qualcosa non va.

Un’architettura rigorosa, con test e linter che falliscono quando si rompe, trasforma la velocità dell’agente in codice che puoi mantenere.

Lezione 1

Un agente dimentica il tuo design da una sessione all’altra.

Ho scritto le regole del progetto in un documento: quale livello può importare quale, dove va ogni cosa, cosa non va toccato. L’agente le leggeva e le seguiva quasi tutte. Ma ogni sessione riparte da zero, e quel «quasi tutte» si accumula.

La deriva non è mai stata grande. Un import che superava un confine, logica di business dentro un controller, un test mancante. Ogni modifica sembrava ragionevole presa da sola, e me ne accorgevo settimane dopo, quando c’era già del codice costruito sopra.

Ho smesso di fidarmi del fatto che l’agente ricordasse le regole e le ho trasformate in controlli che vengono eseguiti da soli. Se una modifica supera un confine, la build o un test fallisce, con il nome della regola nel messaggio di errore.

Distanza dal designRegole in un documentoIl design12345SessioneRegole che vengono eseguiteIl designRespinta da un controllo12345Sessione
Con le regole in un documento, le piccole deviazioni si accumulano. Con le regole che vengono eseguite, ognuna si ferma nella modifica che la causa.

Un agente legge gli errori con molta attenzione. Un errore con un nome gli dice esattamente quale regola ha violato, e corregge la modifica prima ancora che io la veda. La regola non dipende più dal fatto che qualcuno se la ricordi, né l’agente né io.

Regole in un documento

  • L’agente le legge all’inizio e le segue la maggior parte delle volte.
  • La deriva emerge settimane dopo, in revisione.
  • Revisionare significa cercare errori a occhio.

Regole che vengono eseguite

  • Vengono controllate a ogni modifica, senza eccezioni.
  • La modifica viene respinta subito, con il nome della regola.
  • Revisionare significa decidere su un lavoro che ha già superato i controlli.

Lezione 2

L’agente lavora sempre nello stesso ordine.

Senza un ordine fisso, l’agente faceva ciò che in ogni momento sembrava più utile. A volte modificava file quando avevo solo fatto una domanda. A volte iniziava a scrivere senza leggere come era costruito il resto, o dava qualcosa per finito senza averlo testato.

Per questo uso Organic Driven Development: un flusso di lavoro in sette passi che l’agente segue a ogni richiesta, piccola o grande. Il processo cresce con la dimensione del compito, invece di applicare la stessa formalità a tutto.

  1. Autorizzare
  2. Esplorare
  3. Chiarire i dubbi
  4. Classificare
  • Piccolo: dritto al codice

    1. Implementare
  • Grande: prima tracciato

    1. Tracciare
    2. Implementare

Chiudere

Ogni richiesta passa dallo stesso tronco. Classificare decide se il lavoro va dritto al codice o viene prima tracciato.
  1. Autorizzare

    Prima verifica se ho davvero chiesto una modifica. Una domanda, una revisione o un piano non toccano nessun file.

    Senza questo passoModifiche a sorpresa quando volevo solo una risposta.

  2. Esplorare

    Legge il codice esistente e le regole del progetto prima di proporre qualsiasi cosa.

    Senza questo passoSoluzioni che funzionano ma non si adattano a ciò che c’è già.

  3. Chiarire i dubbi

    Se una decisione spetta a me (prodotto, ambito, design), fa una sola domanda concreta e aspetta. Se è tecnica, decide e va avanti.

    Senza questo passoO una valanga di domande meccaniche, o decisioni prese al posto mio che non spettano a lui.

  4. Classificare

    Un compito è piccolo se è compreso, il suo rischio è circoscritto e si potrebbe riprendere dal solo diff. Altrimenti è grande.

    Senza questo passoO tutto riceve formalità, o niente.

  5. Tracciare

    I compiti grandi ricevono un documento che cita la mia richiesta parola per parola, un elenco di attività e un registro delle decisioni.

    Senza questo passoIl lavoro si perde quando una sessione si interrompe, e il risultato si allontana da ciò che ho chiesto senza che nessuno se ne accorga.

  6. Implementare

    Prima un test che fallisce, poi il codice che lo fa passare. I commit vanno per unità di lavoro, di circa 400 righe al massimo.

    Senza questo passoModifiche enormi, senza prova che funzionino, impossibili da revisionare in una sola volta.

  7. Chiudere

    Riporta cosa è passato, cosa è fallito e cosa non ha potuto verificare.

    Senza questo passo«Fatto» senza prove, e io che scopro il problema più tardi.

L’ordine trasforma il buon senso in abitudine. Non dipende dal fatto che l’agente «si ricordi» di essere prudente: ogni passo ha un risultato concreto che posso verificare. E poiché il processo si adatta al compito, una correzione di una riga resta veloce.

Lezione 3

L’agente apre la pull request. Io decido quando è pronta.

Quando l’agente può percorrere da solo l’intero ciclo, scrivere, testare e fare merge, la revisione diventa una formalità. Le modifiche arrivavano al branch principale perché i controlli passavano, non perché qualcuno avesse deciso che erano giuste.

Ho separato «è fatto» da «è pronto». L’agente lavora su un branch e apre la pull request, ma l’integrazione continua parte solo quando aggiungo un’etichetta a mano. Il merge richiede che quell’esecuzione passi, e all’agente non è permesso aggiungere l’etichetta.

  1. L’agente scrive e testa in locale
  2. Apre la pull request
  3. Una persona aggiunge l’etichetta
  4. Parte l’integrazione continua
  5. Verde: si può fare merge. Rosso: l’etichetta viene tolta e si torna all’agente

Ogni merge passa da una decisione umana esplicita, e quella decisione costa poco: arrivo alla revisione con test, lint e architettura già verificati in locale. Il mio lavoro smette di essere la caccia agli errori e diventa giudicare se la modifica è quella giusta.

Lezione 4

Se non vedi cosa sta facendo l’agente, non sai quando intervenire.

Con diverse sessioni aperte contemporaneamente, perdevo il filo. Una aspettava la mia risposta da dieci minuti, un’altra aveva esaurito il contesto e aveva iniziato a fare errori banali, e un’altra aveva finito senza che me ne accorgessi. Per saperlo, dovevo leggere ogni conversazione.

Ho aggiunto all’ambiente dell’agente delle mod che ne mostrano lo stato a colpo d’occhio. Non cambiano ciò che fa l’agente; mi danno visibilità su di esso.

  • landingScrive i test per la nuova sezioneAl lavoro
  • webChiede prima di eseguire una migrazioneHa bisogno di te
  • mobileTutti i controlli passati, branch prontoFatto

ProssimoRivedi il piano web, poi esegui i controlli prima del commit.

  • Stato di ogni sessione

    Al lavoro, ha bisogno di te, fatto o errore. Intervengo solo dove servo.

  • Piano e attività

    L’elenco delle attività dell’agente e dei subagenti che avvia. Posso seguire un lavoro lungo senza leggere ogni messaggio.

  • Contesto rimasto

    Una barra per sessione. Quando si esaurisce, avvio una nuova sessione prima che la qualità cali.

  • Consigli e prossimo passo

    Dopo ogni turno, una breve nota su ciò che ha appena fatto e un suggerimento su cosa fare dopo.

Lavorare con un agente significa, prima di tutto, decidere quando intervenire. Prima vedo una sessione che si blocca o devia, meno lavoro c’è da disfare. La visibilità trasforma la supervisione in qualcosa che sta in un’occhiata.

Lezione 5

Livelli chiari dicono all’agente dove va ogni pezzo.

Quando il progetto non aveva una struttura esplicita, l’agente metteva il codice dove gli era più comodo. La logica di business finiva mescolata con l’accesso ai dati e con l’interfaccia. Ogni modifica toccava molti file, e nessuno, né l’agente né io, poteva dire con certezza cosa avrebbe rotto.

Ho costruito repository di base con un’architettura rigorosa già definita: backend, mobile, web e landing. I nomi dei livelli cambiano con il progetto, ma l’idea è sempre la stessa. Le dipendenze puntano sempre verso il dominio, mai al contrario, e ogni modulo o feature resta isolato: una feature non importa direttamente un’altra.

IngressoInfrastrutturaApplicazioneDominioLe dipendenze puntano verso l’interno
Ingresso e infrastruttura stanno all’esterno; ogni dipendenza punta verso l’interno, verso il dominio.
  1. Ingresso

    Ciò che riceve il mondo esterno: una schermata, una rotta HTTP, un comando. Traduce e delega; non decide.

  2. Applicazione

    I casi d’uso. Coordina il lavoro, ma le regole non vivono qui.

  3. Dominio

    Le regole di business. Non sa nulla di database, framework o rete.

  4. Infrastruttura

    Database, servizi esterni, file. Implementa ciò di cui il dominio ha bisogno.

Ogni freccia punta verso il dominio. L’infrastruttura dipende dal dominio, non il contrario.

Vietato: il dominio importa l’infrastruttura

Per l’agente, l’architettura è una mappa: per ogni modifica sa in quale livello va e cosa può importare. Per me, ogni modifica resta circoscritta ed è più facile da revisionare. E poiché la regola è semplice («le frecce puntano verso l’interno»), uno strumento può verificarla a ogni build.

Lezione 6

Una regola conta solo se violarla rompe la build.

Avevo regole in tre posti diversi: alcune solo scritte, altre controllate sulla mia macchina, altre solo nell’integrazione continua. Quelle solo scritte erano proprio quelle che l’agente finiva per violare.

Ora ogni regola sale una scala di tre gradini, e ogni progetto controlla le stesse cinque cose, anche se lo strumento esatto cambia con il linguaggio.

  1. Scritta

    È nelle istruzioni del progetto, dove l’agente la legge per prima. Spiega il perché, non solo il cosa.

  2. Collegata

    Un linter, un test o un hook la controlla su ogni macchina, prima di ogni commit o push.

  3. Imposta

    L’integrazione continua rifiuta il merge se si rompe, chiunque sia l’autore, persona o agente.

PassatoTipiCodice che compila «per caso» o che usa dati con la forma sbagliata.
FallitoArchitetturaImport che attraversano i livelli, o cicli tra moduli.
PassatoLint rigorosoSchemi pericolosi, come inserire dati come HTML invece che come testo.
PassatoCopertura minimaNuovo comportamento senza un test che lo dimostri.
PassatoSegretiChiavi o password sul punto di essere inviate al repository.
Un controllo fallisce. L’agente legge il nome della regola, sposta l’import ed esegue di nuovo tutto.

La riga rossa è quella utile. Ferma la modifica, dà il nome alla regola, e l’agente sa cosa correggere. Un progetto in cui è tutto verde perché non si controlla niente non protegge niente.

Lezione 7

Quattro pratiche che rendono l’architettura difficile da rompere per sbaglio.

Avere regole che falliscono è l’inizio. Queste quattro pratiche sono quelle che mi hanno aiutato di più a far sì che quelle regole continuino a proteggere nel tempo, chiunque scriva il codice.

  • Vieta tutto per default, e testa il divieto.

    All’inizio le mie regole dei livelli elencavano ciò che era vietato, quindi qualsiasi cosa mancasse dall’elenco era permessa senza che nessuno lo avesse deciso. Ora la regola vieta ogni import che non sia esplicitamente permesso, e un piccolo progetto di test dimostra che ogni import vietato fallisce davvero. Se qualcuno indebolisce la regola, quel test diventa rosso.

    Risultato Una regola che non si può indebolire in silenzio.

  • Scrivi le regole di architettura come test.

    «Il dominio non importa nulla dall’esterno» può essere una frase in un documento o un test che gira con il resto della suite. Il secondo gira su ogni macchina e nell’integrazione continua, e il suo messaggio di errore spiega la regola meglio di qualsiasi documento.

    Risultato La regola gira ovunque girino i test.

  • Due strumenti che si sovrappongono di proposito.

    Uno controlla livello contro livello. L’altro guarda l’intero grafo delle dipendenze: cicli, moduli orfani, un dominio che importa qualcosa che non dovrebbe. Ognuno coglie ciò che all’altro sfugge, e se uno è configurato male, l’altro c’è ancora.

    Risultato Uno strumento rotto non apre una falla.

  • Documenta quale controllo intercetta ogni regola.

    Tengo una tabella «intercettata da» che associa ogni regola di architettura allo strumento che la impone. Una regola senza controllo risalta subito come la prossima da collegare.

    Risultato La prossima regola da collegare è sempre visibile.

Regole deilivelliFeature cheimportafeatureSchermatache legge ildatabaseGrafo delledipendenzeCicli diimportModuliorfaniIl dominioimportainfrastruttura
Ogni strumento coglie qualcosa che all’altro sfugge, ed entrambi colgono la regola più importante.

Lezione 8

Cinque abitudini che rendono un agente sicuro da usare.

Un agente che legge, scrive ed esegue comandi ha più accesso di molte persone in un team. Queste abitudini valgono sia per il flusso di lavoro dell’agente sia per l’applicazione che costruisce, e ognuna è sostenuta da un controllo, non solo da una frase.

Fuori

  • Commenti e issue
  • Pagine web
  • Documentazione scaricata

Letto come dato, mai come ordine

L’agente

  • Legge il codice
  • Esegue i controlli
  • Modifica su un branch

Leggere segreti: negato

Irreversibile: decide una persona

Una persona

  • Elimina
  • Pubblica
  • Fa il merge
Il testo esterno entra solo come dato. L’agente lavora entro i suoi permessi, e tutto ciò che è irreversibile aspetta una persona.
  • Il testo esterno è un dato, non un ordine.

    Commenti, issue, descrizioni delle pull request, pagine web e documentazione scaricata informano l’agente. Ma chiunque può scriverci, e qualcuno potrebbe provare a dargli istruzioni. La regola è che gli ordini li do solo io, e qualsiasi cosa chieda un testo esterno viene prima verificata.

    Sostenuta da Istruzioni del progetto e revisione umana

  • Il minimo accesso necessario.

    L’agente riceve solo i permessi di cui il compito ha bisogno. La lettura dei segreti è negata, e tutto ciò che è irreversibile (eliminare, pubblicare, fare merge) aspetta una persona.

    Sostenuta da Regole di permesso e liste di divieto

  • Fissa le tue dipendenze.

    Lockfile con versioni esatte e checksum, azioni di integrazione continua fissate per commit e un periodo di attesa prima di installare una versione appena pubblicata. Un attacco alla supply chain di solito viene scoperto nel giro di pochi giorni; aspettare costa poco.

    Sostenuta da Installazioni bloccate e limiti di età delle release

  • I segreti restano fuori.

    Ogni commit viene scansionato prima di essere creato e di nuovo nell’integrazione continua. I file di ambiente sono ignorati, tranne quello di esempio, che non contiene valori reali.

    Sostenuta da Due scanner di segreti indipendenti

  • I dati vengono mostrati come testo.

    Niente di ciò che arriva da un utente o da un’API viene inserito come HTML. Il lint rifiuta quelle operazioni, e una content security policy blocca qualsiasi script che la build non abbia registrato.

    Sostenuta da Lint e una content security policy

Lezione 9

Ciò che richiede attenzione, in un solo pannello.

I problemi che non rompono la build si accumulano in silenzio: dipendenze che invecchiano, vulnerabilità pubblicate in librerie che uso, attività che l’agente ha lasciato «per dopo», un branch rimasto indietro rispetto al remoto. Lo scoprivo tardi, di solito in revisione o quando qualcosa stava già fallendo.

Ho aggiunto una mod che tiene lo stato del progetto accanto alla conversazione con l’agente. Mostra cinque cose.

  • Mappa del lavoro

    Ogni strumento che usa l’agente, con un segno dove un controllo automatico gli ha detto di no.

  • Aggiornamenti

    Cosa è obsoleto in ogni ecosistema, e quanto sarà difficile l’aggiornamento.

  • Vulnerabilità

    Gli avvisi di sicurezza noti per le mie dipendenze, ognuno con un link.

  • In sospeso

    Le attività che l’agente lascia per dopo, in un’unica lista che posso svuotare.

  • Stato del branch

    Un avviso quando sono indietro rispetto al remoto, prima di costruire su codice vecchio.

L’agente e io vediamo la stessa cosa. Posso chiedergli di occuparsi di un avviso specifico prima che diventi un problema, invece di scoprirlo in revisione.

Cosa porto con me

L’IA non mi ha tolto il lavoro. Lo ha cambiato.

Ho smesso di scrivere la maggior parte del codice e ho iniziato a progettare l’ambiente in cui viene scritto: i livelli, le regole che falliscono, l’ordine del lavoro, il cancello prima del merge e la visibilità su ciò che succede. Più quell’ambiente è rigoroso, più libertà posso dare all’agente, perché ciò che è sbagliato non passa.

Se dovessi tenere una sola idea: non cercare di rendere perfetto l’agente. Fai in modo che il progetto si accorga quando non lo è.

Foto di Hernán David Figueroa

Chi è lo sviluppatore

Hernán David Figueroa

Sviluppatore full-stack con più di 8 anni di esperienza, specializzato in fintech e pagamenti sicuri. Lavoro su terminali POS e funzioni di pagamento per Android e iOS presso un gateway di pagamento colombiano. Lavoro con l’IA dal 2022 e con gli agenti da metà 2025. Vivo a Bogotá.

Scrivo e mantengo Guardrail da solo. Vedi il mio profilo da sviluppatore