Il tuo agente di coding copia il tuo codice peggiore
Gli agenti di coding copiano l'architettura che vedono. Scopri quali fatti architetturali scrivere, come attributi di qualità, confini e ADR, e come verificarne l'effetto.
Architettura del software · Fonderia del software · Documentazione dell'architettura

Il video è in inglese. La trascrizione qui sotto è una traduzione.
Il diff che sembrava a posto
Questo è un diff concreto di uno dei miei progetti di esempio. L'agente di coding ha aggiunto una funzionalità, i test passano, il controllo dei tipi è pulito, la review sembrava a posto. Ma il nuovo codice nel modulo billing importa il data store dal modulo orders e legge gli ordini direttamente dal data store dell'altro modulo.
Il codice era brutto? No, era corretto, leggibile e testato. Solo che nessuno aveva detto all'agente che questa chiamata è vietata.
In un progetto presso un cliente è successo più di una volta, e quando ho dato lo stesso compito a 5 sessioni fresche dell'agente, è successo 5 volte su 5. Ti mostro che cosa lo ha fermato davvero.
Dopo questo episodio sarai in grado di guardare un cattivo output di un agente e chiederti quale fatto architetturale mancava davvero. Potrai poi scrivere quel fatto nel posto in cui l'agente lo legge. Vedrai una configurazione piccola e concreta e un modo per verificare se funziona: lo stesso compito, lo stesso modello, lo stesso prompt, eseguito più volte, prima e dopo.
Gli agenti copiano ciò che vedono
Ecco che cosa mi ha sorpreso. Sulla versione pulita del mio esempio l'agente non ha commesso quell'errore. Cinque sessioni su cinque hanno tenuto billing fuori dai dati di orders senza che nessuno glielo dicesse. Il codice pulito porta con sé la propria architettura, e l'agente la legge.
Allora ho cambiato una cosa. Ho fatto in modo che la base di codice sembrasse una vera, dopo qualche anno, in cui qualcuno ha già preso una scorciatoia. Qui, nel modulo users, hanno importato direttamente il datastore di orders per leggere il numero di ordini dell'utente. Il numero di ordini viene letto qui sotto, con accesso diretto al datastore di orders. E nessuno ha detto loro che era un errore, e non era scritto da nessuna parte.
Questi sono i diff degli agenti che hanno lavorato sul codice. Su quel codice eroso, ogni sessione ha copiato la scorciatoia. Tre l'hanno perfino confezionata bene: una port in billing più un adapter in billing che importa orders. Sembra ports and adapters, ma la dipendenza punta nella direzione sbagliata. I test erano verdi ogni volta.
La maggior parte dei cattivi output degli agenti è una soluzione locale corretta. L'agente segue il precedente che trova nel codice, e solo il team sa che quel precedente è sbagliato.
L'agente vede i file che apre, non la vostra storia. Attributi di qualità, confini dei contesti e opzioni scartate vivono nelle teste, in wiki che nessuno apre e in vecchie riunioni.
Un esempio: un agente rompe il confine, lo correggiamo in review, alla sessione successiva lo rompe di nuovo. Le correzioni in chat spariscono con la sessione. Resta solo ciò che è nel repository.
Potresti dire: «In futuro un modello migliore dedurrà l'architettura.» Sul codice pulito lo fa già, ma può dedurre solo ciò che il codice mostra. Quando il codice contraddice la tua intenzione, l'agente non distingue la regola dall'eccezione, e non sa perché billing non debba leggere dati da orders.
Che cosa scrivere
Tre tipi di conoscenza cambiano più di tutti l'output dell'agente: gli attributi di qualità, i confini dei contesti e le decisioni con le loro motivazioni.
Gli attributi di qualità dovresti averli come affermazioni verificabili. Non solo «il nostro sistema deve essere velocissimo e scalabile», ma «300 millisecondi per il checkout nel 95% dei casi, con carico normale». Billing può essere rilasciato senza orders. Queste indicazioni guidano l'agente. «Scalabile» da solo no.
Bounded context: dai loro un nome, elenca chi può parlare con chi e come, per esempio con eventi o API, mai con il datastore dell'altro modulo. Un paragrafo e un piccolo diagramma in forma testuale.
E gli ADR: contesto, decisione, conseguenze e soprattutto le alternative scartate. Altrimenti l'agente ripropone l'alternativa scartata, con sicurezza. E in una base di codice erosa, l'alternativa scartata è spesso proprio lì nel codice, pronta per essere copiata.
Un esempio: l'ADR per il mio progetto. Billing legge i dati degli ordini solo attraverso una port propria. Uso il formato Y-statement, una frase in sei parti. Suona così. Nel contesto dell'emissione di fatture per gli ordini, di fronte alle esigenze che abbiamo, rilasci separati di billing e orders da una parte e proprietà separata dei dati dall'altra. Che cosa abbiamo deciso? Abbiamo deciso per una port in billing che la composition root riempie con la API pubblica del modulo Orders, e abbiamo scartato altre opzioni, come billing che importa lo store di orders e un adapter dentro billing che importa orders. Vogliamo ottenere che billing possa essere rilasciato senza orders, accettando una funzione in più da collegare.
Potresti dire: «È un sacco da scrivere.» Giusto, quindi ecco un consiglio per risparmiare tempo. Parti dalla decisione che il tuo agente ha già violato. Scrivi l'ADR a partire dal commento di review che hai dato. Poi fai lo stesso la prossima volta che il tuo agente non fa ciò che vuoi.
Mettilo dove l'agente legge
La conoscenza serve solo se è nel contesto dell'agente al momento giusto, e se è abbastanza breve da essere usata.
Nel mio esempio è bastato pochissimo. Un breve file CLAUDE.md che dice: ogni modulo possiede i propri dati, un modulo importa solo i propri file, quando ha bisogno di qualcosa da un altro modulo dichiara una port, e la composition root, src/app.ts, riempie le port. Più quella composition root vuota, così c'è un posto ovvio per il collegamento.
In un sistema reale CLAUDE.md cresce fino a contenere lo scopo del sistema, i tre principali attributi di qualità, la context map e regole come «prima di cambiare qualcosa a cavallo dei moduli, leggi docs/adr/», e un indice degli ADR con riassunti di una riga. Questo indice conta. L'agente apre l'ADR rilevante per il compito invece di caricare tutto. Quindi scrivi i titoli degli ADR come affermazioni, per esempio «Un bounded context non legge mai dati da altri bounded context».
Prima: billing legge lo store di orders. Dopo: billing dichiara una port, orders pubblica il metodo di lettura e src/app.ts collega i due. In tutte e cinque le sessioni.
Per onestà, è un modello, una funzionalità, cinque esecuzioni ciascuno. Il tuo agente e la tua base di codice possono ovviamente comportarsi diversamente, quindi misuralo sul tuo codice. Esegui lo stesso compito alcune volte prima e dopo e confronta i diff.
Farlo rispettare, tenerlo vivo
La documentazione che l'agente legge è il primo livello. I controlli che fanno fallire la build sono il secondo. L'agente rende economico mantenere aggiornata la documentazione.
Trasforma le regole più importanti in fitness function: un test di architettura come, per esempio, ArchUnit, import-linter o equivalenti, che fallisce a ogni import oltre il confine di un modulo. Le violazioni legacy, se esistono, finiscono in una lista che può solo ridursi.
Ecco che cosa mi ha sorpreso di nuovo. Nelle mie esecuzioni il test non è mai diventato rosso. Gli agenti lo leggevano prima della prima modifica e lo seguivano. Anche senza CLAUDE.md, il test e la composition root vuota hanno tenuto tutte e cinque le sessioni entro i loro confini. Quindi anche il test è documentazione, e per fortuna una che non può invecchiare senza che la build te lo segnali.
Questo test fermerà un agente che ignora tutto? Le mie esecuzioni non potevano mostrarlo, perché nessun agente l'ha fatto. Ed è proprio per questo che c'è. Non costa nulla finché l'agente si comporta bene, e blocca il merge quando non lo fa. È anche un buon giudice. Eseguilo dopo ogni sessione dell'agente, e ogni riga rossa indica un nuovo import che attraversa il confine.
Potresti pensare: «Questa è solo documentazione, non l'abbiamo mai tenuta aggiornata.» Beh, con l'introduzione degli agenti di coding una cosa è cambiata. Prima la documentazione non aveva un lettore che agisse ogni giorno in base ad essa. Ora ce l'ha. Un ADR obsoleto produce visibilmente codice sbagliato nel giro di pochi giorni, quindi l'obsolescenza viene notata.
Rendi l'agente parte della manutenzione. Quando una modifica contraddice un ADR, l'agente deve o rispettarlo o proporre un nuovo ADR nella stessa pull request. Una persona rivede quella decisione, non la prosa.
Quindi, tienilo piccolo. Dieci ADR accurati valgono molto più di cento mai letti. Naturalmente tutto questo non sostituisce review fatte bene, e anche un ADR può essere sbagliato. Ma almeno rende visibile il disaccordo.
Conclusione e prova pratica
Ricorda: il tuo agente copia l'architettura che vede. Se il tuo codice non la mostra più, scrivila dove l'agente legge.
Quindi prova così. Prendi gli ultimi tre commenti di review in cui hai detto a un agente o a un collega: «qui non si fa così». Scrivi ciascuno come un breve ADR o una riga di attributo di qualità, collegali da CLAUDE.md ed esegui di nuovo uno degli stessi compiti. Confronta i diff. Facoltativamente, aggiungi un test di architettura per la regola che contava di più.
Vuoi provarlo nella pratica? Usa il link ad Architecture Practice Lab nella descrizione di questo video. Ottieni il repository di esempio erodo di questo episodio. Dagli lo stesso compito con il tuo agente, Claude o un altro, e guarda se mantiene i confini. Poi scrivi l'architettura, riprova e ricevi un feedback dal mio agente revisore, che ho addestrato su regole per una buona architettura.
A presto!