# O Claude Code não consegue ver os ficheiros do projeto: porquê e o que fazer em 2026 > Porque é que o Claude Code não consegue encontrar ficheiros do projeto: foi iniciado a partir da pasta errada, o ficheiro está numa subpasta ou está no .gitignore. Como conceder acesso com add-dir, cd e definições. Source: https://ailoot.ai/blog/pt-pt/claude-code-cant-see-project-files/ Canonical: https://ailoot.ai/blog/pt-pt/claude-code-cant-see-project-files/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-199 Revision: sha256-2c07da1c7cee1eca26f1c1bbbeca9d33ea997b870e2c9484451df5bf72f396b6 Uma situação familiar: pede ao Claude Code que corrija um ficheiro e ele responde que esse ficheiro não existe. Ou altera silenciosamente algo completamente diferente daquilo que pretendia. Abre a pasta — o ficheiro está lá, exatamente onde devia estar. Mas parece que o Claude não dá por ele. Quase sempre, há uma única razão e nada está avariado. O Claude não vê os ficheiros de todo o computador. Só pode aceder à pasta a partir da qual o iniciou. Iniciar numa pasta irmã ou abaixo da raiz pode deixar ficheiros necessários fora da árvore de trabalho. Iniciar numa pasta antepassada, como a pasta pessoal, dá âmbito mais amplo; não torna inacessível um projeto descendente. Vou explicar passo a passo porque é que isto funciona assim e como dar ao Claude acesso aos ficheiros de que precisa. Cito comandos e definições diretamente da documentação oficial do Claude Code, que consultei no início de setembro de 2026. Pode encontrar materiais adicionais sobre a configuração de ferramentas na [documentação da Ailoot](https://ailoot.ai/docs/).
[Guias Ailoot](https://ailoot.ai/docs/)
## Porque é que o Claude Code não consegue ver alguns ficheiros do projeto?
Conclusão principal O Claude Code não lê ficheiros de toda a unidade; só lê os que estão na pasta onde o iniciou. Essa pasta chama-se diretório de trabalho. O Claude pode ver e ler tudo o que estiver nela e nas respetivas subpastas, sem perguntar. Tudo o que estiver fora dela — numa pasta vizinha, um nível acima ou noutra unidade — fica inacessível até lhe conceder acesso. Por isso, a razão mais comum para um ficheiro «não estar visível» é simples: iniciou o Claude a partir de uma pasta diferente. Primeiro, confirme exatamente a partir de onde o abriu.
Por predefinição, o Claude Code trabalha com uma pasta: aquela onde introduziu o comando `claude` e iniciou a sessão. A documentação diz isto diretamente.

Por predefinição, o Claude tem acesso aos ficheiros da pasta a partir da qual o iniciou.

— Claude Code Docs, Configure permissions, documentação oficial
Esta pasta é o diretório de trabalho do Claude. Dentro dela, o Claude lê qualquer ficheiro sem perguntas adicionais: editar um prompt, procurar código, ler um ficheiro específico — tudo funciona de imediato. Mas tudo o que estiver fora desta pasta fica inacessível por predefinição. Uma pasta vizinha, uma pasta um nível acima, outra unidade — o Claude não irá procurar nesses locais até lhe dar autorização. É aqui que uma pasta de trabalho errada pode importar. Suponha que o projeto é `/Users/you/my-shop`, mas iniciou o Claude em `/Users/you/other-project`, uma pasta irmã. O `index.html` de `my-shop` fica fora dessa árvore. Iniciar em `/Users/you` é diferente: `my-shop` é descendente e não fica inacessível só por iniciar na pasta pessoal, embora o âmbito seja mais amplo do que o pretendido. Acesso a uma pasta também não significa que todos os ficheiros já foram lidos. A seguir, vou explicar como verificar e corrigir isto: primeiro confirmamos a partir de que pasta o Claude foi iniciado e, depois, damos-lhe acesso aos ficheiros de que precisa de diferentes formas — desde uma instrução pontual até uma definição permanente. ## Como pode verificar a partir de que pasta o Claude Code foi iniciado?
Conclusão principal Pergunte ao Claude em que pasta está ou peça-lhe que mostre o diretório atual com o comando `pwd` — este só verifica e não altera nada. Compare o que mostrar com a localização real do projeto. Se os caminhos forem diferentes, essa é a razão: o Claude foi iniciado a partir da pasta errada. Uma solução ainda mais fiável é fechar a sessão e voltar a iniciar o Claude diretamente a partir da pasta do projeto: navegue até lá no terminal e introduza `claude` nessa pasta.
Antes de corrigir seja o que for, confirme que a pasta é realmente o problema. É fácil verificar. Peça ao Claude no chat que mostre o diretório onde se encontra — ele executará `pwd`, que é seguro: o comando limita-se a mostrar o caminho e não altera nada. ```bash pwd ``` A resposta mostra a pasta de trabalho real. Compare-a com o caminho completo do projeto: `/Users/you/other-project` é irmã de `/Users/you/my-shop`, enquanto `/Users/you` é antepassada. No primeiro caso, `my-shop` fica fora da árvore; no segundo, está incluída, mas não é selecionada como raiz específica. A forma mais simples de resolver esta diferença é iniciar o Claude diretamente a partir da pasta do projeto. Feche a sessão atual, navegue até à pasta correta no terminal e inicie o Claude a partir daí: ```bash # Substitua este caminho ilustrativo pela raiz real do projeto. cd /Users/you/my-shop claude ``` Agora, `my-shop` será a pasta de trabalho e todos os ficheiros do projeto estarão visíveis. A mesma regra aplica-se num editor como o VS Code: abra a pasta que contém o projeto. Não a pasta um nível acima nem a unidade inteira. A pasta que abrir determina o que o Claude considera o seu diretório de trabalho. Se for inconveniente voltar a iniciar a sessão — por exemplo, se já tiver dado contexto ao Claude nesta sessão e não quiser perdê-lo — pode adicionar ou mudar de pasta durante a sessão. As duas secções seguintes explicam como. ## Como pode mostrar ao Claude Code um ficheiro que está numa pasta vizinha?
Conclusão principal Sem reiniciar a sessão, adicione a pasta de que precisa com o comando `/add-dir` diretamente no chat: introduza `/add-dir` e o caminho da pasta, e os respetivos ficheiros ficarão disponíveis nas mesmas condições que os da pasta principal. Para abrir o acesso logo quando o Claude é iniciado, adicione a opção `--add-dir` com um caminho ao comando `claude`. E, se quiser que uma pasta seja aberta automaticamente todas as vezes, adicione-a à chave `additionalDirectories` nas definições. Nos três casos, é possível ler os ficheiros da pasta adicionada sem confirmações separadas.
Por vezes, um projeto não está guardado numa única pasta. O código está num sítio, as imagens ou o texto numa pasta vizinha e os componentes partilhados algures nas proximidades. É inconveniente reiniciar o Claude em cada pasta, uma de cada vez. É melhor dar-lhe acesso à pasta de que precisa e manter a pasta principal como diretório de trabalho. A forma mais simples é fazê-lo diretamente na sessão ativa com o comando: ``` /add-dir ../assets ``` Introduza `/add-dir` e o caminho da pasta, e o Claude terá acesso imediato aos respetivos ficheiros, nas mesmas condições que aos ficheiros da pasta principal. Não voltará a pedir autorização: a pasta adicionada segue as mesmas regras que o diretório de trabalho.

Os ficheiros em diretórios adicionais seguem as mesmas regras de acesso que o diretório de trabalho principal: são lidos sem pedir autorização.

— Claude Code Docs, Configure permissions, documentação oficial
Se já souber que vai trabalhar com várias pastas, abra o acesso assim que o Claude for iniciado — usando o mesmo caminho, mas com uma opção: ```bash claude --add-dir ../assets ``` E, quando precisar sempre da mesma pasta vizinha num projeto, não é necessário adicioná-la manualmente todas as vezes. O ficheiro de definições `settings.json` tem uma chave `additionalDirectories`. Indique aí os caminhos e estes serão abertos automaticamente sempre que o Claude for iniciado: ```json { "permissions": { "additionalDirectories": ["../assets", "../shared"] } } ``` Há uma ressalva no Windows: não pode adicionar uma pasta de rede com um caminho como `\\server\shared` — o Claude não aceita esse tipo de caminho. Monte-a como uma unidade separada com uma letra e, em seguida, indique essa letra com `--add-dir`. As pastas locais normais não têm este problema. E se adicionar uma pasta vizinha não for suficiente e precisar de mudar completamente para outra pasta? Existe um comando específico para isso, que explicamos a seguir. ## Como pode mudar o Claude Code para outra pasta durante uma sessão?
Conclusão principal O comando `/cd` muda a pasta de trabalho principal sem fechar a sessão: introduza `/cd` e um caminho, e o Claude irá para essa localização mantendo o histórico da conversa. Durante a mudança, carregará o ficheiro de instruções `CLAUDE.md` da nova pasta e, se nunca tiver trabalhado nela, pedirá que confirme se confia nela. A diferença em relação a `/add-dir` é que `/add-dir` abre uma pasta vizinha juntamente com a principal, enquanto `/cd` move todo o diretório de trabalho para uma nova localização. O comando está disponível a partir da versão 2.1.169.
Por vezes, adicionar uma pasta vizinha não é suficiente — precisa de mudar a pasta principal e passar para outro projeto sem perder o contexto que acumulou. Use o comando `/cd`: ``` /cd ../another-project ``` Depois disso, o Claude passa a tratar a nova pasta como o seu diretório de trabalho. Mantém todo o histórico da conversa, mas o local que o Claude usa como referência para os ficheiros muda para a nova localização. O Claude também carrega o ficheiro de instruções `CLAUDE.md` da nova pasta, se existir — ou seja, adapta-se às regras do novo projeto. Há uma coisa a saber sobre confiança: se nunca tiver trabalhado nesta pasta, o Claude perguntará se confia nela quando mudar para lá. Esta é uma salvaguarda: um ficheiro de instruções numa pasta desconhecida pode conter qualquer coisa, por isso o Claude verifica primeiro se é o seu projeto. Confirme e continue. A diferença entre os dois comandos é simples. `/add-dir` mantém a pasta principal como diretório de trabalho e abre também uma pasta vizinha — útil quando as partes de um projeto estão espalhadas. `/cd` move todo o diretório de trabalho para uma nova localização — útil quando muda para outro projeto. O comando `/cd` foi introduzido na versão 2.1.169, por isso, se não estiver disponível, atualize o Claude Code. Tenho um guia separado sobre [como atualizar o Claude Code](https://ailoot.ai/blog/pt-pt/update-claude-code/). O facto de o Claude Code ver ficheiros é apenas a base. Os resultados consistentes não dependem apenas do acesso aos ficheiros. Dependem do conteúdo desses ficheiros e da forma como constrói o contexto em torno do projeto.
[Guias Ailoot](https://ailoot.ai/docs/)
## Porque é que o Claude Code não consegue ver um ficheiro numa subpasta?
Conclusão principal As subpastas funcionam de forma diferente das pastas vizinhas: o Claude tem acesso a elas, mas o respetivo conteúdo não entra logo no contexto. O Claude carrega ficheiros de instruções e o conteúdo das subpastas quando necessário, à medida que as consulta. Não os carrega ao iniciar. Por isso, um ficheiro numa subpasta profundamente aninhada pode estar «invisível» até lhe indicar diretamente o caminho. A solução é simples: indique ao Claude o caminho exato do ficheiro ou peça-lhe que o leia primeiro, e ele ficará visível.
É importante não confundir duas situações diferentes. Uma pasta vizinha (fora do projeto) fica completamente inacessível até a adicionar. Uma subpasta dentro do projeto é diferente: o Claude tem acesso a ela, mas não mantém o respetivo conteúdo presente desde o início. É assim que funciona. Quando o Claude é iniciado, carrega o que está nos níveis superiores do projeto. Carrega ficheiros das subpastas quando necessário, ao entrar nelas para ler algo. A documentação descreve este comportamento para os ficheiros de instruções, e a mesma lógica aplica-se ao contexto em geral.

O Claude descobre ficheiros nas subpastas do diretório de trabalho. Em vez de os carregar ao iniciar, vai buscá-los quando lê ficheiros nessas subpastas.

— Claude Code Docs, Manage Claude's memory, documentação oficial
Em termos simples: o ficheiro numa subpasta profundamente aninhada não desapareceu e está totalmente acessível. O Claude simplesmente ainda não se lembrou dele porque ainda não o consultou — o que explica porque pode parecer que o Claude «não consegue ver» um ficheiro, apesar de este estar lá e ser acessível. Pode resolver isto numa só linha. Indique diretamente ao Claude o caminho do ficheiro — por exemplo, `src/components/header.jsx` — ou peça-lhe simplesmente que leia primeiro o ficheiro. Assim que o consultar, o ficheiro será incluído no contexto e poderá trabalhar com ele normalmente. Não é necessário alterar definições. ## Onde desaparecem os ficheiros do menu @ e o que é que isso tem a ver com o .gitignore?
Conclusão principal Quando escreve o símbolo `@`, o Claude Code mostra uma lista de ficheiros à sua escolha. Por predefinição, esta lista oculta tudo o que estiver incluído no `.gitignore` — pastas de serviço, ficheiros de ambiente e resultados de compilação. Assim, um ficheiro pode estar exatamente onde devia estar e, mesmo assim, não aparecer no menu `@`. A definição `respectGitignore` controla este comportamento: está ativada por predefinição e oculta esses ficheiros. Defina-a como `false` e o menu também mostrará os ficheiros indicados no `.gitignore`. Pode sempre introduzir manualmente o caminho de um desses ficheiros.
Outra razão comum para pensar que o Claude «perdeu» um ficheiro é o seletor de ficheiros. Quando escreve `@`, aparece uma lista que facilita a seleção de um ficheiro sem ter de escrever o caminho completo. Mas a lista não mostra tudo. Por predefinição, o menu `@` oculta os ficheiros indicados no `.gitignore`. Este ficheiro especifica o que não deve ser adicionado ao repositório partilhado: pastas de serviço, ficheiros com palavras-passe e definições de ambiente, e resultados de compilação concluídos. A lógica é clara — normalmente, não precisa de trabalhar manualmente com estes ficheiros, por isso só iriam encher a lista. Mas, por vezes, precisa de um deles e não o encontra no menu. A definição `respectGitignore` controla este comportamento. Está ativada por predefinição, por isso os ficheiros do `.gitignore` não aparecem no menu. Se os quiser ver, mude-a para `false`: ```json { "respectGitignore": false } ``` Pode fazer o mesmo sem editar o ficheiro, usando o comando `/config` dentro do Claude Code. A opção chama-se «Respeitar .gitignore no seletor de ficheiros». Desmarque-a e os ficheiros ocultos voltarão a aparecer no menu. Uma ressalva importante: `respectGitignore` aplica-se apenas ao menu `@` e não tem nada que ver com o acesso a ficheiros. Mesmo quando um ficheiro está oculto na lista, pode sempre introduzir o caminho manualmente e o Claude irá lê-lo. O menu é uma funcionalidade de conveniência; não define os limites de acesso. ## O que deve fazer se o Claude Code não conseguir ler um ficheiro específico?
Conclusão principal Por vezes, a pasta está correta, mas o Claude continua a recusar-se a ler um ficheiro específico. Normalmente, a razão é uma restrição nas definições. O ficheiro `settings.json` pode conter regras `deny` que impedem a leitura de determinados ficheiros, sobretudo ficheiros `.env` com chaves e palavras-passe. Há também uma definição que bloqueia completamente a leitura de tudo o que esteja fora das pastas de trabalho. Verifique ambos os pontos no `settings.json`. E lembre-se de que a restrição para `.env` é uma salvaguarda predefinida; não a deve remover sem um bom motivo.
Se a pasta estiver definitivamente correta e o acesso estiver aberto, mas o Claude continuar a não ler um ficheiro específico, é provável que exista uma restrição. As restrições estão no ficheiro de definições `settings.json` e são de dois tipos. O primeiro é uma restrição específica para determinados ficheiros. Nas definições, estas são as regras `deny` e aplicam-se, mais frequentemente, ao ficheiro `.env`, onde são guardadas chaves e palavras-passe: ```json { "permissions": { "deny": [ "Read(./.env)", "Read(./.env.*)" ] } } ``` Esta regra impede intencionalmente o Claude de ler os ficheiros especificados. As chaves e palavras-passe não devem acabar numa conversa com o modelo, por isso o `.env` está protegido por predefinição. Se o Claude se recusar a ler `.env` ou um ficheiro semelhante que contenha segredos, isso é intencional; não deve remover esta restrição sem uma razão convincente. O segundo tipo é uma restrição geral a tudo o que esteja fora das pastas de trabalho. A definição `blockReadsOutsideWorkingDirectories` controla-a. Quando está ativada, o Claude recusa-se a ler qualquer ficheiro fora do diretório de trabalho, mesmo que tente abri-lo diretamente. Se estiver definida como `true` e precisar de um ficheiro externo, adicione a pasta com `/add-dir` ou desative a restrição: ```json { "permissions": { "blockReadsOutsideWorkingDirectories": false } } ``` Esta definição foi introduzida na versão 2.1.257. Se já tentou tudo o resto e o ficheiro continua inacessível, vale a pena verificar tanto `deny` como `blockReadsOutsideWorkingDirectories`. ## Por onde deve começar se o Claude Code não consegue ver ficheiros?
Conclusão principal Comece por verificar a pasta: peça ao Claude que mostre o diretório atual com `pwd` e compare-o com a localização do projeto. Se não coincidirem, volte a iniciar o Claude a partir da pasta do projeto ou mude para lá com `/cd`. Precisa de ficheiros de uma pasta vizinha? Abra-a com `/add-dir`. Não consegue ver um ficheiro numa subpasta? Indique diretamente o caminho ao Claude. Falta um ficheiro no menu `@`? Está relacionado com o `.gitignore` — altere `respectGitignore`. Um ficheiro está bloqueado? Procure uma restrição `deny` no `settings.json`.
Segue-se um plano curto que pode percorrer do início ao fim. 1. Verifique a pasta de trabalho: peça ao Claude que mostre o diretório atual com `pwd` e compare-o com a localização do projeto. 2. Se as pastas forem diferentes, volte a iniciar o Claude a partir da pasta correta (`cd project` e, em seguida, `claude`) ou mude para lá com o comando `/cd`. 3. Precisa de ficheiros de uma pasta vizinha? Adicione-a com `/add-dir` ou com a opção `--add-dir` ao iniciar o Claude. 4. Um ficheiro de uma subpasta não está no contexto? Indique diretamente o caminho ao Claude ou peça-lhe que leia o ficheiro. 5. Falta um ficheiro no menu `@`? A causa é o `.gitignore`. Defina `respectGitignore` como `false` ou desmarque a caixa em `/config`. 6. Um ficheiro específico está bloqueado? Verifique as regras `deny` e `blockReadsOutsideWorkingDirectories` no `settings.json`. Em nove casos em cada dez, o primeiro passo resolve tudo: o Claude foi iniciado a partir da pasta errada. O acesso aos ficheiros é a base, mas não vai construir o projeto por si. Expliquei em detalhe como criar contexto em torno do Claude para que mantenha todo o projeto presente e não perca o fio à meada no meu guia sobre o [Segundo Cérebro no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/).
### Fontes - [Claude Code - Configure permissions, documentação oficial](https://docs.claude.com/en/docs/claude-code/permissions) - diretório de trabalho predefinido, --add-dir e /add-dir, /cd, additionalDirectories, acesso sem pedir autorização, caminhos de rede - [Claude Code - Manage Claude's memory, documentação oficial](https://docs.claude.com/en/docs/claude-code/memory) - carregamento de ficheiros de subpastas quando necessário, CLAUDE.md, importações - [Claude Code - Settings reference, documentação oficial](https://docs.claude.com/en/docs/claude-code/settings-reference) - respectGitignore e o menu @, blockReadsOutsideWorkingDirectories e versão 2.1.257 - [Claude Code - Settings, documentação oficial](https://docs.claude.com/en/docs/claude-code/settings) - regras deny e bloqueio da leitura de .env
Encontre materiais adicionais sobre como trabalhar com ferramentas na [documentação da Ailoot](https://ailoot.ai/docs/).
[Guias Ailoot](https://ailoot.ai/docs/)
[Aceder ao Ailoot](https://ailoot.ai/)
## Perguntas frequentes ### Porque é diferente iniciar na pasta pessoal ou num projeto irmão? Um projeto abaixo da pasta pessoal é descendente; iniciar aí não o deixa fora da árvore, mas dá contexto mais amplo do que o pretendido. Uma pasta irmã da pasta de trabalho fica fora dela. Compare os caminhos completos antes de diagnosticar falta de acesso. ### Acesso a uma subpasta significa que os ficheiros já estão no contexto? Não. Dê ao agente o caminho e peça-lhe que leia o ficheiro. Se a leitura for negada, inspecione as permissões aplicáveis; um ficheiro ausente do menu de seleção e uma leitura negada são problemas diferentes. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.