Scrivere codice che gli agenti capiscono 🧠

C’è stato un tempo in cui il codice veniva scritto per il compilatore. Poi è arrivato il momento in cui lo scrivevamo per il collega successivo. Oggi c’è un terzo lettore, e non si accontenta di un buon naming: conta ogni token. L’agente AI legge il tuo codice come un testo da comprimere, non come una storia da leggere con calma. E la qualità di quella compressione dipende interamente da quanto è leggibile ciò che hai scritto.

La leggibilità non è più un lusso estetico: è una leva economica sul contesto.

Il nome è la prima compressione del contesto 🏷️

Una variabile chiamata d non comunica nulla. Una chiamata pendingOrderCount comunica tutto: tipo, stato, significato. Quando un agente processa il tuo codice, ogni nome ambiguo genera una mini-consultazione interna: cosa rappresenta questa cosa? Ogni nome chiaro la elimina.

Il naming esplicito non è pedanteria: è compressione semantica. Un nome buono risparmia all’agente il lavoro di deduzione, e al team il lavoro di interpretazione. Funziona per entrambi i lettori contemporaneamente.

Un nome chiaro è un token che non devi più spendere per spiegare.

La differenza tra processData() e validateAndPersistUserRegistration() non è lunghezza: è densità informativa. La seconda funzione racconta cosa fa prima che qualcuno legga il corpo. Il compilatore non lo apprezza, ma l’agente e il tuo collega delle 5 di sera sì.

Un pattern comune che fallisce in entrambi i contesti: i nomi abbreviati generati da pigrizia, non da economia. tmp, res, val non sono nomi: sono segnali di confusione temporanea codificata nel codice. L’agente li processa, ma deve dedurne il significato dal contesto circostante. Ogni deduzione è un token extra, una latenza in più, un margine di errore che si alza.

Funzioni corte: il vincolo che libera 📏

Una funzione di 200 righe è un problema di contesto, non solo di stile. Quando l’agente deve capire cosa fa quella funzione, deve processare 200 righe di logica per estrarne l’intenzione. Con una funzione di 15 righe, l’intenzione è nel nome e il corpo è una conferma.

Le funzioni lunghe e annidate costringono l’agente a tenere troppe variabili in testa contemporaneamente. Non è diverso da ciò che succede a noi umani: più contesto attivo, più possibilità di confusione. Ma c’è una differenza cruciale: noi possiamo scrollare avanti e indietro con un’occhiata; l’agente paga per ogni riga che processa.

La regola pratica è semplice: se non riesci a descrivere una funzione in una frase, è troppo lunga. Non è un principio estetico, è un vincolo di efficienza. Una funzione corta e con un nome buono fornisce all’agente esattamente il contesto che serve, senza rumore extra.

Una funzione corta è un modulo di contesto atomico: tutto ciò che serve, niente di più.

Coesione: ogni modulo racconta una storia 🧩

Un file ben coeso ha una responsabilità chiara. Quando apri un modulo chiamato order_validation.go, ti aspetti di trovare logica di validazione ordini. Non logica di persistenza, non gestione errori generica, non utility varie. Una cosa, fatta bene, in un posto solo.

La coesione riduce il numero di file che l’agente deve aprire per capire un concetto. Se ogni modulo racconta una storia coerente, il retrieval diventa preciso. L’agente legge il nome del file, apre quello, e trova esattamente ciò che cercava. Nessuna sorpresa, nessuna caccia al tesoro.

In Gestire il contesto come una risorsa parliamo di context hygiene: tenere pulito ciò che entra nella finestra di contesto. La coesione del codice è il primo strumento di questa igiene. Se il codice è ben coeso, meno file servono, meno token si consumano, meno rumore entra nel sistema.

Un segnale che un modulo ha perso coesione: quando per capire una funzione devi aprire tre altri file. Non è sempre un disastro architetturale, ma è un segnale che il contesto necessario per quella funzione si è disperso. E contesto disperso è token sprecato.

Un esempio pratico: un file utils.go con 40 funzioni di natura diversa non è un utilità, è un cestino. L’agente che cerca una funzione di validazione dovrà leggere l’intero file per trovare quella giusta, consumando token per ogni altra funzione irrilevante che attraversa. Un file order_validation.go con 5 funzioni di validazione, invece, è un bersaglio preciso: apri, leggi, capisci. Fine.

Leggibilità come contratto con l’agente 📝

