SpyBara
Go Premium

debug-your-config.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 2 additions and 2 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Esegui il debug della tua configurazione

Diagnostica perché CLAUDE.md, impostazioni, hooks, server MCP o skills non hanno effetto. Usa /context, /doctor, /hooks e /mcp per vedere cosa è stato effettivamente caricato.

Quando Claude ignora un'istruzione o una funzione che hai configurato non appare, la causa è solitamente che il file non è stato caricato, è stato caricato da una posizione diversa da quella prevista, o un altro file l'ha sovrascritto. Questa guida mostra come ispezionare cosa Claude Code ha effettivamente caricato in modo da poter restringere quale situazione si applica.

Per problemi di installazione, autenticazione e connettività, consulta invece Troubleshooting installation and login.

Vedi cosa è stato caricato nel contesto

Il comando /context mostra tutto ciò che occupa la finestra di contesto per la sessione corrente, suddiviso per categoria: prompt di sistema, strumenti di sistema, strumenti MCP, subagenti personalizzati con la fonte da cui ciascuno è stato caricato, file di memoria, skills e messaggi di conversazione. Eseguilo per primo per confermare se i tuoi CLAUDE.md, regole o descrizioni di skill sono presenti. La sezione skills in /context include anche skills raggruppate, che /skills non elenca.

Per dettagli su una categoria specifica, segui con il comando dedicato:

Comando Mostra
/memory Posizioni dei file di memoria negli ambiti utente e progetto con l'opzione di aprire ciascuno nel tuo editor, più accesso alla cartella di memoria automatica e l'interruttore di memoria automatica
/skills Skills disponibili da fonti di progetto, utente e plugin
/hooks Configurazioni di hook attive
/mcp Server MCP connessi e il loro stato
/permissions Regole di consentimento e negazione risolte attualmente in vigore
/doctor Diagnostica della configurazione: salute dell'installazione, file di impostazioni non validi, estensioni inutilizzate, nomi di subagent duplicati nella stessa directory, e contenuto CLAUDE.md archiviato che Claude può derivare dalla base di codice, con correzioni proposte
/debug [issue] Abilita la registrazione del debug per la sessione e richiede a Claude di diagnosticare utilizzando l'output del log e i percorsi delle impostazioni
/status Fonti di impostazioni attive, incluso se le impostazioni gestite sono in vigore

Se un file di memoria manca dalla suddivisione /context, controlla la sua posizione rispetto a come i file CLAUDE.md si caricano. I file CLAUDE.md della sottodirectory si caricano su richiesta quando Claude legge un file in quella directory con lo strumento Read, non all'inizio della sessione.

Se /context conferma che il file è stato caricato ma Claude ancora non segue una particolare istruzione, il problema è probabilmente come l'istruzione è scritta piuttosto che se è stata caricata. CLAUDE.md funziona bene per il tipo di guida che daresti a un nuovo collega, come convenzioni di progetto, comandi di compilazione e dove appartengono i file.

L'aderenza diminuisce quando un'istruzione è abbastanza vaga da poter essere interpretata in più modi, quando due file danno indicazioni conflittuali, o quando il file è cresciuto abbastanza che le singole regole ricevono meno attenzione. Scrivi istruzioni efficaci copre i modelli di specificità, dimensione e struttura che mantengono l'aderenza alta.

Controlla le impostazioni risolte

Le impostazioni si uniscono tra gli ambiti gestiti, utente, progetto e locale. Le impostazioni gestite si applicano per prime quando presenti. Tra il resto, l'ambito più vicino sostituisce quello più ampio nell'ordine locale, poi progetto, poi utente. Alcune impostazioni possono anche essere impostate da flag della riga di comando o variabili di ambiente, che agiscono come un altro livello di override. Quando un'impostazione non sembra applicarsi, il valore che hai impostato è solitamente sovrascritto da un altro ambito o da una variabile di ambiente.

Per trovare file di impostazioni non validi, esegui claude doctor dal tuo terminale. Stampa diagnostica di installazione e impostazioni di sola lettura senza avviare una sessione. Per un controllo completo che propone anche correzioni e chiede prima di applicarle, esegui /doctor all'interno di una sessione.

Esegui /status per vedere quali fonti di impostazioni sono attive, incluso se le impostazioni gestite sono in vigore. Per capire quale ambito Claude Code utilizza per una data chiave, vedi Precedenza delle impostazioni.

Controlla i server MCP

Esegui /mcp per vedere ogni server configurato, il suo stato di connessione e se l'hai approvato per il progetto corrente. Un server può essere definito correttamente ma comunque non fornire strumenti per alcuni motivi comuni:

  • I server con ambito di progetto in .mcp.json richiedono un'approvazione una tantum. Se il prompt è stato chiuso, il server rimane disabilitato fino a quando non lo approvi da /mcp.
  • Un server che non riesce ad avviarsi appare come non riuscito in /mcp. I percorsi di file relativi in command o args sono una causa frequente, poiché si risolvono rispetto alla directory da cui hai lanciato Claude Code piuttosto che alla posizione di .mcp.json.
  • Un server che appare come connesso ma elenca zero strumenti si è avviato correttamente ma non sta restituendo un elenco di strumenti. Seleziona Reconnect da /mcp. Se il conteggio rimane a zero, esegui claude --debug=mcp e leggi lo stderr del server nel log di debug in ~/.claude/debug/<session-id>.txt.

Per i percorsi di configurazione e le regole di ambito, vedi MCP.

Controlla gli hooks

Esegui /hooks per elencare ogni hook registrato per la sessione corrente, raggruppato per evento. Se un hook che hai definito non appare, non viene letto: gli hooks vanno sotto la chiave "hooks" in un file di impostazioni, non in un file autonomo.

Se l'hook appare ma non si attiva, il matcher è la causa usuale. Controllalo per questi errori:

  • Il campo matcher è una singola stringa che usa | per corrispondere a più nomi di strumenti, ad esempio "Edit|Write". Un separatore , è equivalente, quindi "Edit,Write" corrisponde agli stessi strumenti. Prima della v2.1.191, una virgola passava alla valutazione regex e il matcher non corrispondeva mai, quindi usa | se non sei ancora su v2.1.191.
  • Un nome di strumento scritto male produce un matcher che non corrisponde a nulla, quindi l'hook fallisce silenziosamente.
  • Un valore di array è un errore di schema: Claude Code mostra un avviso di errore di impostazioni e rifiuta l'intero file di impostazioni utente, progetto o locale, claude doctor segnala l'errore di convalida e nessun hook da quel file appare in /hooks. Nelle impostazioni gestite, Claude Code elimina l'intera chiave hooks dal file che contiene l'array, quindi nessuno degli hook di quel file si applica. Le altre impostazioni del file si applicano ancora e claude doctor elenca la chiave eliminata.

Quando modifichi settings.json, la modifica ha effetto nella sessione in esecuzione dopo un breve ritardo di stabilità del file, anche se crei il file o la cartella .claude/ del progetto stesso dopo l'avvio della sessione. Non è necessario riavviare. Prima della v2.1.257, Claude Code non rilevava le modifiche in una cartella .claude/ creata dopo l'avvio della sessione.

Se /hooks mostra ancora la definizione precedente alcuni secondi dopo il salvataggio, esegui /hooks di nuovo per aggiornare la visualizzazione.

Se /hooks mostra l'hook ma comunque non si attiva, il passo successivo è guardare la valutazione dell'hook dal vivo. Avvia una sessione con claude --debug e attiva la chiamata dello strumento. Il log di debug registra ogni evento, quali matcher sono stati controllati e il codice di uscita e l'output dell'hook. Vedi Debug hooks per il formato del log e troubleshooting degli hooks per i modelli di errore comuni.

Prova con una configurazione pulita

Inizia con claude --safe-mode, che avvia una sessione con tutte le personalizzazioni disabilitate, inclusi CLAUDE.md, skills, plugins, hooks, server MCP e comandi e agenti personalizzati. L'autenticazione, la selezione del modello, gli strumenti integrati e le autorizzazioni funzionano normalmente. Se il problema scompare in modalità sicura, una di quelle superfici è la causa; usa i controlli mirati sopra per trovare quale. La modalità sicura applica comunque gli hooks gestiti e la policy delle impostazioni dalla vostra organizzazione. I plugin gestiti, gli skills, CLAUDE.md e i server MCP sono disattivati.

Se il problema persiste in modalità sicura, o le tue impostazioni stesse sono sospette, confronta con una sessione che non carica nulla dalla tua configurazione usuale. Punta CLAUDE_CONFIG_DIR a una directory vuota per bypassare tutto sotto ~/.claude, e avvia da una directory che non ha una cartella .claude, .mcp.json o CLAUDE.md in modo che la configurazione del progetto sia anche saltata.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

La sessione pulita non ha impostazioni utente o progetto, hooks, server MCP, plugin o memoria. Al primo avvio, aspettati le schermate di configurazione iniziale, a partire dalla selezione del tema. Se le vedi, la directory di configurazione pulita è in vigore. Gli avvii successivi con la stessa directory saltano queste schermate perché Claude Code salva lo stato dell'onboarding lì.

  • Le impostazioni gestite si applicano comunque se la tua organizzazione le distribuisce. Claude Code legge i profili MDM, la policy del registro e managed-settings.json da posizioni al di fuori della directory di configurazione, e recupera le impostazioni gestite dal server di nuovo per la sessione pulita una volta che ha le credenziali
  • Ti verrà chiesto di accedere di nuovo

Se il problema scompare qui, la causa è da qualche parte nei tuoi veri file ~/.claude o progetto .claude. Reintroducili uno alla volta, copiando i file nella directory temporanea o avviando dal tuo progetto, per trovare quale. Se persiste nella sessione pulita, la causa è al di fuori della tua configurazione utente e progetto. Esegui /status per verificare se le impostazioni gestite sono in vigore, cerca variabili di ambiente che influenzano Claude Code, quindi vedi Risoluzione dei problemi.

Controlla le cause comuni

La maggior parte delle sorprese di configurazione risale a un piccolo insieme di regole di posizione e sintassi. Controlla questi prima di assumere un bug:

