Claude Code diz que o arquivo não existe, mas ele está lá: o que conferir primeiro

Fala aí, beleza? O arquivo está lá, você está OLHANDO pra ele no explorador de arquivos, e mesmo assim o Claude Code responde que não encontrou

Dá aquele frio na barriga de achar que a IA travou, ou pior, que ela está alucinando na sua cara

Na quase totalidade dos casos não é bug e não é alucinação

É divergência de escopo: o caminho que existe na sua cabeça (e no seu editor) não é o mesmo conjunto de arquivos que AQUELA sessão enxerga

Então bora fazer isso do jeito certo, com um roteiro de diagnóstico que vai do mais provável pro menos provável

Cada causa aqui vem com sintoma, motivo e o que fazer, beleza?

Causa 1: a sessão foi aberta em outra pasta (o diretório de trabalho não é o que você imagina)

Sintoma: ele lê alguns arquivos numa boa, responde sobre o código, parece tudo certo… e aí jura de pés juntos que um outro arquivo não existe

Causa: por padrão o Claude tem acesso aos arquivos do diretório onde você o iniciou

E esse diretório segue sendo o diretório de trabalho principal da sessão até você mover a sessão com /cd

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Ou seja: se você abriu o terminal já dentro de packages/api e pediu um arquivo que mora em packages/web, o problema não é o arquivo, é de onde a sessão subiu 🙂

Solução: confirme de onde você iniciou a sessão e, se for o caso, mova ela

1. Volte no terminal e olhe em que pasta você estava quando rodou o claude
2. Se a sessão subiu no lugar errado, mova com o comando de mudança de diretório de trabalho:

/cd ../web

O /cd move a sessão para outro diretório de trabalho, aplica as configurações de projeto do novo diretório e pede pra você confirmar que confia naquele workspace caso nunca tenha trabalhado nele

O erro comum deste passo: pedir em linguagem natural pro Claude "mudar de pasta"

Não funciona, e você perde tempo achando que funcionou

O /cd não é model-invocable: o Claude não pode chamar ele

Só funciona quando VOCÊ digita o comando

Como prevenir: inicie a sessão na raiz do projeto sempre que der

E se a dúvida for outra, se ele leu mesmo os arquivos ou só chutou uma resposta convincente, dá pra checar se ele leu o projeto antes de sair caçando caminho

Causa 2: o arquivo está fora do diretório inicial da sessão

Sintoma: arquivo real, caminho certinho, você conferiu duas vezes, e mesmo assim ele não alcança o arquivo (ou fica pedindo confirmação toda hora)

Causa: o escopo padrão é o diretório inicial

Qualquer coisa fora dali é território estrangeiro pra sessão

Causa: clássico de quem tem a lib compartilhada num repo e o app em outro

Solução: existem três formas oficiais de estender o acesso a arquivos fora do diretório inicial

1. Flag --add-dir <caminho> na inicialização, que é argumento de CLI e pode ser repetido pra vários diretórios:

claude --add-dir ../design-system --add-dir ~/projetos/utils

2. Comando /add-dir <path> durante a sessão, que adiciona um working directory pra acesso a arquivos na sessão corrente:

/add-dir ../design-system

3. Ou permissions.additionalDirectories nos arquivos de settings, pros diretórios que você usa TODO dia

Agora o ponto fino que quase ninguém sabe, e que muda o comportamento de verdade

As exceções de configuração valem só pros diretórios adicionados via --add-dir ou /add-dir

O additionalDirectories dá acesso a arquivo e não carrega a configuração daquele diretório

Se você esperava que o setup do outro projeto viesse junto, é por isso que não veio

Tome cuidado com outra coisa: aprovação automática vale só pros caminhos dentro do diretório de trabalho ou de additionalDirectories

Caminho fora disso continua gerando prompt de confirmação, o que é ótimo pra segurança e péssimo pra sua paciência quando você não entendeu o motivo 😀

Causa 3: o arquivo existe, mas a busca pula ele por causa do .gitignore

Sintoma: ele diz que procurou e não achou nada

E o arquivo em questão é um .env, uma pasta de build, um log, ou qualquer coisa que o git ignora

Causa: a ferramenta Grep é construída sobre o ripgrep e respeita o .gitignore

Arquivo ignorado é arquivo pulado na busca

O arquivo está no disco, tá tudo certo com ele, só que a ferramenta de busca nem passou por ali

Solução: pare de mandar ele PROCURAR e entregue o caminho direto

Pra ler um arquivo ignorado, o caminho é passado diretamente, sem intermediário de busca

Aqui tem um contraste que vale guardar, porque as duas ferramentas se comportam diferente

O Glob não respeita o .gitignore por padrão: ele encontra os arquivos ignorados junto com os rastreados

Se você quiser inverter isso, existe a variável de ambiente CLAUDE_CODE_GLOB_NO_IGNORE=false, definida ANTES de iniciar o Claude Code, pra fazer o Glob respeitar o .gitignore

E tem ainda a configuração respectGitignore, que controla se o file picker do @ respeita os padrões do .gitignore

Ou seja: se o arquivo nem aparece no menu de sugestão quando você digita @, olha essa configuração antes de achar que o arquivo sumiu

Como prevenir: pra arquivo ignorado, referência explícita sempre

Nada de "dá uma olhada nas variáveis de ambiente", vai de caminho na mão

Causa 4: a referência ao arquivo ficou ambígua

Sintoma: você escreve o nome do arquivo no meio da frase, tipo "arruma o config.ts"

E ele abre o config.ts errado, ou não acha nenhum

Causa: nome solto não é caminho

Se o projeto tem oito arquivos chamados index.ts, o nome sozinho não diz nada

Pensa como se você pedisse "me passa a pasta" numa sala com trinta pastas iguais em cima da mesa

Solução: existem três jeitos de passar a referência sem deixar dúvida

1. Digite @ pra abrir o menu de sugestão de caminho no modo interativo

Enter ou Tab aceita o caminho destacado, e Enter de novo envia a mensagem

Dá pra referenciar vários arquivos na mesma mensagem, então não precisa mandar uma mensagem por arquivo

2. Use o autocomplete de caminho ao vivo, digitando um token com barra normal como ./src/ ou ~/, e aceitando com Tab

Ele funciona em todas as plataformas, então não é recurso de um sistema só

O erro comum deste passo (usuário Windows, é com você): usar barra invertida

O gatilho é a barra normal /, e não a \, inclusive no Windows

3. No VS Code, Option+K no Mac ou Alt+K no Windows e Linux insere uma @-menção já com o caminho do arquivo e os números de linha, no formato @app.ts#5-10

Esse é ótimo pra quando o problema mora em um trecho específico e não no arquivo inteiro

E por que caminho completo funciona melhor que nome solto?

Porque a ferramenta Read é instruída a sempre receber caminhos absolutos

Quanto mais perto disso você entrega a referência, menos trabalho de adivinhação sobra pro modelo

Causa 5: você mandou ele rodar cd e o efeito não foi o que você esperava

Sintoma: depois de um cd num comando de terminal, alguns caminhos passam a funcionar e outros voltam a falhar

Parece aleatório, mas não é

Causa e regra: quando o Claude roda cd na sessão principal, o novo diretório vale pros comandos Bash seguintes

Porém isso só se mantém enquanto o caminho continuar dentro do diretório do projeto ou de um diretório adicional adicionado com --add-dir, /add-dir ou additionalDirectories

O cd de Bash é navegação dentro do escopo, não é troca de escopo

Solução: pra sair de vez desse escopo tem dois caminhos

Ou /cd, digitado por você, que move a sessão de verdade

Ou adicionar o diretório com uma das três formas da Causa 2, se você quer acesso aos dois lugares ao mesmo tempo

Como prevenir: não trate cd de Bash como troca de projeto

