Modularità e token: quando l'architettura paga anche la bolletta AI 💸

Il codice non è mai stato solo per le macchine 🤖

Per anni abbiamo ripetuto una frase quasi liturgica: il codice deve essere scritto per gli esseri umani, non per il compilatore. Il compilatore, in fondo, è il lettore più permissivo del team: non si lamenta dello stile, non ti chiede perché hai messo tre responsabilità in una funzione, non ti invita a prendere aria dopo il terzo if annidato.

Oggi però c’è un nuovo lettore al tavolo: l’agente AI. E questo lettore ha una caratteristica speciale, quasi brutale nella sua onestà: conta i token. Ogni domanda, ogni file caricato, ogni riga superflua si traduce in una metrica concreta. Non in un giudizio estetico, ma in costo, tempo di risposta e qualità del risultato.

Il codice resta linguaggio umano, ma ora vive anche dentro un’economia del contesto.

La nascita della modularità: ridurre la complessità umana 🧠

La modularità non nasce perché ci piace ordinare le cartelle come il cassetto delle posate. Nasce per ridurre il carico cognitivo. Quando separi responsabilità, stai dicendo una cosa molto semplice: nessuno dovrebbe capire tutto, tutto insieme, sempre.

Un modulo è una promessa: entro questi confini succede questa cosa, con queste regole, senza sorprese teatrali. E quella promessa serve prima di tutto a noi, quando torniamo su un progetto dopo due mesi e ci chiediamo chi sia stato il criminale che ha scritto quel passaggio. Di solito il criminale siamo noi, ma questa è un’altra storia.

La buona modularità riduce il rumore, rende le dipendenze visibili e spezza i problemi in unità gestibili. In altre parole, trasforma un territorio ostile in una mappa leggibile.

Il principio di responsabilità singola come strumento di chiarezza 🎯

Il Single Responsibility Principle non è una regola da puristi da conferenza. È un principio di sopravvivenza operativa: se una componente fa una sola cosa, la sua superficie mentale si restringe, con meno concetti da tenere in testa, meno dipendenze nascoste e meno effetto domino quando tocchi una riga.

Quando invece una funzione valida input, chiama servizi esterni, formatta output e nel tempo libero prepara anche il caffè, non hai un componente. Hai un romanzo russo in una singola pagina.

SRP, in pratica, è un gesto di rispetto verso chi dovrà leggere, modificare e mantenere quel codice, incluso il tuo io del futuro, che merita almeno un minimo di compassione.

Il nuovo vincolo: contesto scarso, costo reale 🧾

Qui cambia davvero il gioco. Con gli LLM entrano in scena vincoli che, fino a ieri, potevamo ignorare con una scrollata di spalle:

• la finestra di contesto è limitata;
• ogni token ha un costo economico e computazionale;
• più contesto significa maggiore latenza;
• il contesto irrilevante peggiora la qualità delle risposte.

Nel passato il rumore informativo era soprattutto un problema cognitivo umano. Oggi è anche un costo diretto, misurabile e ripetibile. Per paura che manchi qualcosa, tendiamo infatti a dare all’agente tutto il repository: sembra prudenza, spesso è sabotaggio elegante. Se carichi 20 file quando ne bastavano 3, non stai solo confondendo l’agente: stai pagando per confonderlo.

La confusione non è più solo un difetto architetturale: è una voce di spesa.

Più contesto indiscriminato comporta quattro effetti quasi garantiti:

• consumo di token più alto;
• rischio di focus errato;
• tempo di inferenza maggiore;
• rapporto segnale/rumore peggiore.

Se vuoi una metafora concreta: è come rispondere a una domanda puntuale portando in riunione l’intero archivio storico dell’azienda. Tecnica impeccabile, risultato comico.

Il contesto non è gratuito: è una risorsa che si consuma.

Modularità come compressione del contesto (e dei token) 🗜️

Quando il codice è davvero modulare, succede una cosa potente: non devi raccontare tutto per ottenere una risposta buona. Basta raccontare il pezzo giusto. La modularità diventa quindi una forma di compressione semantica.

In pratica ottieni tre vantaggi diretti:

• riduci il contesto necessario per ogni operazione;
• abbassi il numero di file da leggere;
• ottimizzi il consumo di token senza sacrificare precisione.

Un modulo ben progettato è autoesplicativo nel suo dominio: nome chiaro, dipendenze esplicite, responsabilità unica. Per questo il retrieval diventa più preciso, le letture inutili diminuiscono e le risposte utili arrivano più in fretta.