Scrivere codice leggibile per un agente significa fare scelte molto concrete: nomi che raccontano il dominio, funzioni che fanno una cosa sola, file che hanno una responsabilità prevalente. Non è diverso da ciò che raccomandava L’arte di leggere il codice AI, ma dal lato opposto: non è solo leggere il codice generato dall’agente, ma scrivere codice che l’agente possa leggere bene.

C’è un aspetto quasi contrattuale in tutto questo. Quando scrivi codice leggibile, stai facendo una promessa a tutti i tuoi lettori futuri — umani e macchine: questo codice ti dice cosa fa, senza che tu debba supplicare. È un gesto di rispetto verso chiunque dovrà lavorarci dopo, inclusi gli agenti che non hanno il lusso di “sentire” il codice per intuizione.

Il codice leggibile è un contratto: meno spiegazioni servono, meno token costano.

I commenti aiutano, ma solo quelli che spiegano il perché, non il cosa. Il cosa dovrebbe essere nel nome della funzione e nella struttura del codice. Il perché è ciò che nessun nome, per quanto buono, può comunicare da solo. In questo senso, un buon commento è un’annotazione al contratto, non una clausola oscura.

La leggibilità come economia del contesto 💰

Torniamo al punto economico. Più codice serve per capire un concetto, più token consumi. Più token consumi, più paghi e più il tempo di risposta cresce. Ma c’è un effetto meno ovvio: più codice irrilevante processa l’agente, peggiora la qualità della risposta. Il rumore non è solo un costo: è un veleno per il contesto.

Modularità e token ha esplorato questo legame: la modularità riduce i token necessari. La leggibilità è il complemento naturale di quella modularità. Puoi avere un sistema perfettamente modulare ma con nomi criptici e funzioni di 500 righe: l’agente dovrà comunque processare tutto per capire cosa succede.

La combinazione vincente è: modularità per ridurre i file necessari, leggibilità per ridurre il contenuto di ogni file. Insieme, comprimono il contesto in modo esponenziale. È come avere una mappa dettagliata di una città piccola invece di una foto sfocata di un continente: meno dati, più chiarezza.

Modularità e leggibilità non sono principi separati: sono due facce della stessa compressione del contesto.

In pratica: piccole abitudini, grande impatto 🔧

Alcune pratiche concrete che rendono il codice più leggibile per agenti e umani:

• Nomi di funzione che iniziano con un verbo: calculateTotal(), non total(). Il verbo è un indicatore di azione che l’agente può processare in modo diretto.
• Parametri con nomi descrittivi: order *Order, non o *Order. Il costo è zero, il beneficio è costante.
• File con una responsabilità principale: se un file gestisce più di tre concetti concettualmente distanti, è tempo di separare.
• Costanti con nomi che raccontano il dominio: MaxRetryAttempts è meglio di MAX_RETRIES. Non è solo leggibilità, è contesto semantico.
• Errori che comunicano intento: ErrOrderNotFound dice esattamente cosa è successo. ErrGeneric non dice nulla.

Queste scelte non richiedono rivoluzioni architetturali. Richiedono attenzione al nome che scrivi, alla lunghezza della funzione, alla responsabilità del file. È un investimento minimo con ritorno costante, perché ogni riga leggibile è un token che non deve essere spiegato due volte.

C’è un test empirico che funziona sempre: prova a spiegare ad alta voce cosa fa una funzione. Se la spiegazione richiede più di una frase, la funzione probabilmente fa più di una cosa. Se la spiegazione è confusa, il nome è probabilmente confuso. Non è un metodoscientifico, ma funziona meglio di molti audit automatizzati.

Conclusione: il codice come documentazione per tutti 🎯

Per molto tempo abbiamo scritto codice pensando a un lettore umano. Oggi il lettore è diverso, non in più. L’agente non sostituisce il collega: si aggiunge a lui. E la leggibilità serve a entrambi, con una differenza: il collega può permettersi di ignorare il rumore; l’agente lo processa comunque e paga per farlo.

Il codice è documentazione per macchine e umani. Quando è leggibile, entrambi pagano meno.

La prossima volta che scrivi una funzione, chiediti: se un agente dovesse capirla senza contesto aggiuntivo, ci riuscirebbe? Se la risposta è no, il problema non è l’agente. È il nome, la lunghezza, la coesione. Sono le leve che hai in mano, e non richiedono permessi speciali per essere usate.

Il bello di tutto questo è che non serve un manifesto né una convention team. Basta una domanda, ripetuta ogni giorno: questo codice racconta chiaramente cosa fa? Se la risposta è sì, l’agente lo capirà. Il collega lo capirà. E tu, tra sei mesi quando tornerai su quella funzione, lo capirai anch’esso. A volte la semplicità è la rivoluzione più efficace.