Il ritmo del software è accelerato. L’architettura è rimasta ferma.

Questa frase semplice e provocatoria descrive una condizione che chiunque lavori con sistemi software complessi in contesto enterprise riconosce immediatamente. Non serve teorizzare: basta pensare all’ultima volta che hai provato a capire perché un sistema si comporta in un certo modo. E hai scoperto che i diagrammi disponibili raccontavano qualcosa di diverso da quello che il codice fa davvero.

Il problema dell’architettura nell’enterprise

Documentazione incompleta, obsoleta o frammentata. Gli architetti documentano nelle fasi iniziali del progetto, poi con il tempo l’implementazione prende strade divergenti e l’infrastruttura evolve. Risultato? I diagrammi e la documentazione descrivono l’intenzione iniziale e non il sistema reale. Chi arriva dopo — un nuovo collega, un team differente, chi si occupa di operation — si trova a lavorare con una mappa che non corrisponde alla realtà.

La conoscenza vive nella testa delle persone. Ogni sistema ha i suoi custodi: le poche persone che “sanno come funziona davvero”. Quando una di queste persone lascia il team, porta via con sé mesi o anni di decisioni, compromessi, ragionamenti. Quello che rimane è codice senza contesto.

Nessuno conosce il sistema intero. Ogni team conosce bene il proprio pezzo. Sa come funziona il proprio servizio, conosce le sue dipendenze dirette, gestisce i propri problemi. Ma la visione end-to-end — come i pezzi si tengono insieme, dove sono i punti di fragilità, cosa succede quando qualcosa va storto a monte — quella manca. E manca sistematicamente.

Architettura, codice e infrastruttura non parlano tra loro. Il codice evolve in risposta ai requisiti, all’infrastruttura disponibile, alle scelte del team. I diagrammi, invece, restano fermi. Non per negligenza, ma perché aggiornarli è costoso, frammentato, mai prioritario. Col tempo i tre livelli — cosa si è pensato, cosa si è scritto, cosa gira in produzione — diventano tre cose diverse.

La conseguenza di tutto questo è prevedibile: onboarding di nuove persone lento, troubleshooting caotico, decisioni architetturali reattive invece che intenzionali. Non si guida più l’evoluzione del sistema: la si rincorre.

Perché succede e perché adesso si può fare diversamente

Questo non è un problema nuovo. È un problema strutturale che esiste da quando i sistemi software hanno cominciato a crescere più velocemente della capacità di documentarli. Quello che però è cambiato, negli ultimi anni, è che abbiamo a disposizione pratiche e strumenti che permettono di affrontarlo in modo diverso.

L’infrastruttura si gestisce “as code” come codice. Kubernetes ha reso dichiarativa la relazione tra applicazione e runtime. Il GitOps ha portato versionamento e tracciabilità su tutto il ciclo di vita. Il platform engineering orienta verso modelli operativi uniformi che attraversano i team.

In questo ecosistema, trattare l’architettura come codice non è più un’idea visionaria: è una conseguenza logica di come già lavoriamo ed è il punto di raccordo che permette di guidare e rendere coerenti le altre pratiche “as code”.

Cosa significa in concreto

Architecture as Code non è uno strumento, né un framework. È un modo di concepire il ruolo che l’architettura occupa nel ciclo di vita del software. In pratica, si compone di quattro ingredienti.

Un modello architetturale descritto in modo formale. Non un disegno su una slide, ma una rappresentazione strutturata, versionata, leggibile dalle persone e interpretabile dagli strumenti. Il C4 Model è un possibile riferimento utile: permette di descrivere il sistema a diversi livelli di astrazione — dal contesto esterno fino ai dettagli implementativi — senza dover gestire tutto con lo stesso livello di dettaglio. I livelli alti (contesto e container) sono relativamente semplici da mantenere e subito utili. I livelli più profondi richiedono più sforzo e hanno senso solo quando il team è pronto a sostenerli o se si sfruttuano strumenti o automazioni in grado di derivarli.

