Como usar o Claude Code para debugar a partir do log de erro (em vez de descrever o bug)

Aquele stack trace vermelho que acabou de estourar no teu terminal já é o melhor prompt que você vai escrever hoje 😀

O material de diagnóstico está na sua mão: arquivo, linha, tipo do erro, ordem das chamadas, o comando exato que quebrou

Aí a gente faz o quê? Fecha o terminal, abre o agente e digita "tá dando erro no login, dá uma olhada"

A paráfrase joga fora tudo que o log tinha de preciso e o agente começa a investigação do zero, adivinhando onde olhar

Bora inverter isso?

O que você precisa antes de começar

Pouca coisa, e nada de PC da Nasa aqui:

• Claude Code instalado e aberto na raiz do projeto, pra ele enxergar os arquivos que o trace cita
• O comando exato que reproduz a falha (npm test, o script que subiu o servidor, a rota que estourou)
• O material bruto em mãos: stack trace do terminal, arquivo de log, saída do teste, print da tela

Um aviso antes que você tente jogar o log inteiro de um mês de produção lá dentro: o stdin canalizado pro Claude Code tem teto de 10 MB

Acima disso ele sai com erro explícito e status diferente de zero, então log gigante precisa ser recortado antes (o trecho da falha, não o arquivo inteiro)

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

Como investigar um bug a partir do log de erro, passo a passo

A documentação oficial de fluxos comuns descreve um fluxo de três passos pra corrigir bug: compartilhar o erro e o comando que reproduz, pedir recomendações de correção, e só então aplicar o fix

Eu expandi esse esqueleto com os caminhos de entrada do material, que é onde a maioria das pessoas se perde

1. Copie o erro inteiro e o comando que reproduz

O primeiro passo do fluxo oficial é literalmente informar o comando e o stack trace, no espírito do exemplo da doc: "I’m seeing an error when I run npm test"

Em português, o teu prompt fica mais ou menos assim:

Estou vendo este erro quando rodo `npm test`:

(cole aqui o stack trace INTEIRO, sem cortar nada)

O Claude Code não fica só explicando a mensagem, se liga: com o erro colado ele rastreia o problema pelo codebase, identifica a causa raiz e implementa a correção

O erro comum deste passo: resumir o trace com as próprias palavras ("deu undefined em algum lugar do auth")

As linhas que você cortou por parecerem barulho são justamente as que dizem QUAL arquivo chamou QUAL função

2. Escolha o canal de entrada certo pro material

Colar no prompt resolve o trace curto, mas nem todo material cabe no copiar e colar

As boas práticas oficiais citam o "pipe in data", que é mandar o conteúdo de um arquivo direto como contexto:

cat error.log | claude

A flag -p (ou --print) roda uma consulta única, não interativa, lendo o stdin

É o mesmo mecanismo do exemplo oficial com histórico do Git:

git log --oneline -20 | claude -p "summarize these recent commits"

Já dentro da sessão interativa, digitar @ seguido do nome do arquivo referencia e carrega aquele arquivo no contexto da conversa

O erro comum deste passo: tentar canalizar um log maior que o teto de 10 MB e levar o erro de saída na cara, achando que o problema é o agente

3. Ligue o plan mode antes de deixar ele mexer no código

Investigação e correção são momentos diferentes, e misturar os dois é o que gera aquele fix apressado no lugar errado

O Shift+Tab cicla os modos de permissão (default, acceptEdits e plan), e o /plan prefixa um único prompt

No plan mode o Claude pesquisa e propõe um plano, com as edições bloqueadas até você aprovar

Traduzindo: ele lê o teu código com o log na mão e volta com a leitura dele, sem sair editando arquivo

O erro comum deste passo: pedir a correção na primeira mensagem

Você pediu fix, ele entrega fix, mesmo que a causa raiz ainda esteja nebulosa

4. Peça algumas formas de corrigir, não A correção

O segundo passo do fluxo oficial é pedir recomendações de correção, no plural

É um detalhe pequeno que muda o resultado: com duas ou três hipóteses na mesa você compara, descarta a que não bate com o trace e escolhe conscientemente

Com uma só, você vira carimbo

O erro comum deste passo: aceitar a primeira hipótese porque ela veio bem escrita e confiante

5. Autorize a aplicação nos arquivos

Escolhida a hipótese, aí sim vem o terceiro passo: mandar aplicar nos arquivos

