Come diagnosticare una configurazione di Claude Code che non funziona

Hai aggiunto una regola a CLAUDE.md. Claude modifica ancora il file vietato. La reazione più comune è riscrivere la regola in maiuscolo, duplicarla nelle impostazioni e aggiungere un hook. Ora hai tre configurazioni e ancora nessuna prova di quale sia stata caricata.

La diagnosi parte dall'ambiente effettivo, non dal file che ricordi di aver modificato. La guida ufficiale di Claude Code mette a disposizione comandi distinti per contesto, memoria, Skill, hook, MCP, permessi, salute e sorgenti delle impostazioni.

Usali in ordine. Prima presenza, poi sorgente, precedenza, stato e infine comportamento. Saltare il primo passaggio trasforma ogni correzione in un'ipotesi.

Prima prova che il file sia stato caricato

Un file esistente sul disco non è necessariamente nel contesto della sessione. Potrebbe trovarsi nello scope sbagliato, avere un nome non riconosciuto o essere legato a una sottocartella che Claude non ha ancora letto.

Esegui /context nella sessione in cui osservi il problema. Cerca la categoria pertinente e la sorgente indicata. Se il file o la Skill non compare, non giudicare ancora la qualità dell'istruzione. Devi prima capire perché non è entrata.

La documentazione segnala un caso facile da fraintendere: i file CLAUDE.md nelle sottocartelle vengono caricati quando Claude legge un file in quell'area, non necessariamente all'avvio. Aprire una sessione nella root e controllare subito può quindi dare un risultato diverso da quello osservato durante il lavoro sul modulo.

Scrivi atteso e osservato

«La configurazione non funziona» contiene troppi problemi possibili. Scrivi due righe verificabili.

Atteso: dopo una modifica ai file Markdown parte il controllo lingua.
Osservato: il file cambia, ma /hooks non mostra un handler per quell'evento.

Oppure:

Atteso: il server MCP espone i tool di lettura del progetto.
Osservato: /mcp mostra il server connesso e zero tool.

Il primo caso riguarda caricamento o matcher. Il secondo riguarda ciò che il server restituisce dopo la connessione. Senza questa distinzione rischi di modificare il prompt per correggere un problema di configurazione.

Controlla il contesto effettivo

/context mostra le categorie che occupano la finestra: istruzioni, messaggi, file letti, Skill, agenti personalizzati e tool MCP, con le fonti disponibili. Usalo come indice, non come verdetto finale.

Tre esiti richiedono azioni diverse:

Salva una schermata o una nota testuale con sessione, directory di avvio e sorgente mostrata. Cambiare directory può cambiare il set di file e impostazioni applicati.

Ispeziona la categoria giusta

Dal quadro generale passa al comando specifico:

• /memory mostra le fonti di memoria e il relativo scope;

• /skills elenca le Skill disponibili da progetto, utente e plugin;

• /hooks mostra le configurazioni attive;

• /mcp mostra server, stato e tool;

• /permissions mostra le regole risolte;

• /status elenca le sorgenti di impostazione attive;

• /doctor controlla installazione e file di configurazione;

• /debug [problema] attiva log mirati per la sessione.

Non lanciarli tutti e poi cercare una frase sospetta. Scegli la categoria legata all'atteso. Se un hook non parte, servono configurazione attiva, evento e matcher. Se una Skill non compare, servono sorgente e struttura. Se un tool MCP manca, servono stato del server e lista restituita.

claude doctor dal terminale offre una diagnosi in sola lettura senza avviare una sessione. /doctor dentro la sessione può proporre correzioni e chiede prima di applicarle. Anche qui, osservazione e modifica sono due passaggi distinti.

Trova la sorgente e la precedenza

Claude Code può leggere impostazioni personali, condivise dal progetto, locali al progetto e gestite dall'organizzazione. La documentazione sulle impostazioni spiega che la sorgente determina chi e quali progetti ricevono la chiave.

Se la stessa chiave compare in più scope, non scegliere il file che ti sembra più vicino. Usa /status e la reference della precedenza per capire quale valore è effettivo. Le impostazioni gestite, per esempio, non vengono normalmente superate da una preferenza locale.

Controlla anche la superficie. Terminale, VS Code e app desktop sulla stessa macchina leggono molte fonti comuni. Una sessione cloud vive altrove e non eredita automaticamente ogni file locale.

Distingui configurazione valida da servizio disponibile

Un server MCP può essere definito correttamente e fallire all'avvio. Può risultare connesso e non restituire tool. Un hook può essere caricato, ma non corrispondere all'evento osservato. Una Skill può comparire nell'elenco e non attivarsi perché la descrizione non corrisponde al lavoro.

Scrivi una catena di evidenze:

Definito: il file contiene la voce attesa.
Caricato: il comando diagnostico mostra la sorgente.
Attivo: il componente espone stato o matcher corretto.
Invocato: il caso di prova lo attiva.
Esito: l'output coincide con il contratto.

Fermati al primo anello mancante. Correggere gli anelli successivi prima di quello produce configurazioni più complesse e nessuna informazione nuova.

Riduci a una configurazione minima

Riproduci il problema in una directory di prova o con una copia controllata dei soli file necessari. Non cancellare la configurazione funzionante e non modificare una policy gestita. Lo scopo è sottrarre variabili, non ripartire alla cieca.

Per una Skill bastano descrizione, un input piccolo e un output osservabile. Per un hook usa un evento e un comando senza effetti. Per MCP prova un solo server e una lettura innocua. Per le istruzioni scegli una regola concreta, come il nome di un file di output, e verifica se cambia la decisione.

Il test di sottrazione rimuove una fonte alla volta dalla copia di prova. Se il comportamento cambia quando escludi l'override locale, hai isolato una precedenza. Se resta identico, torna alla catena di caricamento.

Correggi una causa, non un sintomo

Una volta isolato il primo anello mancante, applica una sola variazione. Sposta il file nella posizione corretta, correggi il JSON invalido, restringi il matcher o riscrivi l'istruzione con quando, azione e prova.

Esegui di nuovo lo stesso caso. Non cambiare input insieme alla configurazione: perderesti il confronto. Registra fonte prima, variazione, evidenza dopo e modo per tornare indietro.

La procedura di controllo delle modifiche nei workflow AI serve proprio a conservare questo legame. Se il problema ha interrotto un processo reale, aggiungilo anche al registro degli incidenti AI con causa confermata, non con la prima supposizione.

Non trasformare ogni limite in configurazione

Una regola può essere caricata e restare troppo vaga. «Fai attenzione ai file importanti» richiede un'interpretazione. «Non modificare generated/; cambia la sorgente sotto content/ e rigenera» nomina confine e alternativa.

Un'istruzione non è il livello giusto per tutto. I divieti che devono essere applicati richiedono permessi o hook. Le azioni su account esterni richiedono autorità, anche se il tool è connesso. La diagnosi è completa quando hai trovato il livello corretto, non quando hai ottenuto una risposta conforme una volta.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi portare una configurazione reale, osservare ciò che Claude ha caricato e costruire un caso di prova ripetibile. Il risultato utile non è aggiungere un'altra regola. È sapere quale sorgente governa il comportamento e come dimostrarlo.