Claude Config Audit: manutenzione della configurazione

Chi usa Claude con regolarità tende a fare sempre la stessa cosa, aggiungere. Un server MCP per la ricerca web, uno per i PDF, uno per il filesystem. Poi le skill, prima quelle dei plugin, poi quelle costruite su misura. Le istruzioni nel prompt di sistema crescono di paragrafo in paragrafo, distribuite tra User Preferences e CLAUDE.md senza una strategia chiara. I plugin del marketplace si accumulano, alcuni attivati per curiosità e mai più toccati.

Il meccanismo è naturale e comprensibile, con ogni singola aggiunta che aveva un senso nel momento in cui è stata fatta. Il problema è che spesso ci si dimentica di verificare l’insieme, si aggiunge ma non si rimuove, si installa ma non si disinstalla, si scrive un’istruzione ma non si controlla se ne esiste già una equivalente altrove.

Il risultato è una configurazione che cresce senza governo. Server MCP che forniscono la stessa funzionalità, plugin di setup rimasti attivi dopo l’onboarding iniziale, skill locali superate da versioni più recenti, istruzioni duplicate tra prompt di sistema e preferenze utente, talvolta in conflitto tra loro, file di memoria che riferiscono a progetti abbandonati mesi prima.

Questo tipo di accumulo non produce errori espliciti. Claude non si blocca, non mostra messaggi di errore, non rifiuta di rispondere. Ma ogni server MCP consuma RAM (tipicamente 40-50 MB per un processo Node.js, fino a 200-500 MB per un container Docker), ogni istruzione duplicata spreca token del contesto, e le istruzioni in conflitto tra loro degradano la qualità delle risposte in modi difficili da diagnosticare. È un problema invisibile, ed è proprio per questo che tende a peggiorare nel tempo.

Ho sviluppato una skill che affronta sistematicamente questo problema. Si chiama Claude Config Audit ed è disponibile come progetto open source.

Cosa controlla Claude Config Audit

La skill esegue un audit della configurazione su sei aree distinte, ma il suo valore reale sta nel fatto che non le tratta come compartimenti separati. Ogni controllo tiene conto delle relazioni tra gli strati perché un’istruzione nel prompt di sistema ha senso solo se lo strumento a cui si riferisce esiste ancora, una skill è utile solo se i server MCP da cui dipende sono configurati, un permesso è valido solo se il tool che menziona è ancora installato.

Server MCP. Il primo controllo riguarda i duplicati funzionali. Non si tratta di server identici, ma di server diversi che coprono la stessa area, ad esempio due strumenti di ricerca web, due lettori PDF di cui uno è un sottoinsieme dell’altro, un server di ragionamento strutturato che replica capacità già native in Claude Opus e Sonnet. La skill mantiene una mappa aggiornata delle sovrapposizioni note e la confronta con la configurazione dell’utente. Per ogni server individua anche il tipo di installazione e stima l’impatto sulle risorse, un processo Node.js locale occupa circa 40-50 MB di RAM, un’installazione via npx aggiunge latenza di avvio, un container Docker può arrivare a 200-500 MB. Vengono segnalati anche i server che dipendono da servizi esterni non attivi o disinstallati.

Plugin. Il controllo si concentra su tre situazioni ricorrenti. La prima è la duplicazione tra marketplace, lo stesso plugin installato da due fonti diverse. La seconda è la sovrapposizione tra plugin e skill locali, un caso frequente quando si installa un plugin generico dal marketplace e poi si costruisce una skill personalizzata che copre lo stesso ambito ma in modo più mirato. La terza sono i plugin di setup e onboarding rimasti attivi dopo la configurazione iniziale, che occupano spazio nel contesto senza fornire più alcun valore.

Skill. L’analisi della directory delle skill cerca anomalie strutturali, file orfani (archivi .zip, cartelle di backup, file senza il SKILL.md richiesto), versioni superate che coesistono con la versione corrente (una skill e la sua variante «-v2» o «-agentic»), sovrapposizioni con le skill generiche distribuite dai plugin. Ma il controllo non si ferma alla struttura della directory. La skill verifica anche che ogni skill locale abbia ancora i presupposti per funzionare, controlla se una skill fa riferimento a un server MCP che non è più presente nella configurazione, il problema non è la skill in sé ma la coerenza tra gli strati.