E peça o teste que falha ANTES do fix, do jeito que o próprio exemplo oficial de prompt específico sugere

Teste que quebra antes e passa depois é a única prova de que ele consertou o bug do log, e não outro bug qualquer

Com o fix aprovado, o passo natural é o commit, e dá pra deixar isso no colo do agente também: tem um guia aqui do blog sobre usar o Claude Code com Git

6. Se o diagnóstico virou correção errada, use o /rewind

Acontece: o agente se apega a uma pista falsa e refatora meio mundo

O Claude Code faz checkpointing automático das edições da sessão

O comando /rewind, ou Esc duas vezes com o campo de prompt vazio, abre o menu com as opções de restaurar código e conversa, só a conversa ou só o código

O erro comum deste passo: contar com o rewind pra desfazer coisa de ontem

Ele só rastreia arquivos editados dentro da sessão atual, então não é backup, é botão de desfazer

Cada tipo de material pede uma entrada diferente

O material que você tem em mãos define o caminho, e é isso que a maioria dos tutoriais esquece de dizer

Um detalhe massa do prefixo !: o Tab autocompleta a partir dos comandos ! anteriores do projeto, então o comando de reprodução vira quase um atalho depois da segunda vez

Trazendo o erro de produção pra dentro da sessão

O Sentry mantém um servidor MCP oficial que dá pra adicionar ao Claude Code:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Depois é rodar /mcp dentro do Claude Code pra autenticar a organização via OAuth

Com isso o agente lê issue, trace, span e a análise Seer direto da fonte, em vez de você ficar copiando bloco de erro do navegador pro terminal

Por que descrever o bug com suas palavras rende diagnóstico pior

O sintoma

Você descreve o problema, o agente sai vasculhando o lugar errado ou devolve uma explicação genérica sobre o tipo do erro

Parece que ele não entendeu o projeto, quando na verdade ele não recebeu o que precisava

A causa

A paráfrase apaga informação: some o arquivo, some a linha, some o tipo exato do erro, some a ordem de chamada

E a documentação descreve o funcionamento do Claude Code como um laço agêntico de três fases: reunir contexto, agir com ferramentas, verificar o resultado, repetindo até concluir

Sacou o problema? Sem o log, as primeiras voltas desse laço são gastas reconstruindo, na base da busca, aquilo que o stack trace já entregava de graça na primeira linha

A solução

As boas práticas oficiais contrastam prompt vago e prompt específico justamente num cenário de bug

O lado ruim:

fix the login bug

O lado recomendado:

users report that login fails after session timeout. check the auth flow in src/auth/,
especially token refresh. write a failing test that reproduces the issue, then fix it

Repara no que o segundo tem e o primeiro não: o comportamento observado, o caminho suspeito, o ponto específico da suspeita e o pedido de teste que falha antes da correção

Se você quiser ir mais fundo nos vários cenários de debugging com Claude Code, tem um guia completo aqui no blog

Como prevenir

Monta um template e para de pensar nisso:

Erro ao rodar: (comando exato)

(stack trace ou trecho do log, bruto)

Suspeito de: (caminho ou módulo, se você tiver palpite)

Antes de corrigir: me dê algumas hipóteses de causa raiz.
Depois escreva um teste que falhe reproduzindo o problema, e só então aplique o fix.

Quatro linhas e o agente já começa na fase certa do laço 🙂

O agente ignorou as instruções do projeto? Confira o que a sessão carregou

Às vezes o diagnóstico vem tecnicamente ok, mas fora do padrão do projeto, e a gente já sai culpando o prompt

Antes de reescrever tudo, confere o que realmente entrou na sessão:

1. /context pra ver o que foi carregado no contexto
2. /doctor pra checar a saúde da configuração
3. /hooks pra ver os hooks ativos
4. /mcp pra ver os servidores MCP conectados

São comandos de diagnóstico da própria configuração, e resolvem aquele mistério do "mas eu escrevi isso no arquivo do projeto"

Conclusão

O log bruto é o melhor prompt que você tem, e ele já está pronto antes de você digitar qualquer coisa

O resto é encanamento: escolher o canal de entrada certo pro material (colar, @arquivo, pipe, prefixo !, imagem), investigar em plan mode, pedir hipóteses no plural e só depois liberar a edição

Na próxima falha, faz o teste: copia o erro inteiro e o comando que reproduz, abre em plan mode e pede as causas possíveis antes do fix

A diferença no primeiro chute costuma ser bem grande

até o próximo post! 😀