Skip to main content
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: 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 delle sottodirectory si caricano su richiesta anziché all’inizio della sessione, quindi non compaiono in quella suddivisione. 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.
CLAUDE.md e permissions risolvono problemi diversi. CLAUDE.md dice a Claude come funziona il tuo progetto in modo che prenda buone decisioni. Permissions e hooks applicano limiti indipendentemente da ciò che Claude decide. Usa CLAUDE.md per “lo facciamo così qui”. Usa permissions o hooks per confini di sicurezza e qualsiasi cosa che non deve mai accadere, dove hai bisogno di una garanzia invece di una guida.

​
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 hook

Esegui /hooks per elencare ogni hook registrato per la sessione corrente, raggruppato per evento. Se un hook che hai definito non appare, Claude Code non l’ha caricato. Verifica queste cause:
  • L’hook è definito in un file autonomo. Gli hook vanno sotto la chiave "hooks" in un file di impostazioni.
  • Il valore matcher è un array invece di una singola stringa. Claude Code elenca la voce come impostazione non valida quando avvii una sessione interattiva e in claude doctor. Se l’array si trova sotto PreToolUse o PermissionRequest, non viene caricato nemmeno nessuno degli altri hook di quel file.
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.
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 allo 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 degli hook per il formato del log e risoluzione dei problemi degli hook per i modelli di errore comuni.

​
Prova con una configurazione pulita

Inizia con claude --safe-mode, che avvia una sessione con le tue personalizzazioni disabilitate, tra cui:
  • CLAUDE.md
  • Skill, plugin e hook
  • Server MCP
  • Comandi e agenti personalizzati
  • Stili di output personalizzati
  • Scorciatoie da tastiera personalizzate
L’autenticazione, la selezione del modello, gli strumenti integrati e i permessi funzionano normalmente. Se il problema scompare in modalità sicura, hai circoscritto la causa a uno degli elementi che hai disattivato. Per trovarlo, usa il controllo relativo a quell’elemento, come Vedi cosa è stato caricato nel contesto, Controlla i server MCP o Controlla gli hook. La modalità sicura applica comunque gli hook gestiti e la policy delle impostazioni della tua organizzazione. I plugin gestiti, le skill, CLAUDE.md e i server MCP sono disattivati. Se il problema persiste in modalità sicura, o le tue impostazioni stesse sono sospette, avvia una sessione senza nessuna tua configurazione e verifica se il problema si ripresenta.
1

Crea una directory vuota e spostati al suo interno

Nella tua shell, senza alcuna sessione di Claude Code in esecuzione, crea la directory e spostati al suo interno:
2

Avvia Claude Code con una directory di configurazione pulita

Dalla stessa shell, imposta CLAUDE_CONFIG_DIR su una nuova directory al posto di ~/.claude e passa --setting-sources user per disattivare la configurazione del progetto, come .claude/settings.json, CLAUDE.md e .mcp.json:
La variabile si applica solo a questo avvio.
Al primo avvio, ripercorri le schermate di configurazione iniziale, segno che la directory di configurazione pulita è in vigore. Le impostazioni gestite si applicano comunque, e i connettori vengono comunque caricati se accedi con un account claude.ai.
3

Riproduci il problema

Ripeti nella sessione pulita ciò che ha causato il problema:
  • Il problema scompare: la causa è nella tua configurazione utente o di progetto. Copia ~/.claude.json e i file in ~/.claude in ~/claude-clean/config uno alla volta. Se nessuno fa ricomparire il problema, vai nella directory del tuo progetto nella stessa shell e avvia Claude Code senza --setting-sources user. In Bash o Zsh, esegui CLAUDE_CONFIG_DIR=~/claude-clean/config claude. In PowerShell, la variabile è ancora impostata, quindi esegui claude.
  • Il problema persiste: la causa è al di fuori della tua configurazione utente e di progetto. Esegui /status nella sessione per verificare la presenza di impostazioni gestite, controlla le variabili d’ambiente nella tua shell, quindi consulta 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: Per il riferimento completo su ogni superficie di configurazione, vedi la pagina dedicata: