Claude Code non riesce a vedere i file del progetto: perché e cosa fare nel 2026

Una situazione familiare: chiedi a Claude Code di correggere un file e lui risponde che quel file non esiste. Oppure modifica silenziosamente qualcosa di completamente diverso da ciò che intendevi. Apri la cartella: il file è lì, esattamente dove dovrebbe essere. Ma Claude sembra non accorgersene.

Quasi sempre c’è un solo motivo e non c’è nulla di rotto. Claude non vede i file dell’intero computer. Può accedere solo alla cartella da cui lo hai avviato. Avviarlo in una cartella sorella o sotto la radice del progetto può lasciare fuori file necessari. Partire da un genitore come Home dà invece un ambito più ampio e non rende inaccessibile un progetto discendente. Ti spiegherò passo dopo passo perché funziona così e come dare a Claude accesso ai file di cui ha bisogno. Riporto comandi e impostazioni direttamente dalla documentazione ufficiale di Claude Code, che ho consultato all’inizio di settembre 2026.

Altri materiali sulla configurazione degli strumenti sono disponibili nella documentazione di Ailoot.

Perché Claude Code non riesce a vedere alcuni file del progetto?#

Per impostazione predefinita, Claude Code lavora con una sola cartella: quella in cui hai inserito il comando claude e avviato la sessione. La documentazione lo dice chiaramente.

Questa è la sua directory di lavoro. Al suo interno, Claude legge qualsiasi file senza altre domande: modificare un prompt, cercare nel codice, leggere un file specifico: funziona tutto subito. Ma tutto ciò che si trova al di fuori di questa cartella è inaccessibile per impostazione predefinita. Una cartella vicina, una cartella un livello più in alto, un altro disco: Claude non ci guarderà finché non glielo consentirai.

Una cartella di lavoro diversa può spiegare il problema. Se il progetto è /Users/you/my-shop ma avvii Claude in /Users/you/other-project, una cartella sorella, index.html di my-shop è fuori dall’albero di lavoro. Partire da /Users/you è diverso: my-shop è discendente e non è inaccessibile solo perché sei partito da Home, anche se il contesto selezionato è più ampio. Accedere a una cartella non significa neppure averne già letto ogni file.

Ora vedremo come controllare e risolvere il problema: prima verificheremo da quale cartella è stato avviato Claude, poi gli daremo accesso ai file di cui ha bisogno in modi diversi, da un’istruzione una tantum a un’impostazione permanente.

Come puoi controllare da quale cartella è stato avviato Claude Code?#

Prima di correggere qualsiasi cosa, assicurati che il problema sia davvero la cartella. È facile controllare. Chiedi a Claude nella chat di mostrare la directory in cui si trova: eseguirà pwd, che è sicuro: il comando mostra solo il percorso e non tocca nulla.

pwd

La risposta mostra la directory di lavoro effettiva. Confrontala con il percorso completo del progetto: /Users/you/other-project è una cartella sorella di /Users/you/my-shop, mentre /Users/you è il genitore. Nel primo caso my-shop è fuori dall’albero di lavoro; nel secondo è incluso, ma non è scelto come radice specifica del progetto.

Il modo più semplice per risolvere questa discrepanza è avviare Claude direttamente dalla cartella del progetto. Chiudi la sessione corrente, raggiungi la cartella corretta nel terminale e avvia Claude da lì:

# Sostituisci il percorso illustrativo con la radice effettiva del progetto.
cd /Users/you/my-shop
claude

Ora my-shop sarà la cartella di lavoro e tutti i file del progetto saranno visibili. La stessa regola si applica a un editor come VS Code: apri la cartella che contiene il progetto. Non la cartella un livello più in alto e non l’intero disco. La cartella che apri determina ciò che Claude considera la sua directory di lavoro.

Se riavviare è scomodo, per esempio perché hai già fornito contesto a Claude in questa sessione e non vuoi perderlo, puoi aggiungere o cambiare cartella al volo. Le due sezioni successive spiegano come.

Come puoi mostrare a Claude Code un file in una cartella vicina?#

A volte un progetto non è conservato in una sola cartella. Il codice si trova in un posto, le immagini o i testi in una cartella vicina e i componenti condivisi da qualche altra parte nelle vicinanze. È scomodo riavviare Claude ogni volta in una cartella diversa. È meglio dargli accesso alla cartella che gli serve mantenendo la cartella principale come directory di lavoro.

