O erro é do Claude Code ou do seu ambiente? Como separar os dois antes de pedir a correção

Fala aí, beleza? O ciclo mais caro do vibe coding não é o modelo errar

É você mandar o agente reescrever um código que nunca foi o problema 😅

Se liga: falha de raciocínio e falha de máquina pedem respostas OPOSTAS. Quando o modelo decide errado, reprompt resolve. Quando a dependência não está lá, a versão é outra, a variável não foi pra onde você achou que foi ou o arquivo simplesmente não carregou, reprompt só queima token e bagunça o que estava certo

E não é achismo meu: a própria documentação do Claude Code separa essas classes em páginas diferentes, com Troubleshooting geral, uma página só de problemas de instalação e login, uma de debug de configuração e uma referência de mensagens de erro de runtime

Então bora aprender a triar antes de acusar o coitado do modelo

Falha de raciocínio x falha de ambiente: os sinais que separam as duas

A tabela abaixo é o atalho mental. Olha o sintoma, olha onde ele aparece, roda o comando que confirma, e só então escolhe a resposta:

Repara numa coisa: nenhuma linha da metade de cima é resolvida reescrevendo código

Você pode pedir dez refatorações seguidas que o hook continua sem disparar e o @arquivo continua sem achar nada. É outro problema, em outra camada

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

O roteiro de triagem em 5 passos antes de pedir qualquer correção

Esse é o roteiro que eu sigo antes de digitar qualquer "corrige aí". É rápido e reprodutível:

1. Rode claude doctor no terminal, fora de qualquer sessão

claude doctor

Ele imprime um diagnóstico somente leitura de instalação e configurações, e a graça é justamente essa: funciona mesmo quando o Claude Code nem inicia. O erro comum deste passo é tentar diagnosticar de dentro de uma sessão que não abre 🙂 Se o problema é mais atrás e nem o comando existe na sua máquina, o buraco é de setup e vale revisar a instalação do Claude Code pelo npm antes de continuar

2. Com a sessão aberta, rode /doctor

/doctor

Esse aqui é o completão: checa instalação, configurações, extensões e uso de contexto, e ainda PROPÕE correções, que ele aplica depois que você confirma. O erro comum é confirmar no automático sem ler o que ele vai mexer

3. Rode /context pra ver o que realmente foi carregado

/context

Ele mostra por categoria o que está ocupando a janela de contexto da sessão atual: system prompt, system tools, MCP tools, subagentes customizados com a origem de cada um, arquivos de memória, skills e as mensagens da conversa. O erro comum deste passo é achar que ele serve só pra economizar contexto. Serve pra prova: se sua skill ou seu arquivo de memória não está listado ali, ele não existe pra sessão

4. Rode /status pra saber de onde vêm as regras

/status

Ele mostra quais fontes de settings estão ativas, incluindo se settings gerenciados estão em vigor. O erro comum é assumir que a única config do mundo é a sua

5. Só agora, isole com o safe mode

claude --safe-mode

O --safe-mode inicia a sessão com as SUAS customizações desligadas: CLAUDE.md, skills, plugins, servidores MCP, comandos e agentes customizados e os hooks que você mesmo definiu ficam fora (com uma ressalva importante sobre hooks gerenciados, que eu explico logo abaixo). Autenticação, seleção de modelo, ferramentas nativas e permissões continuam funcionando normalmente, então dá pra trabalhar de verdade nesse modo. Se preferir, o mesmo comportamento sai pela variável de ambiente CLAUDE_CODE_SAFE_MODE

E aqui está a ressalva: no safe mode, hooks gerenciados e a política de settings da organização CONTINUAM valendo, enquanto plugins gerenciados, skills, CLAUDE.md e MCP ficam desligados. Ou seja, se o comportamento estranho persiste no safe mode, olhe pro que é gerenciado

E o erro comum global do roteiro? Pular direto pro passo 5

O safe mode te diz SE o problema é da sua config. Ele não te diz QUAL peça é. Quem responde isso é o /context e o /status que você pulou 😛

Sintoma: o Claude ignora sua instrução do CLAUDE.md

Você escreveu a regra, deixou em negrito, quase escreveu em caixa alta, e ele passa por cima. Aí bate aquela vontade de brigar com o modelo

A causa quase nunca é teimosia