Sintomo Causa Soluzione
Hook non si attiva mai matcher è un array JSON invece di una stringa Usa una singola stringa con | per corrispondere a più strumenti, ad esempio "Edit|Write". Vedi matcher patterns.
Hook non si attiva mai matcher utilizza , come separatore su una versione precedente a v2.1.191 Claude Code v2.1.191 o successivo tratta , come separatore di elenco come |. Le versioni precedenti valutano una virgola come carattere letterale, quindi "Edit,Write" non corrisponde a nulla. Usa | invece, o aggiorna Claude Code.
Hook non si attiva mai Il valore di matcher è minuscolo, ad esempio "bash" La corrispondenza è sensibile alle maiuscole. I nomi degli strumenti sono capitalizzati: Bash, Edit, Write, Read.
Hook non si attiva mai Gli hooks sono definiti in un file autonomo invece di settings.json Non esiste un file di hooks autonomo per la configurazione del progetto o dell'utente. Definisci gli hooks sotto la chiave "hooks" in settings.json. Solo i plugins caricano un file separato hooks/hooks.json. Vedi hook configuration.
Permissions, hooks o env impostati globalmente vengono ignorati La configurazione è stata aggiunta a ~/.claude.json ~/.claude.json contiene lo stato dell'app e gli interruttori dell'interfaccia utente. permissions, hooks e env appartengono a ~/.claude/settings.json. Questi sono due file diversi.
Un valore di settings.json sembra ignorato La stessa chiave è impostata in settings.local.json settings.local.json sostituisce settings.json, e entrambi sostituiscono ~/.claude/settings.json. Vedi settings precedence.
Skill non appare in /skills Il file di skill è in .claude/skills/name.md invece che in una cartella Usa una cartella con SKILL.md dentro: .claude/skills/name/SKILL.md.
Skill appare in /skills ma Claude non la invoca mai Skill ha disable-model-invocation: true nel suo frontmatter, o la sua descrizione non corrisponde a come formuli la richiesta Controlla il badge in /skills: un'etichetta "user-only" significa che Claude non la attiverà da sola. Vedi skill invocation.
Le istruzioni di CLAUDE.md della sottodirectory sembrano ignorate I file della sottodirectory si caricano su richiesta, non all'inizio della sessione Si caricano quando Claude legge un file in quella directory con lo strumento Read, non al lancio e non quando scrive o crea file lì. Vedi come i file CLAUDE.md si caricano.
Subagent ignora le istruzioni di CLAUDE.md Gli agenti Explore e Plan incorporati saltano CLAUDE.md. I subagenti personalizzati lo caricano nello stesso modo in cui la conversazione principale lo fa, a meno che la sua definizione non imposti omitClaudeMd Per Explore o Plan, ripeti l'istruzione nel tuo prompt di delega. Per un subagente che imposta omitClaudeMd, rimuovi il campo. Per qualsiasi altro subagente personalizzato, metti le istruzioni critiche nel corpo del file dell'agente, che diventa il prompt di sistema dell'agente. Vedi cosa si carica all'avvio.
La logica di pulizia non viene mai eseguita alla fine della sessione Nessun hook SessionEnd configurato Aggiungi un hook SessionEnd in settings.json. Vedi l'elenco degli eventi di hook.
I server MCP in .mcp.json non si caricano mai Il file è sotto .claude/, o i suoi server si trovano sotto una chiave servers di livello superiore, come nel file mcp.json di VS Code, invece di mcpServers La configurazione MCP del progetto va alla radice del repository come .mcp.json, non dentro .claude/, con server sotto la chiave mcpServers. Vedi MCP configuration.
Server MCP aggiunti sotto mcpServers in settings.json non appaiono mai settings.json non legge una chiave mcpServers Definisci i server del progetto in .mcp.json alla radice del repository, o esegui claude mcp add --scope user per i server con ambito utente. Vedi MCP configuration.
Server MCP del progetto aggiunto ma non appare Il prompt di approvazione una tantum è stato chiuso I server con ambito di progetto richiedono approvazione. Esegui /mcp per vedere lo stato e approvare.
Il server MCP non riesce ad avviarsi da alcune directory command o args utilizza un percorso di file relativo Usa percorsi assoluti per gli script locali. Gli eseguibili sul tuo PATH come npx o uvx funzionano così come sono.
Il server MCP si avvia senza le variabili di ambiente previste La voce di configurazione del server non le imposta, e non si trovano nell'ambiente che Claude Code passa ai server stdio: il suo ambiente, meno le variabili che rimuove dai sottoprocessi Imposta per-server env all'interno della voce .mcp.json del server, che non dipende dall'ambiente di lancio o dalla fiducia dell'area di lavoro.
La regola di negazione Bash(rm *) non blocca /bin/rm o find -delete Le regole Bash corrispondono alla stringa di comando letterale, non all'eseguibile sottostante; vedi cosa una regola Bash non corrisponde Usa un PreToolUse hook o la sandbox per una garanzia difficile.

Per il riferimento completo su ogni superficie di configurazione, vedi la pagina dedicata: