Claude Code não lê os arquivos? Como saber se ele leu o projeto ou chutou a resposta

A resposta chegou em três segundos, veio bem escrita, bem estruturada, com bullet e tudo

E não citou um único arquivo do seu projeto

O problema aqui não é o Claude Code estar errado (às vezes ele até acerta no chute, e é isso que confunde), o problema é você não conseguir separar leitura real de padrão genérico ANTES de aplicar a sugestão no código

Porque uma resposta tirada do padrão do framework parece idêntica a uma resposta tirada do seu repositório

Aí você aplica, quebra, e só descobre depois

Bora aprender a reconhecer os sinais? 🙂

Sinal 1: resposta genérica que nunca cita um arquivo do seu projeto

O sintoma: a resposta fala de "seu componente", "sua config", "o seu handler" e nunca nomeia um caminho, uma função ou uma linha que existam de verdade no repositório

É vago com cara de específico

A causa provável: o modelo respondeu do padrão da linguagem ou do framework, sem abrir arquivo nenhum

Ele sabe como um projeto Next "costuma" ser, e isso basta pra montar uma resposta plausível

A solução: confira o transcript

O Ctrl+O abre o visualizador de transcrição e alterna o modo verboso, mostrando o raciocínio em texto cinza itálico (que fica recolhido por padrão)

Se não existiu chamada de leitura antes da resposta, você acabou de descobrir que aquilo ali não veio do seu código

Pra prevenir: peça o comprovante junto com a resposta

Algo como "me diga o caminho do arquivo e cole o trecho que embasou essa conclusão"

Quando não tem trecho pra colar, a coisa aparece na hora

Sinal 2: velocidade incompatível com o tamanho do pedido

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O sintoma: você pediu algo que exige varrer o codebase inteiro, tipo "onde esse estado é mutado?", e a resposta veio quase instantânea

Rápido demais é suspeito

Varrer projeto custa tempo, e tempo aqui é sinal de trabalho feito

A causa provável: nenhuma etapa de busca ou exploração rodou

Ele pulou direto pro texto final

A solução: ligue o modo verboso e olhe o que realmente aconteceu

O Ctrl+O alterna o verboso na sessão, e a flag --verbose mostra a saída COMPLETA das ferramentas em vez de resumos truncados

claude --verbose

Essa flag está disponível a partir da v2.1.119, o padrão do ajuste é false e ela sobrepõe o ajuste apenas para aquela sessão

Se preferir, o mesmo item aparece no /config como "Verbose output"

Pra prevenir: deixe o verbose ligado enquanto você ainda está calibrando confiança num projeto novo

Depois que você já sabe o padrão de comportamento dele ali, dá pra desligar e viver em paz

Sinal 3: ele leu a pasta, não os arquivos

O sintoma: o Claude parece conhecer a estrutura do projeto, fala o nome das pastas certinho, e mesmo assim erra o conteúdo de um arquivo que ele "acabou de ver"

Esse é o mais traiçoeiro dos sinais, porque a estrutura correta te dá a sensação de leitura real

A causa: aqui não é bug nem chute, é comportamento documentado do @

E ele muda conforme o que você referencia:

• @ em ARQUIVO inclui o conteúdo completo do arquivo na conversa
• @ em DIRETÓRIO fornece apenas a LISTAGEM do diretório, não o conteúdo

Ou seja: @src/ não é "leia src", é "veja os nomes que existem dentro de src"

A diferença é enorme e passa batido fácil

A solução: referencie os arquivos um a um

Dá pra referenciar vários na mesma mensagem, e ao digitar @ abre um menu de sugestão de caminho pra te ajudar a montar isso rápido

revise o fluxo de login em @src/auth/session.ts e @src/auth/middleware.ts

Um detalhe bom de saber: referências @ também trazem o CLAUDE.md da pasta do arquivo e das pastas pai

Pra prevenir: nunca trate @pasta como "ele leu a pasta inteira"

Tome cuidado com isso, é o tipo de suposição que vira uma sessão inteira de resposta errada

Sinal 4: ele leu o arquivo e ignorou as instruções que estavam dentro dele

O sintoma: dessa vez a leitura ACONTECEU, você viu no transcript, e mesmo assim a regra escrita dentro do arquivo não foi obedecida

Você deixou lá "nunca edite migrations aplicadas" e ele editou

A causa: leitura não é adesão

O conteúdo entrar no contexto não garante que a instrução vai ser seguida, e isso não é impressão sua, é comportamento reportado publicamente

