Architecture Drift Score: la tua documentazione dice la verita?
C'e un segreto sporco nell'architettura software: la maggior parte della documentazione e sbagliata.
Non sbagliata come "contiene errori". Sbagliata come "descrive un sistema che non esiste piu". Il diagramma mostra un microservizio che e stato fuso con un altro sei mesi fa. Il modello C4 elenca una cache Redis che e stata sostituita da Memcached durante un incidente nel weekend. Il diagramma dei componenti fa riferimento a un PaymentGateway rinominato in BillingService durante un refactoring di cui nessuno ha informato l'architetto.
Non e un problema di disciplina. E un problema strutturale. Il codice cambia continuamente. La documentazione cambia quando qualcuno se ne ricorda. Il divario tra realta e documentazione -- quello che chiamiamo deriva architetturale -- cresce silenziosamente fino a quando il diagramma appeso al muro non ha piu alcuna somiglianza con il sistema in produzione.
Abbiamo costruito il Drift Score per rendere questo divario visibile, misurabile e azionabile.
Un singolo numero: da 0 a 100
L'Architecture Drift Score risponde a una domanda: quale percentuale della tua architettura documentata esiste effettivamente nella tua codebase?
Apri un progetto qualsiasi in Archyl, clicca sull'icona del battito cardiaco nell'intestazione e premi "Compute Drift Score". In pochi secondi, vedrai un numero tra 0 e 100:
- 90-100% -- Eccellente. La tua documentazione corrisponde fedelmente alla codebase.
- 70-89% -- Buono. Per lo piu accurata, alcuni divari da colmare.
- 50-69% -- Discreto. Deriva significativa rilevata. E ora di aggiornare.
- Sotto il 50% -- La tua documentazione e finzione.
Tutto qui. Nessun lungo rapporto da leggere. Nessuna valutazione soggettiva. Un numero che puoi tracciare, analizzare e imporre.
Cosa viene realmente verificato
L'analisi della deriva e leggera per design: una singola chiamata API al tuo provider git, nessuna IA, nessun contenuto di file recuperato. Valida la tua architettura su cinque dimensioni:
Systems -- Il nome del tuo repository corrisponde al sistema documentato? Usiamo la stessa convenzione di denominazione PascalCase della pipeline di discovery IA, con corrispondenza fuzzy in modo che EkoAuthz corrisponda a un repository chiamato authz.
Containers -- Le directory di primo livello nel tuo repository corrispondono ai container documentati? frontend/ corrisponde a FrontendWebApp. backend/ corrisponde a BackendApiServer. I container di infrastruttura (database, code, monitoraggio) che non hanno directory sorgente sono correttamente esclusi: sono documentazione valida di servizi esterni, non deriva.
Components -- I componenti sotto ogni container sono ancora validi? Se la directory del container padre esiste, i suoi componenti sono presunti validi. Se la directory del container e scomparsa, tutti i suoi componenti vengono segnalati.
Code Elements -- Questo e il controllo piu preciso. Ogni elemento di codice nel tuo modello C4 ha un filePath. Verifichiamo che ogni file esista ancora nel repository. File rinominato? Classe eliminata? Modulo spostato? Il drift score lo rileva istantaneamente.
Relationships -- Una relazione e valida se sia l'elemento sorgente che quello di destinazione hanno superato la validazione. Se uno dei due endpoint ha subito deriva, la relazione viene segnalata.
Il risultato e una scomposizione per elemento che mostra esattamente cosa corrisponde, cosa manca e cosa e nuovo: non un punteggio opaco, ma un rapporto azionabile.
Perche la leggerezza conta
Abbiamo deliberatamente scelto di non eseguire la pipeline completa di discovery IA per il rilevamento della deriva. Ecco perche:
Velocita. L'analisi IA richiede minuti per repository grandi. Il calcolo del drift score richiede secondi. Puoi eseguirlo a ogni push senza rallentare la tua pipeline.
Determinismo. L'IA puo produrre risultati diversi sulla stessa codebase a seconda della temperatura del modello, delle variazioni dei prompt e dei limiti di token. L'esistenza di un percorso file e binaria: o il file c'e o non c'e. Il tuo punteggio e riproducibile.
Costo. Nessun token IA consumato. Nessun limite di frequenza API raggiunto. Eseguilo cento volte al giorno se vuoi.
Semplicita. L'algoritmo e auditabile. Verificare percorsi file, abbinare nomi di directory, validare relazioni. Nessuna scatola nera.
Traccia le tendenze, non solo le istantanee
Un singolo punteggio e utile. Una tendenza e potente.
Ogni calcolo di deriva viene memorizzato con la sua scomposizione completa. La scheda Overview mostra un grafico a barre del tuo punteggio nel tempo. Clicca su qualsiasi barra per caricare quel rapporto storico e vedere esattamente cosa e cambiato.
Questo trasforma il drift scoring da un audit una tantum a una metrica di salute continua. Puoi vedere:
- Il refactoring della scorsa settimana ha migliorato o peggiorato la precisione della documentazione?
- La deriva peggiora nel tempo? (Spoiler: senza automazione, succede sempre.)
- Quale sprint ha introdotto il maggior numero di modifiche non documentate?
Applicalo nella CI
Una metrica che non applichi e una metrica che ignorerai. Per questo abbiamo costruito una GitHub Action.
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'
Imposta threshold: '70' e l'action fallisce se la precisione della tua documentazione architetturale scende sotto il 70%. Il riepilogo del job mostra una tabella formattata con la scomposizione completa, visibile direttamente nei check della tua PR.
Puoi anche pubblicare il punteggio come commento alla PR:
- uses: archyl-com/actions/drift-score@v1
id: drift
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
organization-id: ${{ secrets.ARCHYL_ORG_ID }}
project-id: 'your-project-uuid'
- uses: actions/github-script@v7
if: github.event_name == 'pull_request'
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '## Architecture Drift: ' +
'${{ steps.drift.outputs.score }}%\n' +
'Matched: ${{ steps.drift.outputs.matched-count }}' +
' / ${{ steps.drift.outputs.total-elements }}'
})
Ogni sviluppatore vede l'impatto della deriva delle proprie modifiche prima del merge. La documentazione architetturale diventa un cittadino di prima classe nella tua pipeline CI, accanto a test, linting e scansioni di sicurezza.
MCP: agenti IA che conoscono la propria precisione
Se usi Claude Code, Cursor o qualsiasi agente IA compatibile con MCP insieme al server MCP di Archyl, il drift scoring e disponibile come strumento:
compute_drift_score({ projectId: "..." })
get_drift_score({ projectId: "..." })
get_drift_history({ projectId: "..." })
get_drift_details({ scoreId: "..." })
Questo significa che un agente IA puo verificare la precisione della documentazione prima di iniziare a lavorare. Lo strumento get_agent_context fornisce gia il modello C4 completo, gli ADR e le regole di conformita. Ora puo anche verificare quanto sia affidabile quella documentazione.
Un agente che vede un drift score del 45% sa che deve essere cauto con il contesto architetturale ricevuto. Un agente che vede il 95% puo fare affidamento con sicurezza sulla struttura documentata. Questa e la base per agenti IA autoconsapevoli che adattano il proprio comportamento in base alla qualita della documentazione.
Avvisi webhook: sapere quando si verifica la deriva
Due nuovi eventi webhook ti tengono informato senza dover controllare le dashboard:
drift.score_computed-- Si attiva ogni volta che un drift score termina il calcolo. Invialo a un canale Slack per visibilita.drift.score_degraded-- Si attiva quando il punteggio scende di 10 o piu punti rispetto al calcolo precedente. Questo e il tuo sistema di allerta precoce: l'architettura sta derivando velocemente.
Configura questi eventi nelle impostazioni webhook di Archyl. Funzionano con Slack, Microsoft Teams, Discord e qualsiasi endpoint HTTP generico.
La REST API
Per i team che desiderano un controllo programmatico completo:
# Avviare il calcolo
curl -X POST https://api.archyl.com/api/v1/drift/compute \
-H "X-API-Key: $API_KEY" \
-H "X-Organization-ID: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{"projectId": "your-project-uuid"}'
# Ottenere l'ultimo punteggio
curl https://api.archyl.com/api/v1/drift/latest?projectId=...
# Ottenere lo storico dei punteggi
curl https://api.archyl.com/api/v1/drift/history?projectId=...&limit=20
Il calcolo e asincrono: il POST ritorna immediatamente con un ID del punteggio, e fai polling fino a quando status diventa completed. La GitHub Action gestisce questo automaticamente.
Cosa significa per l'era agentica
Stiamo entrando in un'era in cui gli agenti IA scrivono una porzione significativa del codice di produzione. Questi agenti sono veloci, capaci e ciechi al contesto. Non sanno che AuthService e stato diviso in IdentityService e AccessControl il mese scorso. Non sanno che la directory frontend/ e stata rinominata in web/.
Il drift score crea un ciclo di feedback:
- L'agente IA legge il modello C4 via MCP prima di scrivere codice.
- Le modifiche al codice avvengono (da parte di umani o agenti).
- Il drift score rileva il divario tra documentazione e realta.
- Il gate CI impedisce al divario di crescere oltre una soglia.
- Il webhook avvisa il team quando la deriva accelera.
- Il team aggiorna la documentazione (o esegue una discovery per aggiornarla automaticamente).
- L'agente IA legge il modello aggiornato. Il ciclo si chiude.
Senza il passo 3, il ciclo e aperto. La documentazione deriva. Gli agenti si basano su un contesto obsoleto. Le cattive decisioni si accumulano.
Il drift score chiude il ciclo.
Per iniziare
- Apri un progetto qualsiasi in Archyl
- Clicca sull'icona del battito cardiaco nella barra degli strumenti dell'intestazione
- Clicca su "Compute Drift Score"
- Configura la GitHub Action per il monitoraggio continuo
- Configura un webhook Slack per gli avvisi
drift.score_degraded
La tua documentazione architetturale riflette la realta oppure no. Ora hai un numero che ti dice quale delle due e.