São coisas diferentes, e essa confusão gera muita hora perdida

–add-dir, /add-dir, additionalDirectories e /cd: qual usar em cada situação

Se você chegou até aqui já percebeu que são quatro ferramentas parecidas resolvendo problemas diferentes

Então se liga nessa tabela de decisão:

Recomendação por cenário, resumindo

Arquivo de fora que você vai usar só hoje? /add-dir e segue o baile

Pasta de fora que entra em toda sessão daquele projeto? --add-dir na subida ou additionalDirectories nos settings

Mudou de projeto mesmo? /cd, digitado por você

Onde esse erro mais aparece: monorepo, subpasta e arquivos de outro repositório

Tem três cenários que concentram quase todo o sofrimento aqui

Sessão iniciada numa subpasta do monorepo:

É o campeão

Você abre o terminal dentro de packages/api porque é onde você está trabalhando, e depois pede um arquivo de outro pacote

Uma coisa que ajuda a entender o comportamento: as project skills carregam de .claude/skills/ no diretório onde você inicia o Claude Code e em cada diretório pai até a raiz do repositório

Ou seja, subir a partir do subdiretório ainda pega as skills da raiz, o que dá aquela falsa sensação de "mas ele está enxergando o projeto todo!"

Enxergar skills da raiz não é a mesma coisa que ter acesso aos arquivos de todos os pacotes, beleza?

Quando o assunto vira delimitar em qual pacote do monorepo mexer, o raciocínio de escopo é o mesmo desse post

E o "ele esqueceu as regras do projeto"?

Esse é o segundo cenário, e ele confunde muita gente

O Claude Code carrega todo CLAUDE.md do diretório de trabalho e de cada diretório pai no launch

Já o CLAUDE.md de cada subdiretório é carregado quando ele lê arquivos ali

Traduzindo: se as regras que importam moram numa subpasta que ele ainda não tocou, elas simplesmente não entraram na conversa ainda

Vale lembrar que arquivos de escopo de projeto ficam em .claude/ no repositório, com exceção de CLAUDE.md, .mcp.json e .worktreeinclude, que ficam na raiz

E o CLAUDE.md também funciona em .claude/CLAUDE.md, se você prefere manter a raiz limpa 🙂

Worktrees e subdiretórios do mesmo repositório:

Cada projeto tem seu diretório de memória em ~/.claude/projects/<project>/memory/

O <project> é derivado do repositório git, então worktrees e subdiretórios do MESMO repo compartilham um diretório de memória

Fora de um repositório git, usa-se a raiz do projeto

Isso explica a sensação de "mas ele lembrava disso na outra pasta": lembrança compartilhada não é acesso a arquivo compartilhado

São duas camadas diferentes

Resumo do diagnóstico e o próximo passo

Fechando o roteiro, uma frase por causa

1. A sessão pode ter subido em outra pasta, e o diretório inicial manda até você rodar /cd
2. O arquivo pode estar fora do escopo, e aí é --add-dir, /add-dir ou additionalDirectories
3. A busca pode ter pulado o arquivo por causa do .gitignore, e a saída é entregar o caminho direto
4. A referência pode ter ficado ambígua, e o @ ou o caminho absoluto resolvem
5. O cd de Bash pode ter dado a impressão de troca de projeto, mas ele não é isso

Da próxima vez que aparecer aquele "não existe" na sua frente, começa confirmando de onde a sessão subiu

Depois estende o escopo se o arquivo mora fora

E por último passa a referência por @ ou caminho absoluto, sem nome solto

Rotina que evita quase toda a dor de cabeça: iniciar sempre na raiz do projeto e deixar os diretórios recorrentes em permissions.additionalDirectories

É chato de configurar uma vez e nunca mais você pensa nisso 😀

Se curte esse tipo de conteúdo, tem mais post sobre Claude Code aqui no blog, e a gente vai destroçando essas pegadinhas uma a uma

Até o próximo post!