Prompt di sistema. Questa è probabilmente l’area dove l’accumulo produce gli effetti meno visibili e più insidiosi. La skill confronta il contenuto delle User Preferences con quello del CLAUDE.md cercando sovrapposizioni (paragrafi con similarità superiore al 70%), contraddizioni tra i due livelli, e istruzioni che fanno riferimento a strumenti o skill non più presenti nella configurazione. Sui progetti lo stesso tipo di analisi si estende ai prompt di progetto, cercando istruzioni duplicate tra progetti diversi e regole che avrebbero più senso come istruzioni globali. L’audit stima anche il costo in token dell’intero prompt di sistema, un dato utile perché quei token vengono consumati a ogni singola interazione.

Hook e permessi (solo per chi usa Claude Code, sia da terminale sia dall’app Desktop). La skill verifica la presenza di hook duplicati sullo stesso evento, hook che riferiscono a script inesistenti sul sistema, permessi troppo ampi (accesso shell senza restrizioni) e regole stantie che menzionano tool di server MCP rimossi. Un permesso che autorizza l’uso di un tool specifico di un server disinstallato mesi prima non crea problemi evidenti, ma è un segnale che la configurazione non viene manutenuta.

File di memoria (anche questi specifici di Claude Code, in entrambe le modalità). L’analisi individua file di memoria non aggiornati da oltre tre mesi, file orfani non indicizzati nel MEMORY.md, indici che superano la soglia di 200 righe oltre la quale il sistema tronca il contenuto, e directory di memoria associate a progetti che non esistono più sul disco. Quest’ultimo caso è un esempio tipico di incoerenza cross-layer: il progetto è stato rimosso o spostato, ma i file di memoria continuano a occupare spazio e potenzialmente a confondere il contesto.

Il risultato è un’analisi che non si limita a fotografare ogni strato in isolamento. La configurazione di Claude è un sistema con dipendenze tra i suoi componenti, e i problemi più difficili da individuare manualmente sono proprio quelli che nascono dall’interazione tra strati diversi: il prompt che parla di uno strumento rimosso, la skill che orchestra un server assente, il permesso che autorizza un tool fantasma.

Come funziona il processo

L’audit segue un workflow in sei fasi progettato per essere conservativo, la skill non rimuove nulla autonomamente e non applica modifiche senza conferma esplicita.

La prima fase è la raccolta dei dati. La skill rileva automaticamente la piattaforma su cui sta operando e le risorse a cui può accedere: se ha un tool di accesso al filesystem (Desktop Commander, filesystem MCP o gli strumenti nativi di Claude Code) legge direttamente i file di configurazione dalla macchina dell’utente. Se lavora in un ambiente senza accesso al filesystem (come claude.ai) analizza il contesto di sessione, che include comunque la lista dei server MCP collegati, le skill disponibili e il contenuto del prompt di sistema, e chiede all’utente di fornire eventuali file di configurazione che non riesce a raggiungere da sola.

La seconda fase è l’analisi vera e propria, con i controlli descritti nella sezione precedente applicati a tutto il materiale raccolto.

La terza fase produce un report strutturato che riassume lo stato corrente (quanti server, quanti plugin, quante skill, quanti token di prompt), elenca i problemi trovati raggruppati per gravità, propone azioni correttive con il razionale per ciascuna, e identifica le domande che richiedono l’input dell’utente.

La quarta fase è quella più importante: la validazione interattiva. La skill presenta ogni raccomandazione e chiede conferma prima di procedere. Questo passaggio non è un dettaglio implementativo ma una scelta progettuale precisa. L’analisi automatica individua i potenziali problemi, ma solo l’utente sa se quel server MCP che sembra inutilizzato viene in realtà attivato una volta al mese per un compito specifico, o se quel plugin apparentemente ridondante è mantenuto per compatibilità con un flusso di lavoro non ovvio.

La quinta fase applica le modifiche approvate, sempre con backup preventivo di ogni file toccato. Le modifiche vengono eseguite una categoria alla volta (prima i server MCP, poi i plugin, poi il prompt, poi le skill) con verifica dopo ogni passaggio. Ciò che non può essere fatto automaticamente (come le modifiche alle User Preferences su claude.ai, accessibili solo dall’interfaccia) viene documentato con istruzioni dettagliate per l’intervento manuale.

La sesta fase è un report finale che documenta tutto ciò che è stato fatto, tutto ciò che resta da fare manualmente, l’impatto stimato delle modifiche e le istruzioni per ripristinare lo stato precedente dai backup.

Compatibilità multi-piattaforma

La skill funziona su tutte le interfacce Claude, ma è importante capire cosa riesce a vedere da ciascuna. Le configurazioni locali (Desktop e Code) sono reciprocamente visibili da qualsiasi piattaforma locale con accesso al filesystem. La configurazione di claude.ai resta accessibile solo da claude.ai.