No repositório anthropics/claude-code existe a issue "Claude reads files but ignores actionable instructions contained in them" (#32290), aberta como bug, que é exatamente esse cenário

E tem também a issue "Need a way to enforce entire file reading" (#2595), um pedido aberto da comunidade por uma forma de forçar a leitura integral de arquivos

Duas issues, dois lados do mesmo desconforto: ler tudo, e obedecer o que leu

A solução e a prevenção são a mesma coisa: repita a regra crítica DENTRO do prompt, não confie que o arquivo lido basta

Se a regra é inegociável (não tocar em banco, não mexer em rotas de pagamento), ela vai na mensagem, em caixa alta se precisar

Regra crítica em arquivo é lembrete, regra crítica no prompt é ordem

Esse cuidado vale dobrado quando o agente encosta em coisa irreversível, que é o caso de delegar mudanças no banco de dados

Sinal 5: contexto estourado, memória curta no meio da sessão

O sintoma: no começo da sessão ele acertava os arquivos, citava caminho certo, sabia o que tinha lido

Duas horas depois, começou a chutar

Mesmo projeto, mesma pessoa perguntando, qualidade despencou

A causa: a composição do contexto mudou ao longo da conversa

O que estava lá no começo foi ficando espremido por tudo que veio depois

A solução é olhar e agir, nessa ordem:

• /context reporta o que está ocupando o contexto da sessão
• /compact resume as mensagens mais antigas preservando o contexto importante
• /clear encerra a conversa e começa uma sessão nova, e a conversa anterior fica preservada e pode ser retomada depois

Pra prevenir: recomece limpo ANTES de tarefas que dependem de leitura fiel

Não adianta pedir uma auditoria de arquitetura no finzinho de uma sessão gigante que já passou por três assuntos diferentes

Sessão nova custa alguns segundos, resposta chutada custa uma tarde

Como forçar a leitura antes da resposta, na prática

Beleza, os sinais você já sabe reconhecer

Agora o fluxo pra não depender de sorte:

1. Referencie o arquivo com @, um a um

Digite @ e o menu de sugestão de caminho abre

Lembra que arquivo entra com conteúdo completo e pasta entra só como listagem

E que as referências @ também puxam o CLAUDE.md da pasta do arquivo e das pastas pai

O erro comum deste passo: referenciar a pasta achando que resolveu

2. Entre em plan mode antes de pedir qualquer coisa séria

O Shift+Tab alterna os modos de permissão no meio da sessão, no ciclo default → acceptEdits → plan

Dá pra já abrir a sessão direto nele também:

claude --permission-mode plan

No plan mode ele explora o codebase e produz um plano SEM editar

As edições de arquivo nunca são auto-aprovadas ali, mesmo com regra de allow

A partir da v2.1.212, comandos de shell que modificam arquivos (touch, rm) também passam pelo canUseTool

O erro comum deste passo: passar do plano pro build no automático, sem ler o plano

O plano é justamente onde a leitura preguiçosa aparece, porque plano genérico denuncia leitura genérica

3. Delegue a descoberta ao subagente Explore

O Claude Code tem um subagente Explore embutido, rápido e read-only, feito pra descoberta de arquivos, busca de código e exploração do codebase

O Claude delega a ele quando precisa entender o projeto sem alterar nada, e ao invocar especifica um nível de profundidade (quick, medium ou very thorough)

O erro comum deste passo: achar que o subagente carrega tudo que a sessão principal carrega

Não carrega

Os subagentes Explore e Plan pulam os arquivos CLAUDE.md e o git status da sessão pai, justamente pra manter a pesquisa rápida e barata

Então as suas convenções de projeto não estão valendo lá dentro do subagente

4. Audite depois, pelo transcript

De novo o Ctrl+O

Com renderização em tela cheia, o ? dentro do visualizador lista os atalhos disponíveis

O erro comum deste passo: auditar só quando a resposta parece errada

A resposta chutada perigosa é a que parece CERTA

Trava automática: bloquear a resposta que não passou pela leitura

Esse aqui é nível avançado, pra quem quer garantia em vez de vigilância manual

A ideia é simples: em vez de você conferir o transcript toda vez, um hook confere por você

Hooks ficam no settings.json, que tem escopos user, project, local ou managed

E tem um detalhe MUITO bom aqui: o Claude Code recarrega o arquivo sem precisar reiniciar a sessão, edições em chaves como permissions e hooks valem na sessão em curso

Os dois pontos de interceptação que interessam pro nosso caso:

• PreToolUse: dispara antes da checagem de modo de permissão, em TODOS os modos, e bloqueia a chamada de ferramenta por padrão
• UserPromptSubmit: roda no envio do prompt e rejeita o prompt quando o hook bloqueia com exit code 2

O PreToolUse tem uma sutileza que muda o uso: com continueOnBlock: true ele devolve o motivo ao Claude como erro da ferramenta, e aí o agente se ajusta e segue em vez de simplesmente parar

É a diferença entre "não deixo" e "não deixo assim, faça diferente"

Do lado do UserPromptSubmit, atenção ao relógio: ele tem timeout de 30 segundos, contra o padrão de 10 minutos dos outros hooks

Hook lento ali não é opção

O erro comum deste passo: assumir que modo permissivo desliga o hook

Não desliga

Um permissionDecision: "deny" bloqueia mesmo em bypassPermissions ou com --dangerously-skip-permissions

Outro cuidado: sessões na nuvem (o Claude Code na web) NÃO leem o ~/.claude/settings.json local

Então a sua trava caprichada não te acompanha pra lá

Já apliquei a sugestão chutada: como voltar atrás

Acontece

Você aceitou a edição, o código mudou, e agora está claro que aquela resposta não olhou o projeto

A solução: /rewind

Ele lista cada prompt enviado na sessão e te deixa escolher o que restaurar:

• restaurar código e conversa
• restaurar a conversa mantendo o código atual
• restaurar o código mantendo a conversa
• resumir a partir daquele ponto, ou até ele

Essa granularidade é útil demais

Porque às vezes você quer manter a conversa (o contexto todo que vocês construíram) e jogar fora só as alterações no código

Pra prevenir: rode em plan mode enquanto a confiança na leitura ainda não está estabelecida

Plano ruim você descarta de graça, código ruim você desfaz na pressa

O que a prática mostra sobre confiar (ou não) na resposta do agente

Esse hábito de desconfiar da resposta rápida eu não peguei lendo doc, peguei apanhando

E ele aparece bem claro num vídeo que gravei testando o OpenCode, um cliente de terminal que roda com vários modelos

No vídeo eu desinstalei a ferramenta antes de gravar pra instalar do zero junto com quem estava assistindo

Mesmo assim ela abriu já com um modelo selecionado, o que eu atribuí a configurações salvas de uma instalação anterior

Ou seja: nem o estado da ferramenta era o que eu achava que era

Instalei via npm porque já tinha Node na máquina, copiei o comando, colei no terminal, enter

Depois conectei a minha própria assinatura do ChatGPT Plus como provedor de modelo: a ferramenta pede pra abrir um link, abre uma aba no navegador pra autorizar, e depois dá pra fechar a janela

Na hora de conectar dá pra escolher o nível de esforço de raciocínio, e eu fiquei no médio, porque quanto mais esforço, mais token consome (e dá pra trocar depois)

Dá pra alternar entre modelos já conectados, e tem modelos gratuitos de curadoria da equipe da ferramenta

Sobre esses gratuitos eu levantei a ressalva no vídeo: provavelmente você está compartilhando prompts e resultados, e eu disse abertamente que não li como isso funciona

Não vou fingir que li

Mas o pedaço que interessa pra este post é o primeiro teste que eu fiz

Não foi um projeto, não foi um refactor bonito de gravar

Foi um prompt trivial de LEITURA DO AMBIENTE: em qual pasta a gente está e quais arquivos existem aqui

A resposta veio com o diretório correto e a informação de que não havia arquivos ou pastas visíveis naquele momento

Pra mim isso foi o sinal verde de que a instalação estava certa

Só DEPOIS desse teste bobo eu parti pro prompt de projeto real, um portfólio pessoal em HTML, CSS e JavaScript, pra avaliar o desempenho em código

E é essa a ordem que eu recomendo em qualquer agente de terminal, o Claude Code incluído: pergunte primeiro algo cuja resposta você já sabe conferir com os próprios olhos

Se ele erra o trivial verificável, não é em cima da resposta complexa (que você NÃO consegue conferir) que você vai descobrir

Duas outras coisas que eu bati na tecla lá e valem aqui

A primeira: separar modo de planejamento de modo de construção muda o jogo, porque evita sair codando direto sem plano

A segunda: documentação oficial é a fonte fiel de informação, acima da perspectiva de qualquer usuário (inclusive a minha)

Eu falo o que vi, a doc fala o que é

Leia o site oficial antes de sair usando, sempre

Essa desconfiança calibrada também é o que separa quem usa a ferramenta com segurança de quem só torce pra dar certo, e vale mais ainda pra quem está começando sem base de programação, porque aí a resposta genérica é ainda mais difícil de flagrar

Quando exigir leitura e quando deixar o Claude Code responder direto

Agora o outro lado, porque exigir leitura em TODA pergunta custa tempo e contexto à toa

Se você referencia meio projeto pra perguntar o que faz um useEffect, você está queimando contexto que vai fazer falta depois

A régua mental é essa: a resposta depende do SEU código ou depende do mundo?

Se depende do seu código, sem leitura ela é chute com sotaque de certeza

Se depende do mundo, exigir leitura só deixa tudo mais lento

Conclusão

Quando bater aquela sensação de que o Claude Code não lê os arquivos, você não precisa adivinhar

Tem três checagens que resolvem quase tudo:

1. Transcript: Ctrl+O e olhe se existiu chamada de leitura antes da resposta
2. /context: veja o que está ocupando o contexto da sessão antes de culpar o modelo
3. Citação de caminho real: se a resposta não nomeia arquivo do seu projeto, trate como hipótese, não como diagnóstico

E o próximo passo concreto, pra fazer hoje ainda: abra a próxima sessão em plan mode com claude --permission-mode plan e confira o transcript UMA vez antes de aceitar qualquer edição

Uma vez só já te mostra o padrão de comportamento dele no seu projeto

Depois disso você para de desconfiar no escuro e passa a desconfiar com prova, que é bem diferente 😀

até o próximo post!