Audit configurazione agenti AI: perché CLAUDE.md e AGENTS.md invecchiano

Un agente AI che funzionava benissimo a marzo può dare risposte peggiori ad agosto senza che nessuno abbia toccato una riga di codice. Non è un guasto: è il modo normale in cui invecchiano le istruzioni che gli abbiamo dato. La manutenzione agenti AI in produzione è il lavoro, poco raccontato e quasi mai pianificato, che tiene in vita quella configurazione mentre tutto il resto si muove sotto di essa: i modelli migliorano, gli harness aggiungono funzioni, il codebase cambia. A giugno 2026 uno studio su cento progetti open source ha messo dei numeri su un problema che chiunque gestisca agenti AI conosce per esperienza. Vale la pena guardarli.

In questo articolo scoprirai:

• L’emivita di una configurazione: perché le istruzioni scritte a marzo non reggono ad agosto
• Il 91% dei repository ha almeno un difetto di configurazione: cosa dice la ricerca
• Cosa controllare in un audit della configurazione (e ogni quanto)
• Non basta ripulire il file: il contesto si degrada anche quando è corretto
• Chi tiene in vita l’agente dopo il go-live: il servizio, non solo il prodotto

L’emivita di una configurazione: perché le istruzioni scritte a marzo non reggono ad agosto

Addy Osmani, engineering leader in Google Chrome, la chiama «half-life», emivita. La sua formulazione è secca: «i modelli migliorano, gli harness aggiungono capacità, i codebase cambiano, e le istruzioni che abbiamo scritto per una versione precedente restano indietro». Il punto non è che la configurazione si rompa. È che smette silenziosamente di essere vera, e nessuno se ne accorge perché l’agente continua a rispondere.

Il meccanismo di decadimento è quasi sempre lo stesso, ed è additivo. L’agente sbaglia, qualcuno aggiunge una regola. Sbaglia di nuovo, un’altra regola. Nessuno toglie mai niente, perché togliere richiede di verificare, e verificare costa tempo. Dopo sei mesi il file di istruzioni è il sedimento di tutti gli incidenti passati, compresi quelli che il modello nuovo non commetterebbe più.

Il dato che rende evidente lo spreco arriva da Anthropic stessa, e lo riprende l’audit di Osmani: per i modelli più recenti ha rimosso oltre l’80% del system prompt di Claude Code «senza perdite misurabili nelle valutazioni interne sul codice». Otto istruzioni su dieci erano diventate zavorra, scritte per compensare limiti di modelli precedenti, mantenute per inerzia. Se succede a chi costruisce il modello, succede a maggior ragione a un team che ha messo in produzione un agente l’anno scorso e da allora ha solo aggiunto righe. Chi lavora su Claude in azienda incontra questo scarto ogni volta che cambia versione del modello.

Il 91% dei repository ha almeno un difetto di configurazione: cosa dice la ricerca

A giugno 2026 un gruppo di ricercatori dell’Università Federale di Minas Gerais e dell’Istituto Federale di Minas Gerais ha pubblicato Configuration Smells in AGENTS.md Files, analizzando i 100 progetti open source più stellati su GitHub dotati di un file AGENTS.md (39) o CLAUDE.md (61). Il risultato principale: 91 repository su 100 presentano almeno un difetto di configurazione. Non progetti amatoriali, i più popolari su GitHub.

Gli autori isolano sei «smell», e le prevalenze dicono dove si annida davvero lo spreco:

• Lint leakage (62%): regole già garantite da linter e formatter, ripetute a parole all’agente.
• Context bloat (42%): file oltre le 200 righe, la soglia raccomandata da Anthropic.
• Skill leakage (35%): procedure usate di rado, caricate però in ogni singola sessione.
• Conflicting instructions (28%): direttive che si contraddicono fra loro.
• Init fossilization (24%): file generato automaticamente all’avvio e mai più aggiornato.
• Blind references (16%): rimandi a documenti esterni senza spiegare quando servono.

Il dettaglio più interessante è l’interazione: secondo i ricercatori, skill leakage e istruzioni contraddittorie aumentano dell’83% la probabilità di context bloat. I difetti non sono indipendenti, si alimentano. E il costo è doppio: il lint leakage «gonfia la dimensione del contesto e spreca token», distraendo il modello da ciò che conta davvero, vincoli architetturali, regole di dominio, policy di sicurezza. Si paga di più per ottenere di peggio.

Cosa controllare in un audit della configurazione (e ogni quanto)

La documentazione ufficiale di Claude Code è esplicita su un punto che molti team leggono come consiglio estetico e invece è operativo: «file più corti producono un’aderenza migliore», con target sotto le 200 righe per file. Ma un audit serio non è solo una potatura: è una sequenza di controlli ripetibili.

Le tre domande a cui ogni istruzione deve rispondere

Primo: è ancora vera? Un comando di build cambiato, un percorso rinominato, una convenzione abbandonata rendono l’istruzione peggiore del silenzio. Secondo: serve in ogni sessione? Se riguarda un solo sottosistema, va spostata in una regola con ambito ristretto o in una skill caricata su richiesta. Terzo: è già garantita altrove? Se un linter la applica, ripeterla all’agente è puro costo in token. Osmani lo sintetizza così: «installare una skill utile e tenerla per sempre sono due decisioni diverse».

La cadenza dell’audit e il test di rimozione

La frequenza suggerita è ogni poche settimane, al massimo un mese: abbastanza spesso da intercettare il decadimento, abbastanza raro da non diventare burocrazia. Il criterio con cui si taglia è quello: via ciò che l’agente può dedurre dal codice, si conservano insidie, convenzioni anomale e motivazioni. La memoria automatica va rivista a parte, con /memory: può conservare preferenze stantie anche quando i file di progetto sono già puliti. Infine il controllo che nessuno fa: disattivare una skill e verificare se la qualità peggiora davvero. Se non peggiora, la risposta è arrivata. Lo stesso rigore che si applica a una prompt library aziendale vale qui, con in più il fatto che questi file girano in produzione.

Non basta ripulire il file: il contesto si degrada anche quando è corretto

C’è un secondo livello, e riguarda il funzionamento del modello. Anthropic documenta il context rot: «all’aumentare del numero di token nella finestra di contesto, la capacità del modello di richiamare accuratamente le informazioni diminuisce». Il fenomeno si presenta su tutti i modelli, con intensità diverse. Ogni token consumato da un’istruzione morta è attenzione sottratta al problema reale, non una spesa neutra.

La conseguenza pratica è che un file di configurazione perfettamente aggiornato ma lungo resta comunque un problema. La raccomandazione di Anthropic è cercare l’«altitudine giusta»: abbastanza specifico da guidare il comportamento, abbastanza flessibile da restare una buona euristica, evitando sia la logica fragile e iper-dettagliata sia le indicazioni vaghe che non danno segnale. È lo stesso equilibrio che governa il prompt engineering, applicato però a qualcosa che gira ogni giorno senza supervisione.

Google Cloud aggiunge il pezzo mancante, quello misurabile: «la valutazione di un agente si concentra sulle traiettorie, l’intera sequenza di decisioni e azioni che l’agente compie per arrivare a un risultato, non solo la risposta finale». Tradotto: senza osservabilità sulle traiettorie non si può sapere se un audit ha migliorato o peggiorato le cose. Prima si stabilisce cosa si misura, poi si tocca la configurazione. Vale anche per i guardrail, che invecchiano esattamente come le istruzioni che accompagnano.

Chi tiene in vita l’agente dopo il go-live: il servizio, non solo il prodotto

Tutto questo descrive un mestiere, non un’operazione occasionale. Un agente in produzione senza nessuno che ne rivede periodicamente la configurazione si degrada, non con un errore visibile, ma con una lenta perdita di qualità che il team attribuisce al modello, al prompt, alla sfortuna. È esattamente il punto in cui un prodotto AI si distingue da un servizio AI: il primo consegna un agente che funziona il giorno della demo, il secondo si assume il decadimento.

La posta in gioco non è solo la qualità delle risposte. Gartner prevede che oltre il 40% dei progetti di AI agentica sarà cancellato entro la fine del 2027, per costi fuori controllo, valore di business poco chiaro o gestione del rischio inadeguata. Il decadimento della configurazione non è l’unica causa, ma è quella che agisce più lentamente: quando il costo per risposta sale e la qualità scende, il progetto diventa indifendibile alla prima revisione di budget.

Cosa mettere a calendario: l’audit della configurazione dopo il go-live

In MIMIR è la parte dell’onboarding che tende a sorprendere i clienti: il go-live non è la fine del lavoro. La manutenzione post-deployment mette a calendario l’audit della configurazione, il controllo dei conflitti fra istruzioni, la revisione della memoria e il test di rimozione delle skill inutilizzate, e li lega a KPI osservati su una dashboard invece che a impressioni. Quando l’agente passa al team interno, l’handover e la formazione trasferiscono anche questa disciplina, perché è quella che decide se fra un anno l’agente varrà ancora quello che costa.

Audit della configurazione: cosa scrivere nel contratto col partner

Cosa entri esattamente in questo perimetro è materia di contratto con il partner, e conviene definirlo prima, non dopo il primo calo di qualità: cadenza dell’audit, chi lo esegue, quali metriche fanno scattare un intervento fuori calendario.

Se state valutando un agente AI per la vostra azienda, o ne avete già uno in produzione che rende meno di sei mesi fa, la domanda giusta non è quale modello usare: è chi si occupa della configurazione quando il modello cambia. Su questo MIMIR lavora tutti i giorni, e una consulenza iniziale serve proprio a capire se il problema è il modello o l’impalcatura che gli sta intorno.

Fonti:

• Addy Osmani — Audit your agent files (emivita delle configurazioni e test di rimozione)
• Configuration Smells in AGENTS.md Files — studio su 100 repository GitHub (arXiv)
• The Register — Smelly config files will make your agents waste tokens
• InfoWorld — AI coding agents may be getting bad instructions from smelly config files
• Anthropic — Claude Code: gestione della memoria e dei file di istruzioni
• Anthropic Engineering — Effective context engineering for AI agents (context rot, altitudine giusta)
• Google Cloud — A developer’s guide to production-ready AI agents (valutazione delle traiettorie)
• Gartner — Oltre il 40% dei progetti di AI agentica sarà cancellato entro fine 2027