Il refactoring non riduce solo la complessità: riduce la bolletta dei token.

Chi ha già lavorato con il context engineering lo sa: il miglior contesto non è il più grande, è il più pertinente.

SRP e modularità come leva economica ⚖️

Fin qui potremmo dire di non aver scoperto nulla di nuovo: chiarezza, confini, basso accoppiamento. La novità è che questi principi non migliorano solo il lavoro umano, ma cambiano anche il costo operativo quando usi agenti AI in modo intensivo.

Questa tabella può sembrare banale, ma racconta un passaggio culturale importante: principi nati per la qualità ingegneristica oggi hanno anche un impatto finanziario misurabile. Non è cinismo, è realtà operativa. Se usi agenti ogni giorno, la qualità architetturale diventa una leva economica oltre che tecnica.

Il problema dei monoliti: esplosione di token inutili 🧱

Un monolite non è necessariamente il male assoluto. Ma un monolite disordinato, opaco e multi responsabilità diventa rapidamente un acceleratore di sprechi, perché:

• obbliga a caricare molto più codice del necessario;
• aumenta il costo medio per task;
• rende il retrieval rumoroso e meno affidabile;
• costringe l’agente a dedurre troppo da segnali ambigui.

In questo senso, il monolite moderno rischia di essere anche un monolite di token: non solo difficile da mantenere, ma costoso da interrogare.

Per capire quando la complessità architetturale smette di essere virtù e inizia a essere posa, resta utile anche Meno architettura è meglio (finché non fa male): semplicità sì, ma con confini leggibili.

Architetture AI-aware: dal principio alla pratica 🧭

Se sappiamo che il contesto è una risorsa scarsa, allora dobbiamo progettare software AI-aware. Non significa inseguire la moda del momento: significa allineare architettura e uso reale degli agenti, fino alle abitudini quotidiane di scrittura del codice.

Alcune scelte aiutano subito:

• API piccole, esplicite e semanticamente isolate;
• moduli autocontenuti, con interfacce chiare;
• dipendenze implicite ridotte al minimo;
• naming che faciliti navigazione e retrieval automatico.

L’obiettivo non è avere un codice “bello” in astratto. L’obiettivo è massimizzare il rapporto tra informazione utile e token consumati.

Se vuoi rafforzare questo approccio sul lato pratico della richiesta ai modelli, la guida Prompt engineering è un ottimo complemento operativo.

Nel lavoro quotidiano questo si traduce in abitudini progettuali molto concrete:

• funzioni brevi e focalizzate;
• naming esplicito, per ridurre letture esplorative;
• file con una responsabilità prevalente;
• riduzione del grep cost per umani e agenti;
• confini chiari tra dominio, infrastruttura e integrazioni.

Una pratica semplice ma potente è introdurre un token budget per task di sviluppo, non come metrica punitiva ma come strumento di progettazione:

• quale contesto è veramente necessario per questa modifica?
• quali file sono essenziali e quali solo “forse utili”?
• posso ottenere lo stesso risultato con metà del contesto?

Un accorgimento ancora più pragmatico è evitare di infilare nei token di input file interi che potrebbero non servire: meglio indicare nel prompt i path dei file potenzialmente utili e lasciare che sia l’agente a decidere se aprirli davvero.

Chi adotta questa disciplina scopre un effetto collaterale interessante: migliora anche la qualità delle review umane, perché costringe a separare meglio intenzioni, confini e impatti.

Un buon allenamento è applicare lo stesso approccio iterativo descritto in Question-Driven Specification: prima chiarisci il perimetro, poi allarghi solo se serve.

Conclusione: dal software leggibile al software economico 🧮

Per molto tempo abbiamo scritto codice pensando alla leggibilità umana. Era giusto, e resta giusto, ma oggi c’è una seconda responsabilità: scrivere codice che non sprechi contesto quando viene letto da agenti AI.

La buona architettura non è solo elegante: è anche efficiente, perché comprime il contesto, riduce il rumore e abbassa il costo dell’intelligenza artificiale applicata allo sviluppo.

In passato cercavamo codice comprensibile. Oggi dobbiamo cercare codice comprensibile ed economico.

La buona notizia è che non serve inventare nuovi dogmi: spesso bastano vecchi principi applicati con disciplina moderna, con meno rumore, più chiarezza e meno token buttati nel vuoto.

Se nel prossimo refactoring vuoi un criterio in più oltre alla “pulizia”, prova questo: quanti token sto risparmiando a ogni task futuro? Potrebbe essere la metrica più pragmatica dell’anno.