Un DSL per rendere operativo il modello. Un Domain Specific Language — come Structurizr o likeC4 per chi usa C4 — permette di descrivere l’architettura come si scrive codice: in un file, in un repository, con una history. Da quel file si possono generare diagrammi, esportare documentazione, verificare vincoli, creare repository e generare scaffolding per guidare l’implementazione. L’architettura smette di essere un artefatto separato e diventa parte del repository di progetto.

ADR per tracciare le decisioni. Architecture Decision Record: documenti brevi, strutturati e legati al modello, che registrano non solo cosa si è deciso ma perché, quali alternative sono state considerate, quali vincoli hanno orientato la scelta. Sono la memoria del sistema. Quando un nuovo collega chiede “perché usate questo database?” o “perché questa separazione tra servizi?”, la risposta non dipende più dal fatto che ci sia ancora in giro qualcuno che era presente in quella riunione.

Requisiti non funzionali come parte del modello, non come nota a margine. Sicurezza, performance, affidabilità, resilienza: spesso vengono elencati in un documento separato, o peggio dati per scontati. Nell’approccio Architecture as Code diventano parte esplicita del modello e, quando possibile, tradotti in fitness function: metriche quantitative che permettono di misurare, nel tempo, quanto il sistema reale resta allineato con l’architettura desiderata. Non dichiarazioni di intenti, ma soglie verificabili da usare come punto di rilevamento nelle fasi del ciclo di vita del software.

Approcci: top-down, bottom-up e il ruolo dell’AI

Ma c’è una tensione che emerge sempre sul campo: si parte dall’intenzione o dalla realtà?

L’approccio top-down, partire da un foglio bianco definendo l’architettura target e scendere verso il dettaglio, è quello che si segue quando si parte con un nuovo progetto. È ordinato, intenzionale, utile per guidare i team. Il rischio è che resti ai livelli alti e perda contatto con il codice reale nel momento in cui lo sviluppo comincia.

L’approccio bottom-up, analizzare il sistema esistente, il legacy, e con quello provare a ricostruirne l’architettura, è indispensabile quando la documentazione manca o è inaffidabile. Il limite è che fotografa il passato e rischia di consolidare il debito tecnico invece di aiutare a superarlo.

Il punto di arrivo più efficace è la combinazione dei due: dichiarare i livelli alti con intenzionalità, inferire quelli più bassi a partire dal codice e dall’infrastruttura reale, e usare questo doppio movimento per governare il sistema con consapevolezza.

È qui che l’intelligenza artificiale generativa diventa rilevante — non come soluzione magica, ma come moltiplicatore di capacità. Attività che erano possibili ma troppo costose, ricostruire un’architettura a partire dal codice, costruire tool di analisi, verificare la coerenza tra modello e implementazione, individuare lacune nei requisiti non funzionali, oggi sono molto più accessibili.

L’AI non sostituisce l’architetto, ma riduce il costo di quel lavoro di collegamento tra ciò che si è immaginato e ciò che è stato davvero costruito.

Un cambio di postura, prima che di strumenti

L’aspetto forse più importante di Architecture as Code è che cambia nel modo di pensare al ruolo dell’architettura nel progetto.

Nella pratica comune, l’architettura spesso viene definita all’inizio, poi il progetto va avanti mentre lei resta indietro. Con questo approccio, l’architettura ha un ruolo cruciale nel ciclo di vita di una soluzione: guida le prime scelte, definisce i repository, fissa i vincoli, orienta le decisioni tecnologiche, e poi accompagna il team lungo tutto il ciclo di vita. È il principio dello shift-left applicato al governo architetturale.

Significa anche che l’architettura non è più un prodotto consegnato una volta sola. È una pratica continua, distribuita nel team, sostenuta dagli strumenti. Non un disegno bello che invecchia appena il progetto entra in produzione, ma è qualcosa che può essere aggiornato, validato, discusso, contestato — esattamente come il codice.

Architecture as Code non promette di eliminare la complessità dei sistemi enterprise. Promette qualcosa di più realistico e forse più utile: esplicitare quella complessità, per renderla governabile nel tempo, con strumenti e pratiche che già conosciamo, applicati a un problema che abbiamo rimandato abbastanza a lungo.

Questo è il primo di tre blog post nati da un intervento alla Moka Conference 2026