La deriva architetturale è lo scarto tra il sistema che hai documentato e il sistema che hai davvero. I consigli standard al riguardo (tieni i documenti accanto al codice, rivedili nella stessa pull request) sono buoni, e nessuno di essi ti dice se ha funzionato. Questa guida copre cos'è la deriva, i modi per rilevarla e come mettere un numero sullo scarto che hai già.

Rilevamento della deriva architetturale: mantieni il codice allineato al design

Da qualche parte nella tua organizzazione c'è un diagramma dell'architettura sbagliato. Forse mostra un microservizio che è stato unito a un altro sei mesi fa. Forse elenca Redis come livello di cache quando il team è passato a Memcached durante un incidente di produzione. Forse descrive una architettura esagonale pulita in un servizio che ha accumulato abbastanza scorciatoie e workaround da sembrare spaghetti code.

Questa è la deriva architetturale: la divergenza graduale e silenziosa tra come il sistema è documentato e come funziona realmente. A differenza dei bug, la deriva non attiva alert. A differenza delle regressioni di performance, non appare nel monitoring. Resta tranquilla finché qualcuno non prende una decisione basata su documentazione obsoleta -- e quella decisione si rivela sbagliata.

La deriva architetturale è universale. Ogni team la sperimenta. La domanda non è se la documentazione subirà una deriva, ma quanto velocemente la rileverai e cosa farai al riguardo.

Di consigli sulla seconda metà della domanda non c'è penuria. Tieni i documenti accanto al codice. Rivedili nella stessa pull request. Rendili parte della definition of done. Sono buoni consigli, gran parte di essi compare più in basso in questa pagina, e condividono un punto cieco: ti dicono cosa fare, non se ha funzionato. La cosa che nelle raccomandazioni correnti somiglia di più a una verifica è un timestamp di ultima modifica, che ti dice quando qualcuno ha toccato il file, non se il file dice il vero.

Rilevare la deriva è la metà che si salta. Questa guida copre il problema, le cinque famiglie di metodi di rilevamento e cosa ciascuna riesce e non riesce a vedere. Due articoli complementari approfondiscono ciascuno una cosa: come si calcola un drift score e cosa significa quel numero e le pratiche che mantengono vero un modello una volta che ce l'hai.

Cos'è la deriva architetturale?

La deriva architetturale si verifica quando l'implementazione effettiva di un sistema software diverge dalla sua architettura documentata o prevista. Perry e Wolf hanno dato un nome al problema in Foundations for the Study of Software Architecture (ACM SIGSOFT Software Engineering Notes, 1992), dove separavano l'erosion (erosione), che nasce dal violare l'architettura, dal drift, che nasce dall'essere insensibili a essa. L'uso quotidiano si è spostato da allora: oggi la maggior parte degli ingegneri dice "deriva" per qualsiasi scarto tra la documentazione e il codice, ed è in questo senso che la usa questa guida. La distinzione vale comunque la pena di essere mantenuta, e più sotto c'è una sezione dedicata.

La deriva si manifesta a ogni livello della documentazione architetturale:

Deriva strutturale

La struttura documentata non corrisponde più alla codebase:

Un servizio documentato come container autonomo è stato assorbito in un monolite
Un componente è stato rinominato ma il diagramma mostra ancora il vecchio nome
Un nuovo servizio è stato creato ma mai aggiunto al modello architetturale
Un database è stato migrato da MySQL a PostgreSQL ma il diagramma dei container dice ancora MySQL

Deriva comportamentale

Il comportamento documentato non corrisponde più alla realtà:

Una chiamata API sincrona è stata sostituita da un messaggio asincrono, ma la relazione dice ancora "REST/HTTP"
Un flusso di dati è stato modificato per passare da un API gateway, ma il diagramma mostra comunicazione diretta tra servizi
È stato aggiunto un passaggio di autenticazione che non si riflette nel diagramma di contesto di sistema

Deriva delle dipendenze

Le dipendenze documentate non corrispondono più alle integrazioni reali:

Un'API di terze parti è stata sostituita da qualcosa costruito internamente
È stata aggiunta una nuova dipendenza esterna (provider di pagamento, servizio di monitoring) ma non documentata
Un'integrazione è stata dismessa ma appare ancora nel diagramma di contesto di sistema

