I tuoi agenti IA hanno un file di regole. Non hanno un modello del tuo sistema.

Apri il CLAUDE.md, l'AGENTS.md o il .cursor/rules alla radice del tuo repository e leggilo come arriva a un agente: come un unico blocco di testo, senza niente dentro che segnali quali righe siano ancora vere.

La maggior parte di quello che trovi sono convenzioni. Usa i tab. Niente any. Ritorna presto. Wrappa gli errori con %w. Quelle righe sono durevoli, perché descrivono come si scrive una riga di codice, e l'agente le applica al codice che ha davanti.

Poi c'è l'altro tipo di riga. Quella che descrive il tuo sistema: quali servizi esistono, quale package possiede cosa, come è permesso alle layer di parlarsi. Sono quelle righe a rendere il file degno di esistere, e sono quelle che marciscono.

Lo so, perché il nostro l'ha fatto.

Cosa è invecchiato nel nostro

Il repository di Archyl ha un CLAUDE.md alla radice. Per gli standard del genere è uno buono: 422 righe, un albero dell'architettura, le variabili di configurazione, il cablaggio della dependency injection, una descrizione della pipeline di discovery. Ogni agente che tocca questa codebase lo legge prima di fare qualunque altra cosa.

Ecco cosa diceva la mattina in cui ho scritto questo pezzo, il 5 agosto 2026. Riga 392:

No test suite: The codebase currently has no Go test files or frontend tests.

Nessuna test suite: la codebase al momento non ha file di test Go né test frontend.

Ci sono 146 file _test.go sotto backend/ e 31 file di test sotto frontend/src/.

La riga 140 dice:

AI Provider Abstraction: Supports both OpenAI and Ollama via ai.Provider interface.

Astrazione del provider IA: supporta sia OpenAI sia Ollama tramite l'interfaccia ai.Provider.

backend/internal/adapter/ai/resolver.go instrada verso OpenAI, Anthropic, Gemini, Bedrock e qualunque endpoint compatibile con OpenAI, oltre al percorso OpenAI e Ollama gestito dalla piattaforma. Cinque tipi di provider in un solo switch. Il file ne nomina due.

E l'albero dell'architettura, alle righe da 74 a 87, elenca undici package sotto internal/domain/: c4, project, user, team, adr, projectdoc, flow, insight, subscription, dependency, history. Oggi in internal/domain/ ci sono quarantuno directory. Tra le trenta che non menziona: conformance, drift, apicontract, marketplace, reality, managedagent, mcpsession. Vale a dire, gran parte di quello che il prodotto è diventato da quando il file è stato scritto.

Ognuna di quelle righe era vera il giorno in cui è stata digitata. Nessuna è stata corretta dopo, perché correggerle richiede che una persona se ne accorga, e non c'era niente a sorvegliare.

Questa è un'azienda che vende documentazione di architettura. Se la disciplina fosse la soluzione, qui avrebbe funzionato.

Le due metà di quel file non hanno niente in comune

La metà delle convenzioni è verificabile in modo automatico. "Niente fmt.Println in Go" è un grep. "I file Go devono essere in snake_case" è uno script. Se un agente ne viola una, un linter lo dice in CI. Se cambia la convenzione stessa, il linter comincia a fallire e qualcuno aggiorna il file. C'è un ciclo di feedback, ed è abbastanza corto da funzionare.

La metà del sistema non ha un equivalente. Non esiste nessun go vet per "il servizio di pagamento non può accedere direttamente al database". Niente fa il parsing di quella frase, niente la confronta con il repository, niente fallisce quando smette di corrispondere. È prosa in un file markdown, e la prosa non ha una modalità di fallimento.

Quindi un file di regole sono due documenti che condividono un nome di file. Uno è verificato di continuo, l'altro non è verificato mai, e niente nel file li distingue. "Wrappa gli errori con %w" e "la codebase non ha test" stanno nella stessa lista, con la stessa voce. Una è una regola sul codice che l'agente ha davanti. L'altra è un'affermazione su 146 file che non sta guardando.

