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.
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
Un’architettura rigorosa, con test e linter che falliscono quando si rompe, trasforma la velocità dell’agente in codice che puoi mantenere.
Lezione 1
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.
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.
Lezione 2
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.
Piccolo: dritto al codice
Grande: prima tracciato
Chiudere
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.
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à.
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.
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.
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.
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.
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
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.
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
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.
ProssimoRivedi il piano web, poi esegui i controlli prima del commit.
Al lavoro, ha bisogno di te, fatto o errore. Intervengo solo dove servo.
L’elenco delle attività dell’agente e dei subagenti che avvia. Posso seguire un lavoro lungo senza leggere ogni messaggio.
Una barra per sessione. Quando si esaurisce, avvio una nuova sessione prima che la qualità cali.
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
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.
Ciò che riceve il mondo esterno: una schermata, una rotta HTTP, un comando. Traduce e delega; non decide.
I casi d’uso. Coordina il lavoro, ma le regole non vivono qui.
Le regole di business. Non sa nulla di database, framework o rete.
Database, servizi esterni, file. Implementa ciò di cui il dominio ha bisogno.
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
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.
È nelle istruzioni del progetto, dove l’agente la legge per prima. Spiega il perché, non solo il cosa.
Un linter, un test o un hook la controlla su ogni macchina, prima di ogni commit o push.
L’integrazione continua rifiuta il merge se si rompe, chiunque sia l’autore, persona o agente.
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
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.
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.
«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.
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.
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.
Lezione 8
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.
Letto come dato, mai come ordine
Leggere segreti: negato
Irreversibile: decide una persona
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
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
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
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
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
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.
Ogni strumento che usa l’agente, con un segno dove un controllo automatico gli ha detto di no.
Cosa è obsoleto in ogni ecosistema, e quanto sarà difficile l’aggiornamento.
Gli avvisi di sicurezza noti per le mie dipendenze, ognuno con un link.
Le attività che l’agente lascia per dopo, in un’unica lista che posso svuotare.
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
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 è.

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