Deriva delle decisioni

Le decisioni architetturali documentate non vengono più seguite:

Un ADR dice "usare PostgreSQL per tutto lo storage persistente" ma un team ha iniziato a usare MongoDB
Le regole di conformance dicono "nessun accesso diretto al database dal frontend" ma qualcuno ha aggiunto un'integrazione Supabase lato client
L'architettura di deployment dice "singola region" ma i servizi sono stati deployati su più region

Perché avviene la deriva architetturale

Capire le cause della deriva è essenziale per prevenirla. La deriva di solito non è né malevola né tantomeno negligente -- è una conseguenza naturale di come il software viene sviluppato.

La velocità prima della documentazione

Quando una feature va consegnata entro venerdì, aggiornare il diagramma dell'architettura è la prima cosa che salta. La modifica al codice è il deliverable. L'aggiornamento della documentazione è overhead. È un comportamento razionale nel breve termine e devastante nel lungo.

Molti piccoli cambiamenti

La deriva raramente avviene in un momento drammatico. Si accumula attraverso centinaia di piccoli cambiamenti, ciascuno troppo minore per giustificare un aggiornamento della documentazione:

Rinominare un file
Aggiungere un package di utilità
Cambiare una dipendenza di libreria
Estrarre una funzione in un modulo separato

Nessun cambiamento singolo è abbastanza significativo da innescare un aggiornamento della documentazione. Insieme, trasformano l'architettura.

Turnover del team

Quando gli ingegneri se ne vanno, portano via con sé la conoscenza implicita. Il nuovo team eredita la codebase ma non la comprensione del perché sia strutturata così. Fanno modifiche in base a ciò che vedono nel codice, non a ciò che dice la documentazione, allargando la deriva.

Assenza di cicli di feedback

Se nessuno verifica che la documentazione corrisponda alla realtà, la deriva è invisibile. Senza un meccanismo di rilevamento, l'unico modo per scoprirla è durante un incidente, un audit, o quando un nuovo ingegnere fa notare che il diagramma non corrisponde al codice. A quel punto la deriva può essere estesa.

Modifiche d'emergenza

Gli incidenti di produzione richiedono spesso scorciatoie architetturali: una connessione diretta al database invece di passare per il livello API, una configurazione hardcoded invece di usare il config service, una cache temporanea che diventa permanente. Queste modifiche scavalcano i normali processi di review e vengono documentate di rado.

Il costo della deriva architetturale

La deriva non è solo un problema estetico. Ha costi concreti e misurabili.

Decisioni sbagliate

Quando gli architetti prendono decisioni basate su documentazione obsoleta, quelle decisioni possono essere sbagliate. "Questo servizio ha poco traffico, quindi possiamo permetterci una dipendenza sincrona" -- solo che la documentazione è vecchia e il servizio in realtà gestisce 10x il carico documentato.

Onboarding lento

I nuovi ingegneri si affidano alla documentazione dell'architettura per costruire il proprio modello mentale. Se la documentazione è sbagliata, costruiscono modelli mentali sbagliati. Scrivono codice che non si adatta all'architettura reale. Fanno domande che rivelano la loro confusione, consumando il tempo degli ingegneri senior.

Risposta agli incidenti

Durante un incidente di produzione, i diagrammi dell'architettura dovrebbero aiutare i team a capire il raggio d'impatto e le dipendenze. Se quei diagrammi sono sbagliati, i team sprecano minuti preziosi seguendo le catene di dipendenze sbagliate o non vedendo sistemi upstream critici.

Fallimenti di compliance e audit

Nei settori regolamentati, la documentazione dell'architettura è spesso richiesta per la compliance (SOC 2, ISO 27001, HIPAA). Se gli auditor riscontrano che la documentazione non corrisponde alla realtà, è un rilievo -- potenzialmente grave.

Confusione degli agenti IA

Man mano che gli agenti di coding IA si diffondono, si affidano sempre più alla documentazione dell'architettura per il contesto. Un agente che legge un modello C4 obsoleto genererà codice che si adatta all'architettura documentata, non a quella reale. Questo amplifica la deriva invece di correggerla.