L'assenza è la metà più difficile

L'invecchiamento è il fallimento che tutti riescono a immaginare. Quello più silenzioso conta di più: un file di regole contiene solo ciò che a qualcuno è venuto in mente di scrivere, e niente al suo interno distingue "questo non esiste" da "nessuno l'ha nominato".

Il nostro non menziona mai internal/adapter/marketplace/. Quel package contiene un'interfaccia di provider e otto adapter: GitHub, GitLab, Argo CD, Datadog, Prometheus, Sentry, SonarQube, PagerDuty. L'elenco degli adapter in CLAUDE.md si ferma a git, ai, stripe, email, osv e registry. Niente di quello che il file dice del marketplace è sbagliato. Il file non ne ha uno.

Non ho fatto l'esperimento di chiedere a un agente di aggiungere una nona integrazione, e non ho intenzione di dirti cosa produrrebbe, perché mi inventerei il risultato. Quello che posso dirti è che sulla mappa non c'è nessun marketplace, e che questa è la condizione ordinaria di ogni file di regole che ho letto, compresi quelli che ho scritto io.

Un modello non ha quella proprietà. Puoi chiedere a un modello cosa esiste e ottenere una risposta che significa qualcosa, perché la risposta è una query su un insieme invece che una ricerca dentro della prosa. "Cosa parla con il servizio di pagamento" è una domanda a cui un grafo può rispondere e un paragrafo no.

Le due risposte ovvie, e perché nessuna delle due regge

Scrivi un file di regole migliore. Più lungo, più curato, con una checkbox nel template della pull request. I team lo fanno, e per qualche settimana funziona. Non tiene, per una ragione che non ha a che fare con la disciplina: ogni riga che descrive il sistema è una copia in cache di qualcosa che vive altrove, e le cache hanno bisogno di invalidazione. Qui l'invalidazione è un essere umano che se ne accorge. È tutto qui il meccanismo, ed è lo stesso che negli ultimi vent'anni avrebbe dovuto tenere accurati i diagrammi di architettura. Sappiamo com'è andata; la guida al rilevamento del drift è la versione lunga di questo argomento.

Lascia che l'agente legga il repository. Può farlo, e per una domanda su un singolo file dovrebbe. Ma leggere il codice non ti dice quali confini fossero deliberati. L'interfaccia davanti a un servizio ha esattamente lo stesso aspetto sia che stia lì per una decisione presa due anni fa dopo un incident, sia perché a qualcuno piacciono le interfacce. L'intenzione non è recuperabile dall'artefatto che ne è risultato. È per questo che il file di regole esiste, prima di tutto, ed è per questo che nemmeno cancellarlo è la risposta.

Qualcuno fuori da questa azienda ha notato la stessa cosa

Thoughtworks ha messo "Architecture drift reduction with LLMs" nell'anello Assess del Technology Radar Vol. 34, pubblicato ad aprile 2026. La loro apertura:

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.

L'uso crescente di agenti di coding IA può accelerare lo scostamento dalla codebase e dai design di architettura previsti. Lasciato senza controllo, questo drift si accumula man mano che agenti ed esseri umani replicano i pattern esistenti, compresi quelli degradati, creando un ciclo di feedback in cui il codice scadente genera codice ancora più scadente.

Assess, nella definizione del radar stesso, significa "worth exploring with the goal of understanding how it will affect your enterprise" — vale la pena esplorarlo con l'obiettivo di capire come influenzerà la tua azienda. Non è una raccomandazione di nulla, e di sicuro non di noi. È una nota che dice che alcuni dei loro team lo stanno provando e che è presto.

La parte utile è la forma che descrivono: strumenti di analisi deterministica (citano Spectral, ArchUnit e Spring Modulith) combinati con la valutazione tramite LLM, perché la struttura è controllabile da un programma e l'intenzione no. Anche la lezione che riportano vale la pena rubarla: la prima scansione fa emergere più violazioni di quante chiunque abbia voglia di smistare.

Nota cosa non c'è in quella ricetta. La risposta di nessuno al drift accelerato dagli agenti è un file markdown più lungo.

Cosa dovrebbe fare l'artefatto

Due proprietà. Nessuna delle due è esotica.

Deve enumerare. Dovresti poter chiedere cosa esiste e ricevere l'insieme, non il ricordo che qualcuno ne ha. Il che significa un artefatto che interroghi invece di leggerlo, e la differenza si vede nel modo più duro proprio sulle domande che nessuno ha messo per iscritto.

Deve essere falsificabile. Qualcosa deve confrontarlo con il codice e segnalare quali parti hanno smesso di essere vere, con una cadenza che non sia "quando un essere umano se ne accorge". ArchUnit lo fa per le regole di layer in Java. dependency-cruiser lo fa per gli import JavaScript. Entrambi sono volutamente ristretti, ed entrambi centrano il punto: l'artefatto che vale la pena avere è quello con cui un programma può essere in disaccordo.

Un file di regole fallisce su entrambe. Non enumera, e niente può contraddirlo.

Dove siamo, e cosa non posso dirti

Archyl mantiene un modello C4 del tuo sistema: sistemi, container, componenti, relazioni, generati dal repository dalla discovery con AI e approvati da una persona invece che disegnati da una persona. Quel modello è la metà enumerabile, e gli agenti ci arrivano tramite MCP, l'equivalente di 181 tool, così un agente chiede cosa esiste invece di sperare che qualcuno l'abbia scritto. La metà delle convenzioni è un catalogo di conformance: 169 regole distribuite su 23 tecnologie nominate più un set agnostico rispetto al linguaggio, controlli deterministici invece di prosa. E il modello viene ricontrollato contro il codice e valutato con un punteggio, che è la proprietà di falsificabilità.

Avere un server MCP non è la parte interessante, e chiunque te ne venda uno come elemento differenziante ti sta vendendo una presa elettrica. Structurizr ne offre uno e quello di IcePanel è in beta aperta. La domanda su cui vale la pena discutere è se la cosa dietro la presa sia mantenuta, perché un endpoint che serve un modello invecchiato a marzo è solo un modo più veloce di sbagliare.

Penso che sia questa la differenza che conta. Non posso dimostrarlo. Nessuno ha misurato se un agente che lavora a partire da un modello mantenuto scriva codice meglio conformato di un agente che lavora a partire da un file di regole curato, e finché qualcuno non lo farà, quella frase è un'affermazione su un meccanismo, non un risultato. Tienila così, e ribatti a chiunque la enunci in modo più netto di come l'ho appena enunciata io.

C'è anche una piega onesta, qui. Archyl genera un file di regole. Il tool MCP get_agent_context restituisce l'architettura come un briefing in markdown che puoi committare nel tuo repository, il che è un file di regole con un altro nome. Il file non è mai stato il problema. Il problema era che dietro non c'era niente, quindi niente poteva rigenerarlo. Un file di regole che è la cache di un modello mantenuto va benissimo. Un file di regole che è l'unica copia è un'istantanea di quello che una persona credeva in un pomeriggio.

La versione da cinque minuti, che non ti costa niente

Ignora tutto quello che c'è sopra e fai invece questo.

Apri il tuo file di regole. Vai riga per riga e marca ognuna o come convenzione, cioè dice all'agente come scrivere codice, o come affermazione, cioè dice all'agente qualcosa sul tuo sistema. Poi, per ogni affermazione, scrivi cosa ti direbbe che ha smesso di essere vera.

La mia previsione è che arriverai in fondo al file con la seconda colonna vuota. È lì lo scarto. Cosa farne è una decisione a parte, e per vederlo non devi comprare niente.

Il nostro ha richiesto qualche minuto e ha tirato fuori tre righe sbagliate. Sistemarle è un commit, e non cambia niente di strutturale: la prossima riga invecchierà allo stesso modo, e nemmeno su quella c'è qualcosa a sorvegliare.