Il modo più semplice è farlo direttamente nella sessione attiva con il comando:

/add-dir ../assets

Inserisci /add-dir e il percorso della cartella, e Claude avrà subito accesso ai suoi file allo stesso modo di quelli nella cartella principale. Non ti chiederà di nuovo l’autorizzazione: la cartella aggiunta segue le stesse regole della directory di lavoro.

Se sai già che lavorerai con più cartelle, apri l’accesso non appena Claude si avvia, usando lo stesso percorso ma con un flag:

claude --add-dir ../assets

E se hai bisogno sempre della stessa cartella vicina in un progetto, non occorre aggiungerla manualmente ogni volta. Il file delle impostazioni settings.json ha una chiave additionalDirectories. Elenca lì i percorsi e si apriranno automaticamente ogni volta che Claude si avvia:

{
  "permissions": {
    "additionalDirectories": ["../assets", "../shared"]
  }
}

Una precisazione per Windows: non puoi aggiungere una cartella di rete usando un percorso come \\server\shared: Claude non accetta percorsi di questo tipo. Montala come unità separata con una lettera di unità, poi passa quella lettera con --add-dir. Le normali cartelle locali non hanno questo problema.

E se aggiungere una cartella vicina non basta e devi passare a un’altra cartella del tutto? C’è un comando apposito, illustrato qui sotto.

Come puoi passare a un’altra cartella in Claude Code durante una sessione?#

A volte aggiungere una cartella vicina non basta: devi cambiare la cartella principale e passare a un altro progetto senza perdere il contesto che hai costruito. Usa il comando /cd:

/cd ../another-project

Da quel momento Claude considererà la nuova cartella come directory di lavoro. Conserverai l’intera cronologia della conversazione, ma il punto di riferimento che Claude usa per i file cambierà e sarà la nuova posizione. Claude caricherà anche il file di istruzioni CLAUDE.md dalla nuova cartella, se presente: in altre parole, si adeguerà alle regole del nuovo progetto.

Una cosa da sapere sulla fiducia: se non hai mai lavorato in questa cartella, quando ti sposti lì Claude ti chiederà se ti fidi. È una misura di sicurezza: un file di istruzioni in una cartella sconosciuta potrebbe contenere qualsiasi cosa, quindi Claude verifica prima che si tratti del tuo progetto. Conferma e poi continua.

La differenza tra i due comandi è semplice. /add-dir mantiene la cartella principale come directory di lavoro e apre una cartella vicina in aggiunta ad essa: è utile quando le parti di un progetto sono sparse in luoghi diversi. /cd sposta l’intera directory di lavoro in una nuova posizione: è utile quando passi a un altro progetto. Il comando /cd è stato introdotto nella versione 2.1.169, quindi se non è disponibile, aggiorna Claude Code. Ho una guida separata su come aggiornare Claude Code.

La visibilità dei file in Claude Code è solo il punto di partenza. Risultati stabili non dipendono soltanto dall’accesso ai file. Dipendono dal contenuto di quei file e da come costruisci il contesto attorno al progetto.

Perché Claude Code non riesce a vedere un file in una sottocartella?#

È importante non confondere due situazioni diverse. Una cartella vicina, esterna al progetto, è completamente inaccessibile finché non la aggiungi. Una sottocartella all’interno del progetto è diversa: Claude può accedervi, ma non tiene a mente i suoi contenuti fin dall’inizio.

Ecco come funziona. Quando Claude si avvia, carica ciò che si trova ai livelli più alti del progetto. Carica i file delle sottocartelle su richiesta, quando vi accede per leggere qualcosa. La documentazione descrive questo comportamento per i file di istruzioni e la stessa logica si applica al contesto in generale.

In parole semplici: il file nella sottocartella annidata a molti livelli non è scomparso ed è pienamente accessibile. Claude semplicemente non lo ha ancora memorizzato perché non lo ha consultato: questo spiega perché può sembrare che Claude «non riesca a vedere» un file anche se è lì ed è accessibile.

Puoi risolvere il problema in una riga. Fornisci direttamente a Claude il percorso del file, per esempio src/components/header.jsx, oppure chiedigli semplicemente di leggere prima il file. Non appena lo consulta, il file entrerà nel contesto e potrai lavorarci normalmente. Non è necessario cambiare alcuna impostazione.

Dove spariscono i file dal menu @ e cosa c’entra .gitignore?#

Un altro motivo comune per cui si pensa che Claude abbia «perso» un file è il selettore di file. Quando digiti @, compare un elenco che rende comodo selezionare un file senza digitarne il percorso completo. Ma l’elenco non mostra tutto.

Per impostazione predefinita, il menu @ nasconde i file elencati in .gitignore. Quel file specifica cosa non dovrebbe essere aggiunto al repository condiviso: cartelle di servizio, file contenenti password e impostazioni di ambiente, e output di compilazioni completate. La logica è chiara: di solito non hai bisogno di lavorare manualmente con questi file, quindi ingombrerebbero soltanto l’elenco. Ma a volte hai bisogno di uno di questi file e non lo trovi nel menu.

L’impostazione respectGitignore controlla questo comportamento. È attiva per impostazione predefinita, quindi i file di .gitignore non compaiono nel menu. Se vuoi visualizzarli, impostala su false:

{
  "respectGitignore": false
}

Puoi fare la stessa cosa senza modificare il file, usando il comando /config all’interno di Claude Code. L’opzione si chiama «Rispetta .gitignore nel selettore di file». Deselezionala e i file nascosti torneranno nel menu.

Una precisazione importante: respectGitignore si applica solo al menu @ e non ha nulla a che fare con l’accesso ai file. Anche quando un file è nascosto dall’elenco, puoi sempre inserirne manualmente il percorso e Claude lo leggerà. Il menu è una funzione di comodità; non definisce il perimetro di accesso.

Cosa dovresti fare se Claude Code non riesce a leggere un file specifico?#

Se la cartella è sicuramente quella giusta e l’accesso è consentito, ma Claude continua a non voler leggere un file specifico, probabilmente è soggetto a una restrizione. Le restrizioni si trovano nel file delle impostazioni settings.json e sono di due tipi.

La prima è una restrizione mirata su file specifici. Nelle impostazioni si tratta di regole deny, che si applicano più spesso al file .env, dove sono conservate chiavi e password:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Una regola del genere impedisce a Claude di leggere i file specificati, ed è intenzionale. Chiavi e password non dovrebbero finire in una conversazione con il modello, quindi .env è protetto per impostazione predefinita. Se Claude si rifiuta di leggere .env o un file simile contenente segreti, è previsto: non dovresti rimuovere questa restrizione senza una ragione impellente.

Il secondo tipo è una restrizione generale su tutto ciò che si trova al di fuori delle cartelle di lavoro. L’impostazione blockReadsOutsideWorkingDirectories la controlla. Se è attiva, Claude si rifiuta di leggere qualsiasi file esterno alla directory di lavoro, anche se provi ad aprirlo direttamente. Se è impostata su true e ti serve un file esterno, aggiungi la sua cartella con /add-dir oppure disattiva la restrizione:

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": false
  }
}

Questa impostazione è stata introdotta nella versione 2.1.257. Se hai provato tutto il resto ma il file è ancora inaccessibile, vale la pena controllare sia deny sia blockReadsOutsideWorkingDirectories.

Da dove dovresti iniziare se Claude Code non riesce a vedere i file?#

Ecco un breve piano che puoi seguire dall’inizio alla fine.

1. Controlla la cartella di lavoro: chiedi a Claude di mostrare la directory corrente usando pwd e confrontala con la posizione del progetto.
2. Se le cartelle non corrispondono, riavvia Claude da quella corretta (cd project, poi claude) oppure spostati lì con il comando /cd.
3. Ti servono file da una cartella vicina? Aggiungila con /add-dir oppure con il flag --add-dir all’avvio di Claude.
4. Un file di una sottocartella non è nel contesto? Indica direttamente il suo percorso a Claude oppure chiedigli di leggere il file.
5. Un file manca dal menu @? È colpa di .gitignore. Imposta respectGitignore su false oppure deseleziona la casella in /config.
6. Un file specifico è bloccato? Controlla le regole deny e blockReadsOutsideWorkingDirectories in settings.json.

Nove volte su dieci, il primo passaggio risolve tutto: Claude è stato avviato dalla cartella sbagliata. L’accesso ai file è il fondamento, ma non costruirà il tuo progetto al posto tuo. Ho spiegato in dettaglio come creare un contesto attorno a Claude in modo che tenga a mente l’intero progetto e non perda il filo nella mia guida al Second Brain in Claude Code.

Trova altri materiali per lavorare con gli strumenti nella documentazione di Ailoot.