Come rilevare la deriva architetturale

Ci sono cinque approcci di uso comune, e rispondono a domande diverse. La review manuale chiede se il diagramma sembra ancora corretto alle persone presenti nella stanza. Le fitness function e l'analisi statica chiedono se vengono infrante regole specifiche. La valutazione con LLM chiede se il codice si legge come il design che dichiara di implementare. Il drift scoring chiede quanta parte del modello documentato esista ancora. Scegli in base alla domanda che ti sta costando di più.

Review manuale (approccio tradizionale)

L'approccio più semplice è la review manuale periodica: riunisci il team, ripercorri i diagrammi dell'architettura e verifica se corrispondono ancora alla realtà.

Quando funziona: team piccoli, architetture semplici, cadenza trimestrale.

Quando fallisce: sistemi grandi, team che si muovono velocemente, o quando le persone che conoscono meglio il codice non hanno tempo per riunioni di review. La review manuale soffre anche di bias di conferma -- le persone tendono a vedere ciò che si aspettano di vedere.

Architecture fitness function

Le fitness function, rese popolari da Neal Ford e dal libro "Building Evolutionary Architectures", sono test automatizzati che validano proprietà architetturali:

// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
    packages := analyzeImports("./internal/handler/...")
    for _, pkg := range packages {
        for _, imp := range pkg.Imports {
            assert.NotContains(t, imp, "database/sql",
                "Handler %s imports database/sql directly", pkg.Name)
            assert.NotContains(t, imp, "gorm.io",
                "Handler %s imports GORM directly", pkg.Name)
        }
    }
}

Le fitness function sono potenti per far rispettare regole specifiche, ma richiedono uno sforzo iniziale per essere scritte e mantenute. Verificano vincoli, non il modello completo.

Strumenti di analisi statica

Strumenti come ArchUnit (Java), Deptrac (PHP) e go-arch-lint (Go) analizzano la struttura del codice e fanno rispettare regole di dipendenza:

// go-arch-lint configuration
components:
  handler:
    in: ./internal/handler/
  service:
    in: ./internal/service/
  repository:
    in: ./internal/repository/

rules:
  handler:
    can_depend_on: [service]
  service:
    can_depend_on: [repository]
  repository:
    can_depend_on: []

Questi strumenti sono eccellenti per far rispettare un'architettura a livelli all'interno di una singola codebase. Non affrontano la deriva tra servizi né validano che il modello dell'architettura corrisponda al codice.

Valutazione assistita da LLM

Thoughtworks ha inserito la riduzione della deriva architetturale con gli LLM nell'anello Assess del Technology Radar Vol. 34 (aprile 2026). Vale la pena citare come inquadrano il problema, perché non arriva da un vendor:

Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.

In italiano: l'uso crescente di agenti di coding IA può accelerare la deriva rispetto alla codebase e ai design architetturali previsti. Senza controllo, questa deriva si aggrava man mano che agenti e persone replicano i pattern esistenti, compresi quelli degradati, creando un ciclo di feedback in cui il codice scadente genera codice ancora peggiore.

La tecnica che descrivono affianca strumenti di analisi deterministici (nominano Spectral, ArchUnit e Spring Modulith) alla valutazione con LLM, per intercettare violazioni semantiche che un motore di regole non sa esprimere, e usa poi l'LLM per aiutare a correggere ciò che ha trovato. I loro team l'hanno applicata alle linee guida di qualità delle API e alla definizione di zone architetturali che guidano le modifiche generate dagli agenti.

Due delle loro lezioni valgono la pena a prescindere dallo strumento che usi. Una prima scansione fa emergere più violazioni di quante chiunque ne triagerà, quindi la prioritizzazione è il lavoro vero. E la correzione di un agente ha bisogno di un proprio ciclo di verifica, perché "ha cambiato il codice" e "ha migliorato il sistema" sono affermazioni diverse.

Assess è l'anello di Thoughtworks che significa "vale la pena guardarlo, non lo raccomandiamo ancora". Trattalo così. Quello che stabilisce è che il problema è abbastanza reale perché una grande società di consulenza lo metta per iscritto, il che è più di quanto la maggior parte degli argomenti sulla deriva possa indicare.

Drift scoring automatizzato

Questo è l'approccio di Archyl. Invece di verificare regole specifiche, valida l'intero modello dell'architettura contro la codebase:

Ogni sistema documentato corrisponde a un repository?
Ogni container documentato corrisponde a una directory nella codebase?
Ogni elemento di codice documentato fa riferimento a un file che esiste ancora?
Entrambe le estremità di ogni relazione documentata sono ancora valide?

Il risultato è un punteggio da 0 a 100 e un dettaglio per elemento di cosa corrisponde, cosa è documentato ma è sparito, e cosa esiste nel codice ma non è mai stato scritto da nessuna parte. Dove le fitness function verificano i vincoli che ti sei ricordato di scrivere, questo verifica l'intero modello che hai già.

Le decisioni di progettazione chiave nel rilevamento della deriva di Archyl:

Leggero. Nessuna chiamata IA e nessun contenuto di file scaricato. Una sola richiesta ricorsiva dell'albero al tuo provider Git, poi corrispondenza di percorsi e nomi rispetto al modello. Il calcolo richiede secondi.

Deterministico. Stessa codebase, stesso modello, stesso punteggio. Nessuna variabilità dovuta alla temperatura dell'LLM o al prompt engineering.

Economico. Eseguilo a ogni push senza preoccuparti dei costi. Cento calcoli al giorno vanno benissimo.

Azionabile. Il dettaglio nomina quali elementi sono andati in deriva, così sai cosa correggere.

Il compromesso sta nel primo punto. Verificare percorsi e nomi invece di leggere il codice rende il punteggio veloce, gratuito e riproducibile, e significa che la verifica è strutturale. Vede un container la cui directory non c'è più e un elemento di codice il cui file è stato cancellato. Non vede la chiamata REST diventata messaggio di coda mentre entrambi i servizi hanno mantenuto i loro nomi. Quella è deriva comportamentale, l'unico tipo nella tassonomia in cima a questa guida che nessuna verifica economica intercetta. Review manuale e valutazione con LLM sono ciò che hai a disposizione per quello.

Come si calcola il drift score, in dettaglio copre la formula, cosa viene escluso dal denominatore e perché, e il resto dei limiti.

Chiudere il ciclo

Il rilevamento da solo non cambia nulla. Un punteggio che qualcuno calcola una volta e guarda è un audit, non un ciclo di feedback. Tre meccanismi lo trasformano in un ciclo, più una distinzione da mettere a fuoco prima di cablare qualunque di essi. Le pratiche di workflow che gli stanno accanto -- architecture as code, la documentazione nella definition of done, l'adozione di regole di conformance -- sono l'argomento di documentazione architetturale vivente.

Automatizzare il rilevamento della deriva in CI

Il meccanismo con più denti è un gate CI che fallisce quando la deriva supera una soglia, perché è l'unico che blocca un merge:

on:
  push:
    branches: [main]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          threshold: '70'

Quando la build fallisce perché il drift score è sceso, qualcuno deve sistemarlo prima di mergiare. L'accuratezza della documentazione diventa non negoziabile quanto i test che passano.

Imposta la soglia sotto il tuo punteggio attuale, non al numero che vorresti avere. Un gate che fallisce alla prima esecuzione viene disattivato alla prima esecuzione. Alzalo man mano che il team costruisce l'abitudine.

Impostare alert sulla deriva

Archyl supporta alert via webhook per gli eventi di deriva:

drift.score_computed: si attiva a ogni calcolo della deriva. Pubblicalo su un canale Slack per dare visibilità.
drift.score_degraded: si attiva quando il punteggio scende di 10+ punti. Questo è il tuo sistema di allerta precoce.

Configura questi alert verso un canale che il tuo team monitora. La consapevolezza è il primo passo verso l'azione.

Fare review dell'architettura

Le review dell'architettura mensili o trimestrali servono a più scopi:

Validare che l'architettura documentata corrisponda ancora alla realtà
Individuare la deriva che gli strumenti automatizzati hanno mancato (quella comportamentale, per esempio)
Discutere se i component andati in deriva vadano aggiornati nel codice o nella documentazione
Rivedere e aggiornare gli ADR per decisioni che potrebbero dover essere riconsiderate