Su claude.ai la skill lavora con il contesto di sessione: analizza i connettori MCP, le skill del progetto, i prompt di progetto e le istruzioni personalizzate dell’utente. Non può accedere ai file locali, quindi le configurazioni di Desktop e Code restano fuori dall’audit. Se l’utente le vuole includere, deve fornire manualmente i file di configurazione.

Su Claude Desktop (Chat, Cowork o Code) la situazione cambia se è presente un tool di accesso al filesystem come Desktop Commander. In quel caso la skill può leggere sia il claude_desktop_config.json (server MCP di Desktop, comuni a Chat, Cowork e Code) sia il settings.json di Claude Code da terminale (server MCP, hook, permessi, plugin). Sono tutti file locali sulla stessa macchina, quindi l’audit li copre entrambi. Ciò che non raggiunge è la configurazione server-side di claude.ai: i progetti, i connettori, le skill caricate nei progetti.

Su Claude Code da terminale vale la stessa logica speculare: la skill accede alla propria configurazione (settings.json con hook, permessi, plugin, CLAUDE.md globale e di progetto, directory delle skill, file di memoria) e può leggere anche il claude_desktop_config.json di Desktop. Anche qui la configurazione di claude.ai resta inaccessibile.

In ogni caso il report dichiara esplicitamente quali piattaforme sono state analizzate. Un utente che usa sia claude.ai sia Desktop dovrebbe eseguire l’audit da entrambi per avere un quadro completo.

A chi serve

Il profilo più immediato è quello di chi ha personalizzato Claude nel tempo senza mai fermarsi a verificare l’insieme. Chi ha installato diversi server MCP in momenti diversi, aggiunto plugin per provarli senza poi disattivarli, scritto istruzioni nel prompt di sistema in modo incrementale senza rileggerle come documento unico. È una situazione comune perché Claude invita naturalmente a questo tipo di accumulo, ogni aggiunta produce un beneficio visibile, e nulla segnala che l’insieme sta diventando incoerente.

Ma la skill è utile anche in situazioni meno ovvie. Chi usa Claude su più piattaforme (claude.ai per la chat, Desktop per il lavoro con i file, Code per lo sviluppo) ha di fatto configurazioni parallele che possono divergere nel tempo. L’audit cross-platform permette di tenere allineato l’insieme.

Chi lavora in team può usare la skill per verificare che la configurazione condivisa (settings a livello di progetto, server MCP comuni, hook standardizzati) sia coerente con quella individuale di ciascun membro.

E anche chi è all’inizio del percorso di personalizzazione può usarla come strumento di verifica preventiva, per partire con una configurazione pulita anziché ereditare ridondanze fin dal primo giorno.

Dove trovarla

Claude Config Audit è disponibile come progetto open source su GitHub a questo indirizzo. L’installazione consiste nel copiare una cartella nella posizione giusta sul proprio computer. Ci sono due modi per farlo.

Metodo 1: scaricare l’archivio zip. Dalla pagina del repository su GitHub, si clicca il pulsante verde «Code» e poi «Download ZIP». Si estrae l’archivio scaricato e al suo interno si trova la cartella claude-config-audit con il file SKILL.md e la sottocartella reference. Questa cartella va copiata nella directory delle skill locali di Claude:

• su macOS e Linux: ~/.claude/skills/
• su Windows: C:\Users\[nome utente]\.claude\skills\

Se la cartella skills non esiste ancora, la si crea.

Metodo 2: clonare il repository con Git. Chi ha familiarità con Git può clonare direttamente il repository nella directory delle skill:

• su macOS e Linux: cd ~/.claude/skills && git clone https://github.com/paolodalprato/claude-config-audit
• su Windows: cd %USERPROFILE%\.claude\skills && git clone https://github.com/paolodalprato/claude-config-audit

Il vantaggio di questo metodo è che gli aggiornamenti futuri si possono scaricare con un semplice git pull.

Una volta che la cartella è in posizione, la skill viene riconosciuta automaticamente. Per eseguire l’audit è sufficiente chiedere a Claude qualcosa come «controlla la mia configurazione» o «esegui un audit del mio setup».

Chi trova utile la skill o vuole contribuire a migliorarla è benvenuto nel repository. I pattern di analisi (le sovrapposizioni note tra server MCP, le strutture valide delle skill, le stime di consumo risorse) sono documentati in file di riferimento separati e possono essere estesi dalla comunità man mano che l’ecosistema Claude si arricchisce di nuovi componenti.