A doc é bem direta nisso: quando o Claude ignora uma instrução ou um recurso configurado não aparece, a causa costuma ser de CARREGAMENTO, não de raciocínio

E são três possibilidades:

• o arquivo não carregou
• ele carregou, mas de um local diferente do que você imaginava
• outro arquivo sobrescreveu o seu

A solução

Rode /context e procure os arquivos de memória e as skills na listagem. Se não aparecem, pronto, você acabou de descobrir que estava reprompt em cima de uma regra que nunca chegou na sessão

Depois compare com uma sessão em claude --safe-mode. Se o comportamento é IGUAL nos dois, sua config nem estava no jogo

Como prevenir

Antes de assumir que a regra é sua, cheque /status pra ver se settings gerenciados estão em vigor. O mesmo raciocínio vale quando uma skill do Claude Code não funciona no seu projeto: primeiro você prova que ela carregou, depois discute o conteúdo dela

Sintoma: o hook que você criou simplesmente não roda

Hook é onde mais gente se ferra em silêncio, porque ele falha sem gritar. E aqui são duas causas bem diferentes, que pedem checagens diferentes

Causa 1: ele nem está sendo lido

Rode /hooks

/hooks

Esse comando lista todo hook registrado na sessão atual, agrupado por evento. Se o hook que você definiu não aparece ali, ele não está sendo lido, ponto

O tropeço clássico: hooks ficam sob a chave hooks dentro de um arquivo de settings, não em um arquivo separado. Se você criou um arquivinho só pra ele, é por isso que sumiu

Causa 2: ele aparece, mas não dispara

Aí o suspeito número um é o matcher

O campo matcher é uma única string. O | casa múltiplos nomes de ferramenta, tipo "Edit|Write", e a vírgula é equivalente: "Edit,Write" casa as mesmas ferramentas

E tome cuidado! Nome de ferramenta escrito errado faz o hook falhar em SILÊNCIO. Nada de erro vermelho na sua cara, só o vazio

A solução ao vivo

claude --debug

Com essa flag você vê a avaliação dos hooks acontecendo: o log registra cada evento, quais matchers foram checados e o exit code e a saída do hook. É o mais perto de assistir ao filme em vez de ler a sinopse

Como prevenir

Olha essa que é sacana: quando o Claude Code roda um hook, ele abre um shell que faz source do seu ~/.zshrc ou ~/.bashrc

Se você tem um echo incondicional no profile (aquele "bem vindo, dev" que você achou massa em 2021), esse texto entra ANTES do JSON do hook e contamina a saída

Sintoma: variável de ambiente configurada que parece não valer nada

Você exportou a variável, conferiu, ela está lá, e mesmo assim o comportamento é outro. Aí vem a conclusão errada: "o agente está ignorando minha chave"

A causa é precedência, não desobediência

Quando a mesma variável está definida no shell E no bloco env de um arquivo de settings, o valor do arquivo prevalece, porque o Claude Code escreve cada entrada de env no ambiente do processo, substituindo o valor herdado do shell

E tem um detalhe que pega muita gente: a precedência é decidida POR PAR, não por nível

• ANTHROPIC_MODEL exportado no shell prevalece sobre a chave model de qualquer arquivo
• ANTHROPIC_DEFAULT_MODEL só vale quando nenhum arquivo define model

Ou seja, não adianta decorar "shell ganha" ou "arquivo ganha". Depende do par

A solução

No arquivo de settings dá pra DEFINIR uma variável, mas não dá pra removê-la

Então, pra neutralizar uma variável que você não consegue apagar, define ela como string vazia no bloco env:

{
  "env": {
    "MINHA_VARIAVEL": ""
  }
}

Como prevenir

Antes de mexer em qualquer coisa, /status pra identificar quais fontes de settings estão ativas. Metade da confusão de variável morre aí

Sintoma: MCP, busca de arquivos e credenciais falhando por fora do modelo

Juntei as três aqui porque elas têm a mesma cara pro usuário ("a IA está burra hoje") e a mesma natureza real: máquina

MCP que não conecta

/mcp

Esse comando mostra cada servidor MCP configurado, o status de conexão e se você aprovou o servidor para o projeto atual. Aquele último item é o pega-ratão: o servidor existe, está de pé, e não foi aprovado pro projeto onde você está

Busca que não acha arquivo