Non confondere deriva e conformance

Vengono eseguiti insieme abbastanza spesso da meritare una distinzione, perché si calcolano in modo diverso e falliscono per ragioni diverse.

Il rilevamento della deriva chiede se il tuo modello corrisponde alla realtà. Confronta l'architettura documentata con il repository e produce un punteggio.

Le regole di conformance chiedono se la realtà segue le tue regole: il container frontend non deve dipendere dal container del database, ogni API pubblica passa dal gateway, ogni servizio possiede il proprio database. Un controllo di conformance può passare su un modello che è andato pesantemente in deriva, e un modello perfettamente accurato può violare tutte le regole che hai.

Vuoi entrambe le cose, e non dovresti leggere un numero come se fosse l'altro.

Deriva architetturale vs. erosione architetturale

Questi termini sono correlati ma distinti:

La deriva architetturale è la divergenza tra documentazione e implementazione. Il codice potrebbe essere perfettamente a posto -- è la documentazione a essere sbagliata.

L'erosione architetturale è il degrado dell'architettura stessa. Il codice viola i principi architetturali, accumula debito tecnico e diventa più difficile da mantenere. L'erosione è un problema di qualità del codice. La deriva è un problema di accuratezza della documentazione.

Perry e Wolf tracciavano la linea in un punto diverso nel 1992: per loro entrambe erano proprietà del sistema anziché della documentazione, con l'erosione causata dal violare l'architettura e la deriva causata dall'essere insensibili a essa. L'uso moderno è più lasco e più utile a un team che lavora, ma se leggi la letteratura accademica sull'erosione architetturale, aspettati che i termini si collochino diversamente da qui.

Spesso coesistono. Quando la documentazione va in deriva, i team perdono consapevolezza dell'architettura prevista. Senza quella consapevolezza, fanno modifiche che erodono l'architettura. La deriva abilita l'erosione.

Ecco perché il rilevamento della deriva conta al di là della sola accuratezza della documentazione. Una documentazione accurata funge da riferimento che previene l'erosione. Quando tutti possono vedere l'architettura prevista, è più probabile che la mantengano.

Misurare e monitorare la deriva nel tempo

Un singolo drift score è utile. Un trend è potente.

Stabilire una baseline

Esegui il primo calcolo prima di cambiare qualsiasi cosa nel modo in cui il team lavora. Qualunque cosa restituisca è la tua baseline, e un primo numero basso è un'informazione, non un verdetto. Una documentazione che nessuno è mai stato incaricato di mantenere non ha fallito; semplicemente non era mai stata misurata.

Resisti alla tentazione di sistemare le cose prima della prima esecuzione. Vuoi il numero che descrive la situazione in cui ti trovi davvero, non quello che ottieni dopo un weekend di pulizie.

Seguire il trend

Un punteggio isolato è un fatto su oggi. Il trend è ciò che ti dice se qualcosa che hai cambiato ha funzionato:

La deriva sta migliorando o peggiorando nel tempo?
Uno sprint o una release specifici hanno causato un calo?
La soglia CI sta tenendo la linea, o la stanno abbassando tutti?

Archyl memorizza ogni calcolo con il suo dettaglio completo, così un report storico può essere riaperto e confrontato elemento per elemento. Qualunque strumento tu usi, conserva lo storico. Un drift score che ricalcoli da zero ogni trimestre e poi butti via è di nuovo un audit.

Fissa un obiettivo che puoi davvero tenere

Scegli il numero successivo invece di quello ideale. Se oggi sei a 58, l'obiettivo utile è 65 e la conversazione utile riguarda quali cinque elementi ti ci portano. Un team che si accorda per arrivare al 90% entro fine trimestre di solito non si accorda su niente.

Il ruolo del rilevamento della deriva nello sviluppo assistito dall'IA

Questa è la parte cambiata più di recente, ed è il motivo per cui Thoughtworks ha scritto la voce citata prima: gli agenti replicano i pattern che trovano, quelli degradati inclusi, quindi la deriva che una volta si accumulava alla velocità dei commit umani ora si accumula alla velocità di quelli generati.

