Como investigar um bug em produção com o Claude Code sem sair chutando correção

Fala aí, beleza? Bug estourou em produção e o reflexo é sempre o mesmo: copiar o stack trace, colar no Claude Code e escrever "conserta isso"

Aí vem o remendo

Só que quase sempre em cima do lugar errado, porque ninguém chegou a entender o caminho do código: olhou a última linha que quebrou e tratou o sintoma

Bug em produção tem pressa, e a pressa é EXATAMENTE o que faz o Claude Code editar arquivo antes de investigar

Então aqui vai um roteiro de investigação onde a correção é a última etapa, não a primeira

Bora?

O que ter em mãos antes de abrir o Claude Code

Investigação sem material é adivinhação com sotaque técnico 🙂

Do teu lado, junta isso aqui:

• O sintoma em comportamento observável, não em suposição: "a listagem mostra o nome antigo depois do salvamento", e não "o cache quebrou"
• Logs e stack trace do ambiente de produção, do período do problema
• A janela de tempo em que a coisa começou (isso vale ouro na hora de perguntar o que mudou)
• O repositório aberto na mesma versão que está no ar, senão tu investiga um código que ninguém está rodando

Do lado do Claude Code:

• Um CLAUDE.md do projeto: ele é lido no início de cada sessão e entra no system prompt da conversa. O /init faz o Claude examinar o código e gerar esse arquivo, e o /memory lista os arquivos de memória nos escopos de usuário e de projeto, criando se ainda não existir
• Uma sessão limpa com /clear, pra investigação não herdar contexto de outra tarefa
• A consciência de que o checkpointing captura o estado do código antes de cada prompt teu, que é a rede de segurança do último passo

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

E um aviso honesto antes de começar…

A própria Anthropic reconhece que muitos problemas de produção só acontecem sob condições específicas, combinando carga do sistema, comportamento de terceiros e dados reais de usuário, coisa que ambiente de staging não replica

Ou seja: o alvo aqui é evidência, não necessariamente reprodução local

Passo a passo: do sintoma à correção sem chutar

A lógica é simples: cada passo tem que produzir uma evidência, e a correção só nasce quando as evidências apontam pro mesmo lugar

1. Abra a sessão limpa e trave o modo somente leitura

Começa com /clear, que zera o histórico mantendo a memória do projeto

Depois cicla os modos de permissão com Shift+Tab na CLI do Claude Code até cair no plan mode

Os modos disponíveis são default, acceptEdits, plan, auto e dontAsk

No plan mode ele lê arquivos e roda comandos de exploração, escreve um plano, mas não edita o código-fonte: as edições ficam bloqueadas até você aprovar

O erro comum deste passo: começar num modo que aceita edição e deixar o Claude "consertar" enquanto ele ainda está lendo

2. Descreva o sintoma em fato observável, sem embutir a sua teoria

   Sintoma em produção: depois de salvar o formulário de perfil, a listagem
   continua mostrando o nome antigo por alguns minutos.
   Começou ontem por volta das 14h.
   Não quero correção ainda, quero entender o caminho do código.

O erro comum deste passo: escrever "o cache está quebrado" no lugar de "a página retorna dado antigo depois do salvamento". Sua teoria vira a hipótese número 1 do modelo, e a investigação já nasce enviesada

3. Cole os logs e peça causas-raiz ranqueadas por probabilidade

Esse formato é sugerido pela própria Anthropic: a partir do log, apontar o serviço, a mudança de configuração ou o caminho de código responsável

   Segue o log do período.
   Liste as causas-raiz mais prováveis, ranqueadas por probabilidade, dizendo em
   cada uma se o responsável é um serviço, uma mudança de configuração ou um
   caminho de código. Sem propor correção.

O erro comum deste passo: pedir a correção junto. O ranqueamento vira enfeite e ele pula direto pro patch

4. Mapeie o caminho do código, arquivo por arquivo

Agora a pergunta é a rota: do ponto onde o sintoma aparece até a origem do dado, com trecho citado em cada parada

   Trace o caminho do sintoma até a origem do dado.
   Para cada etapa: arquivo, linha e o trecho real citado.
   Se você não abriu o arquivo, diga que não abriu.

O erro comum deste passo: aceitar nome de função sem o arquivo aberto. Nome bonito de função é onde mora o chute mais convincente 😀

5. Delegue a varredura pesada a um subagente

Subagente é uma instância isolada do Claude, com janela de contexto própria: ele recebe a tarefa, executa e devolve só o resultado, deixando as chamadas de ferramenta e os passos intermediários lá dentro

O Claude Code já traz os nativos Explore e Plan, então dá pra usar sem montar nada

Só que se liga nisso: a janela do subagente começa VAZIA, sem a conversa do agente pai. O único canal é o texto do prompt, então caminho de arquivo, mensagem de erro e decisões já tomadas precisam ir escritos ali

   Tarefa: varrer todos os pontos que leem ou gravam o perfil do usuário.
   Contexto (não presuma nada além disso): sintoma é listagem com nome antigo
   após o salvamento; log mostra "stale read on profile"; já descartamos a
   camada de template.
   Devolva só: arquivo, linha, trecho e por que entra na lista.

O erro comum deste passo: escrever "investigue aquele bug" e o subagente não ter absolutamente nada do que vocês conversaram

6. Confronte as hipóteses antes de escolher uma

   Para cada hipótese: qual trecho de código a sustenta, e qual observação no
   log ou nos dados derrubaria ela?
   Se não houver evidência no código, escreva "sem evidência".

Hipótese que não pode ser derrubada por nenhuma observação não é hipótese, é opinião

O erro comum deste passo: parar na primeira que soa plausível, que costuma ser a mais parecida com o que você já achava no passo 2

7. Só agora aprove o plano e saia do somente leitura

O plano bom cita arquivo, linha e o que muda em cada ponto

O erro comum deste passo: aprovar plano que fala em "ajustar o tratamento de erro" sem apontar onde. Isso não é plano, é intenção

8. Se a correção piorar, volta atrás

O menu de rewind abre com /rewind ou apertando Esc duas vezes com o campo de prompt vazio

Detalhes que evitam susto: as opções de restaurar código só aparecem quando o checkpoint selecionado tem alteração de arquivo rastreada (sem edição capturada, sobra restaurar conversa, resumir e cancelar), o histórico guarda os 100 checkpoints mais recentes da sessão, e só entram arquivos editados dentro da sessão atual

Alteração manual feita fora do Claude Code, ou edição de outra sessão rodando em paralelo, normalmente não é capturada

Ah, e checkpoint não é arquivo morto eterno: ele some junto com a sessão depois de 30 dias, período configurável pelo cleanupPeriodDays

O erro comum deste passo: contar com o rewind pra desfazer o que tu mesmo editou na mão no editor ao lado

Como o roteiro muda conforme o tipo de bug

O esqueleto é o mesmo, o peso de cada passo muda bastante

No terceiro caso não existe log pra colar, e é aí que o roteiro faz mais diferença: o passo 4 e o passo 6 viram o trabalho inteiro

E tem o clássico bug intermitente que não reproduz na tua máquina de jeito nenhum

Aceita: a condição de produção pode simplesmente não ser replicável no teu ambiente, então mira em evidência no código em vez de gastar o dia perseguindo a reprodução

Agora, se o que está lento e estranho é o próprio assistente, e não o teu app, a investigação é outra história: vale entender por que o Claude Code fica lento antes de mexer no projeto

Quando a investigação sai do trilho: três padrões e como prevenir

Esses três aparecem sempre, e todos são problema de processo, não do bug

1. O Claude propõe correção antes de citar código

Sintoma: primeira resposta já vem com patch pronto e zero trecho citado

Causa: o prompt pediu solução, não diagnóstico

Solução: reformular pedindo hipóteses com evidência, cada uma amarrada a arquivo e linha

Como prevenir: trabalhar em plan mode, onde as edições ficam bloqueadas até você aprovar o plano. Modo somente leitura é guardrail de processo, não frescura

2. A resposta fica genérica e perde a pista depois de muita ida e volta

Sintoma: ele começa a repetir generalidade e esquece o que já foi descartado

Causa: contexto poluído ou resumido

Solução: reiniciar a investigação com /clear, que zera o histórico mantendo a memória do projeto, em vez de apostar no /compact, que pede um resumo da conversa e substitui o histórico por ele (processo com perda, e o que se perde costuma ser justamente o detalhe que você descartou com trabalho)

Como prevenir: registrar as conclusões da investigação FORA do chat, num arquivo mesmo, e recolar o essencial na sessão nova

3. O subagente devolve resultado que não bate com o problema

Sintoma: ele volta com uma lista bonita de arquivos que não têm nada a ver

Causa: prompt incompleto, porque o contexto do agente pai não é herdado

Solução: reescrever o prompt com caminho de arquivo, mensagem de erro e decisões já tomadas

Como prevenir: padronizar um subagente de investigação. Eles são arquivos Markdown com frontmatter YAML, guardados em .claude/agents/ (nível de projeto, compartilhado com o time) ou em ~/.claude/agents/ (nível de usuário, disponível em todos os projetos). Desde a versão 2.1.198 o /agents não abre mais assistente interativo de criação: ele imprime um lembrete pra você pedir ao Claude ou editar o diretório direto

Tome cuidado com um detalhe chato: o Claude Code não observa a pasta .claude/agents/ dentro de diretórios adicionados com --add-dir ou /add-dir, então subagente criado ou editado ali só carrega depois de reiniciar

E antes de sair copiando o subagente do vizinho, vale a mesma lógica de quando uma skill copiada de outro projeto simplesmente não funciona no seu: o que muda é o contexto do projeto, não a esperteza do modelo

O próximo passo

A inversão central é essa: o valor do debug com Claude Code não está na correção rápida, está em chegar na correção com uma hipótese sustentada por evidência no código

Correção rápida em cima de palpite é dívida com juros, tu paga de novo na semana que vem

Próximo passo prático: pega o próximo bug real e roda o roteiro inteiro em plan mode, do sintoma até o plano aprovado

Depois transforma o que funcionou em instrução no CLAUDE.md do projeto, que é lido no início de cada sessão, pra próxima investigação já começar com o método montado

Menos chute, mais evidência 😀

até o próximo post!