Se a ferramenta de busca, as menções @arquivo, agentes customizados ou skills customizadas não encontram arquivos, o suspeito é o binário de ripgrep embutido não rodar no seu sistema

A solução é instalar o pacote de ripgrep da sua plataforma e definir USE_BUILTIN_RIPGREP como 0, no ambiente do shell ou no bloco env do settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

E dá pra confirmar que a troca pegou: rode claude doctor no terminal e olhe a linha Search. Ela deve mostrar o caminho do ripgrep do sistema em vez de OK (bundled)

Credencial em processo worker

Esse é ambiente puro, sem discussão. A credencial precisa estar no ambiente que LANÇA o worker, não só no seu shell interativo

Confirme que ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN ou as credenciais do seu provedor de nuvem estão setadas lá, no processo que sobe o worker

Como prevenir

Regra de bolso: todo "não encontrei o arquivo" é suspeita de ambiente até prova em contrário. Antes de reprompt, prova

Como é um erro de raciocínio de verdade: o que vi testando o Claude Code

Agora o contraponto, porque também não dá pra sair chamando tudo de ambiente

No vídeo em que eu comparo o Antigravity com o Claude Code, o teste foi um app de kanban: pedi 4 colunas no quadro, pelo menos 3 quadros iniciais e dados mocados com 4 membros do time

O Claude Code passou cerca de 5 minutos ainda na fase de planejamento, antes de começar o desenvolvimento

Cinco minutos parado te dá aquela coceira de "travou, né?". Mas não, ele estava planejando mesmo, e o resultado veio mais alinhado ao escopo que eu tinha pedido

E teve o outro lado no mesmo teste: quando fui rodar o projeto gerado, tomei uma mensagem de porta ocupada. Isso não era bug de código nem falha do modelo, era a MINHA máquina com a porta em uso. Resolvi por fora, no terminal, sem acionar a IA e sem gastar token pra isso

Separar essas duas coisas mudou meu fluxo: bug do resultado (tipo um dark mode que não funciona) vira prompt novo e específico pra correção. Atrito de execução vira comando meu, na mão

Espera longa em planejamento não é sintoma de ambiente quebrado

Instrução ignorada e arquivo não encontrado quase nunca são culpa do modelo

Decorou isso, você já economiza um monte de reprompt inútil 😀

Confirmou que é o modelo? volte no tempo em vez de empilhar prompts

Beleza, a triagem apontou mesmo pro raciocínio. O instinto é escrever "não, não era isso, refaz" e seguir empilhando. Péssima ideia: você mantém no contexto todo o caminho errado

A solução

/rewind

Ou aperte Esc duas vezes com o campo de prompt vazio

Aí você escolhe: restaurar código e conversa, só a conversa, ou só o código. E reprompt a partir de um ponto limpo, do jeito que você deveria ter pedido da primeira vez

Como prevenir o falso alívio

Aqui mora uma armadilha boa de saber antes de precisar

Os checkpoints só registram mudanças feitas pelas ferramentas de edição de arquivo do Claude. Mudança feita por comando Bash ou por processo externo NÃO é capturada

Eles também são locais da sessão, separados do git, e cobrem apenas alterações de arquivo

Ou seja: voltar no tempo limpa o código editado pelo agente, mas não desfaz o que rodou no terminal. Já dá pra imaginar o susto de quem confia demais nisso…

Conclusão

A ordem importa mais que a ferramenta: diagnosticar, isolar em safe mode, e só ENTÃO pedir correção

Na próxima sessão que der problema, faz o mínimo: /doctor pra checar instalação, configurações, extensões e uso de contexto, e /context pra ver o que realmente foi carregado. Se nem abrir a sessão der certo, claude doctor no terminal resolve o começo

E guarda as páginas oficiais separadas por classe de falha, porque isso sozinho já acelera a triagem: Troubleshooting geral, Troubleshoot installation and login (comando não encontrado, PATH, permissão, rede, autenticação), Debug your configuration (CLAUDE.md, settings, hooks, MCP e skills que não fazem efeito) e Error reference (mensagens de erro de runtime)

A de instalação e login tem versão em português, em code.claude.com/docs/pt/troubleshoot-install

Diagnosticar antes de reprompt é chato nos primeiros dois minutos e economiza horas depois

até o próximo post! =)