Gli agenti IA si affidano sempre più alla documentazione dell'architettura per il contesto. Attraverso protocolli come MCP, gli agenti possono leggere il tuo modello C4, gli ADR e le regole di conformance prima di generare codice. Questo li rende più efficaci -- generano codice che si adatta alla tua architettura invece di tirare a indovinare.

Ma funziona solo se la documentazione è accurata. Un agente che legge un modello C4 obsoleto e genera codice basandosi su di esso produrrà codice che si adatta all'architettura sbagliata. L'agente amplifica la deriva invece di prevenirla.

Il rilevamento della deriva crea il ciclo di feedback che tiene onesti gli agenti IA:

L'agente legge l'architettura via MCP
L'agente genera codice che si adatta all'architettura documentata
Il codice viene mergiato, cambiando potenzialmente l'architettura reale
Il rilevamento della deriva viene eseguito e intercetta qualsiasi divergenza
Il gate CI fallisce se la deriva supera la soglia
Il team aggiorna la documentazione per riflettere la realtà
L'agente legge l'architettura aggiornata -- il ciclo si chiude

Senza il passo 4, il ciclo è aperto. La documentazione diventa sempre più fittizia. Gli agenti generano sempre più codice che si adatta a un'architettura di fantasia. Lo scarto si allarga a ogni commit.

Il rilevamento della deriva è il meccanismo che chiude questo ciclo.

Iniziare con il rilevamento della deriva

Se hai già un modello da qualche parte

Misuralo prima di cambiare qualsiasi altra cosa. È la prima mossa meno costosa a disposizione e non ti impegna a nulla.

Se la tua architettura vive già in Structurizr DSL, LikeC4, IcePanel o in un catalogo Backstage, porta quel modello dentro e calcola un punteggio su di esso così com'è. Stai misurando la documentazione che hai già scritto, nello stato in cui l'hai lasciata. Nessun cambio di workflow, nessuna nuova abitudine per il team, nessuna decisione sul tooling per ora. Il numero è l'input di quella decisione, non il suo risultato.

Due avvertenze oneste. Gli importatori non sono lossless: viste, stili e layout non sopravvivono, e il parser Structurizr salta gli ambienti e i nodi di deployment, ma li nomina con il numero di riga nella sua lista di avvisi, quindi leggi quella lista e il modello importato prima di fidarti del denominatore. E il punteggio descrive il modello che è arrivato, non il file che hai esportato.

Quello che torna indietro è un elenco per elemento. Un punteggio di 84 è un problema di manutenzione che puoi pianificare. Un punteggio di 41 significa che le decisioni sono state prese contro un documento che descrive un altro sistema, ed è meglio scoprirlo adesso che durante il prossimo incidente.

Se non hai documentazione dell'architettura

Parti dalla discovery IA. Collega un repository, lascia che la discovery proponga il modello C4, e approva o rifiuta ciò che suggerisce invece di disegnarlo. Una volta che c'è un modello, il rilevamento della deriva è ciò che lo tiene onesto.

Se stai già monitorando la deriva

Mettilo in CI. Imposta una soglia sotto il tuo punteggio attuale. Configura l'alert di degrado. Rendi la deriva una metrica che il team vede ogni settimana, non un numero che una persona calcola prima di una review.

Da qualunque punto tu parta

La deriva si accumula come il debito tecnico: più la lasci lì, più ce n'è da riconciliare, e meno qualcuno si fida del documento nel frattempo. La differenza è che puoi scoprire a che punto sei oggi senza sistemare niente prima.

La tua documentazione dell'architettura o riflette la realtà o non la riflette. Il senso di un drift score è che non devi più tirare a indovinare quale delle due.

Per approfondire: come si calcola il drift score per il meccanismo, documentazione architetturale vivente per le pratiche che mantengono vero un modello, e cos'è il modello C4 se parti da zero. Definizioni: l'architecture drift, la documentazione vivente e il rilevamento della deriva nel prodotto. Il piano Developer è gratuito e non richiede carta, se vuoi mettere un numero sulla documentazione che hai già: archyl.com.

Rilevamento della deriva architetturale: mantieni il codice allineato al design - Archyl Blog