Como reportar um bug para o Claude Code: o que colocar no prompt

Fala aí, beleza? Deu erro no projeto, você seleciona o terminal inteiro, joga no prompt e escreve "corrija esse erro"

Funcionou? Às vezes

Mas colar um erro seco e entregar um relato completo são duas coisas bem diferentes na prática

O erro seco faz o Claude adivinhar: ele chuta uma causa, edita um arquivo, você diz que continua quebrado, ele chuta de novo

O relato completo elimina esses chutes antes de começar, porque ele já sabe o que acontece, como reproduzir e o que você esperava que acontecesse

Aqui eu vou montar o checklist item a item, explicando POR QUE cada pedaço corta uma rodada de tentativa e erro

O que ter em mãos antes de abrir o prompt

Antes de digitar qualquer coisa, junta o material bruto

A documentação de boas práticas do Claude Code recomenda colar erros, logs, screenshots e saída de plano direto no prompt, ou digitar @ para referenciar um arquivo

O motivo é simples: assim ele lê a fonte, e não a sua descrição da fonte

Sua lista de coleta:

• Stack trace completo, não resumido. O material de suporte da Anthropic é direto nisso: nome de arquivo, número da linha e mensagem exatos permitem localizar o ponto certo rapidamente
• Log bruto, quando o erro não tem um stack trace limpo. A orientação é colar qualquer saída de log disponível, e o Claude Code reconstrói a falha pelo contexto
• Screenshot, quando o bug é visual e você não tem mensagem nenhuma
• Os caminhos dos arquivos suspeitos, pra referenciar com @ na hora do prompt

E se o log tá num arquivo? Dá pra mandar o conteúdo direto por pipe no terminal:

cat error.log | claude

O padrão de debug do Claude Code é disparado de duas formas: você cola a mensagem de erro OU descreve o sintoma

Formação Recomendada

Formação Claude Code

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

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

A partir daí ele rastreia o problema pelo código, identifica a causa raiz e implementa a correção

Ou seja: sem erro em mãos, ainda dá pra reportar bug no Claude Code. O sintoma bem descrito já serve de gatilho 😀

(se você usa o app de desktop e ficou na dúvida sobre o que sai do seu computador quando anexa arquivo ou conecta uma pasta, já escrevi sobre isso por aqui)

Como montar o prompt de bug passo a passo

A ordem abaixo é a que eu uso pra montar o prompt sem esquecer nada

Cada passo tem o porquê e o erro comum que mata aquele passo

1. Descreva o sintoma específico, não uma frase genérica

A documentação usa exatamente este contraste como exemplo: em vez de "fix the bug", use "fix the login bug where users see a blank screen after entering wrong credentials"

Por que corta rodada: a frase genérica obriga o Claude a descobrir primeiro QUAL bug você quer resolver, e essa descoberta é uma rodada inteira de leitura de arquivo

O erro comum deste passo: escrever "tá dando erro no login" e achar que isso é específico. Especificidade é o que o usuário FAZ e o que ele VÊ

2. Cole o erro, o stack trace ou o log bruto no prompt

Colado, não parafraseado

Por que corta rodada: a mensagem exata e o número da linha apontam o lugar. Sua descrição do erro aponta pro seu entendimento do erro, que pode estar errado

O erro comum deste passo: resumir com as próprias palavras ("deu um erro de undefined lá no service") e apagar justamente o dado que localizaria o ponto

Tem um detalhe aqui que merece nuance, e eu volto nele lá na seção sobre contexto cheio: o suporte recomenda o stack trace COMPLETO, e a minha prática é colar o topo do erro sem editar nada e mandar o resto se ele pedir. Os dois convivem porque nenhum dos dois parafraseia

3. Escreva os passos para reproduzir

Numerados, do jeito que você faz na tela:

Passos:
1. rodar npm run dev
2. abrir /login
3. digitar senha errada e enviar
4. tela fica em branco, sem mensagem

Por que corta rodada: reprodução é o que permite ele CONFERIR a hipótese em vez de só propor uma. Sem isso, toda correção é no escuro

O erro comum deste passo: escrever "às vezes acontece". Se é intermitente, diga o que muda entre a vez que quebra e a vez que não quebra

4. Separe o que você esperava do que aconteceu

Duas linhas, sem mistério:

Esperado: mensagem "credenciais inválidas" abaixo do formulário
Aconteceu: tela em branco, formulário some, nenhum log no console

Por que corta rodada: sem isso, o Claude adota a interpretação DELE do comportamento correto. Aí ele "conserta" pro lugar errado e você perde uma rodada só pra dizer "não era isso"

O erro comum deste passo: descrever só o que quebrou e deixar o comportamento correto implícito na sua cabeça

Só um aviso honesto: esses dois rótulos não são um formato oficial da documentação, é boa prática derivada da orientação de ser específico e de colar material bruto

5. Conte onde você já olhou e o que já descartou

Por que corta rodada: isso apaga do mapa os caminhos que já foram testados. É a diferença entre ele investigar várias hipóteses ou investigar uma

O erro comum deste passo: guardar essa informação pra si porque "não deu em nada". Não deu em nada É informação, e das boas

6. Aponte os arquivos com @ em vez de descrever

@src/auth/login-service.ts @src/components/LoginForm.tsx

Por que corta rodada: referenciando o arquivo, ele lê o código de verdade. Descrevendo, ele lê a sua memória do código

O erro comum deste passo: apontar um monte de arquivo "por garantia". Cada arquivo lido entra na janela de contexto e cobra o seu preço, então aponte os suspeitos, não a pasta inteira

7. Aperte Shift+Tab duas vezes e peça o plano antes das edições

O Shift+Tab cicla os modos de permissão do Claude Code (default, acceptEdits, plan e outros que estejam habilitados)

A própria Anthropic recomenda apertar Shift+Tab duas vezes pra entrar no modo de plano e revisar antes que aquilo vire um diff grande

Por que corta rodada: mal-entendido aparece no plano em poucas linhas, não num monte de arquivo alterado

O erro comum deste passo: deixar ele sair editando direto porque "é um bug pequeno". Bug pequeno com diagnóstico errado vira refatoração não pedida, e aí a rodada que você economizou volta em dobro

Esse mesmo hábito de pedir explicação em vez de resposta pronta ajuda muito quando o código é de outra pessoa e você ainda tá entendendo o terreno

Juntando tudo, o prompt fica assim:

Bug: ao enviar credenciais erradas em /login, a tela fica em branco
em vez de mostrar a mensagem de erro

Passos:
1. npm run dev
2. abrir /login
3. enviar senha errada

Esperado: mensagem "credenciais inválidas" abaixo do formulário
Aconteceu: tela em branco, formulário some, nada no console

Erro do terminal:
<cole aqui a mensagem e o arquivo onde estourou>

Já olhei: o handler do submit e a rota da API, ambos respondem 401
como esperado. Não olhei o tratamento de erro no client ainda

@src/auth/login-service.ts @src/components/LoginForm.tsx

Me dê o plano antes de editar

Legal né? É o mesmo esqueleto sempre, muda só o recheio 🙂

Como adaptar o prompt para cada tipo de bug

Nem todo bug chega do mesmo jeito, então a peça principal do prompt muda

Dois casos merecem comentário

Erro sem stack trace limpo: a orientação oficial é colar qualquer saída de log que você tenha, porque o Claude Code reconstrói a falha pelo contexto. Não fique tentando montar um relatório bonitinho, cola o log como ele saiu

Bug de comportamento sem erro nenhum: aqui o relato de reprodução vira a estrela do prompt. Não existe mensagem pra colar, então o que localiza o problema é a sequência de passos mais o par esperado/aconteceu

Na prática o prompt vira isso: passo, passo, passo, esperado, aconteceu. Essa sequência é o que substitui o stack trace que não existe, e é ela que dá pro Claude algo pra conferir em vez de só teorizar

Bug que volta sempre igual: isso não é bug de código, é falta de regra

O CLAUDE.md é um arquivo markdown que o Claude lê automaticamente no início de cada sessão naquele diretório

E o sinal de que falta uma regra ali é exatamente esse: quando ele erra a mesma coisa duas vezes

Se quiser mais moldes de prompt pro dia a dia (explorar código desconhecido, depurar, refatorar, escrever testes, abrir PR), a página Common workflows da documentação é a referência oficial

O que aprendi reportando bug com o contexto cheio

Agora a parte que eu vivo na pele

Meu incômodo concreto foi esse: as sessões estavam durando menos e a cota sendo consumida de forma agressiva

Isso me fez montar uma lista de práticas pra gastar menos token, e o relato de bug apareceu como um dos maiores vilões

O hábito que eu vejo com MUITA frequência (e mostro no vídeo abaixo com um repositório aberto na tela): deu erro, o cara copia o bloco inteiro do terminal e cola com um "corrija este erro"

Vão junto um monte de linha que não ajuda em nada

Na minha prática, a parte inicial do erro (a mensagem e o arquivo onde estourou) já costuma ser suficiente pro Claude resolver na maioria dos casos

O caminho de arquivos que o código percorreu até chegar no erro raramente precisa ir junto

E aqui tem a tal nuance que eu prometi lá no passo 2: o suporte recomenda o stack trace completo em vez de resumido, e eu concordo com o espírito da regra, que é NÃO parafrasear

A diferença é onde você corta: parafrasear apaga o dado que localiza o ponto, cortar o rastro depois da linha que estourou não apaga nada essencial

Ou seja, resumo escrito por você tá fora em qualquer cenário. O que vai pro prompt é texto do erro, cru, sem uma vírgula editada. A única escolha que sobra é quanto do rastro vai junto

Minha regra de bolso: cola o topo do erro inteiro, do jeito que saiu. Se ele pedir mais, você cola o resto na hora

E se o bug for daqueles cabeludos, com stack trace apontando pra dentro de biblioteca, aí vai o trace completo mesmo, sem dó. Na dúvida, completo sempre ganha do resumido

Porque tudo que você cola vira input que o modelo tem que interpretar, então log gigante colado por reflexo é token queimado sem retorno

O outro aprendizado é sobre O ONDE você reporta, não o que

A janela de contexto guarda a conversa inteira: cada mensagem, cada arquivo lido e cada saída de comando

Conforme ela enche, o desempenho piora e o Claude pode esquecer instruções anteriores

Ou seja: relato de bug jogado no fim de uma sessão longuíssima nasce com desvantagem

O que eu passei a fazer é abrir o bug em sessão limpa

O /clear começa a tarefa do zero mantendo a memória do projeto, então você não perde o CLAUDE.md, perde só o entulho

E o /context mostra o que realmente foi carregado na sessão, junto com /doctor, /hooks e /mcp

Sobre contexto de projeto, é o mesmo raciocínio do CLAUDE.md enxuto: sem ele, o Claude sai vasculhando arquivos pra descobrir os padrões do projeto e queima token nessas idas e voltas

Quando o prompt de bug não resolve: o que fazer

Às vezes o relato tá completo e mesmo assim a coisa desanda

Três cenários e a saída de cada um

Ele foi pro caminho errado e mexeu demais

Sintoma: você pediu uma correção pontual e voltou um diff que você nem reconhece

Causa: hipótese errada seguida de edição direta, sem plano no meio

Saída: o Claude Code salva checkpoints e tem menu de rewind. Chame com /rewind, ou aperte Esc duas vezes com o campo de prompt vazio

Dá pra restaurar a conversa, o código, os dois, ou resumir a partir de uma mensagem específica

Cada prompt enviado cria um checkpoint, e ele tira um snapshot dos arquivos antes de cada alteração

Tome cuidado! Os checkpoints só rastreiam mudanças feitas pelas ferramentas de edição de arquivo do Claude

Alteração feita por comando Bash ou por processo externo NÃO é capturada, e o recurso não substitui o git

Ou seja: rewind é rede de segurança, commit continua sendo commit

As respostas foram piorando dentro da mesma sessão

Sintoma: ele começou bem e agora ignora instrução que você deu lá atrás

Causa: contexto cheio. A janela guardou tudo e a qualidade caiu junto

Saída: /clear e reabrir o bug do zero, com o checklist na mão. A memória do projeto continua lá

O bug é do próprio Claude Code, não do seu projeto

Sintoma: não é o seu código que quebra, é a ferramenta que não instala, não roda, ou se comporta de forma estranha

Saída: existem comandos dedicados a diagnosticar problemas de instalação e execução, o /doctor e o /debug

E atenção nessa confusão clássica: o /bug é um alias de /feedback

Ele serve pra mandar feedback sobre o PRÓPRIO Claude Code, não pra pedir a correção de um bug do seu projeto

Bug da ferramenta também pode virar issue no repositório anthropics/claude-code no GitHub

E como prevenir tudo isso? Sessão limpa pro bug, plano antes do diff, e regra no CLAUDE.md sempre que o mesmo erro aparecer duas vezes

Conclusão

Recapitulando o que importa

O que corta rodada de tentativa e erro não é prompt esperto, é relato completo

Sintoma específico no lugar de frase genérica, erro colado no lugar de erro parafraseado, passos para reproduzir, esperado versus aconteceu, onde você já olhou e os arquivos apontados com @

Depois disso, Shift+Tab duas vezes e o plano antes das edições

E a nuance do stack trace, pra não ficar dúvida: nunca resuma com as suas palavras. Cola texto de erro cru, começando pelo topo, e completa com o resto quando ele pedir ou quando o rastro for parte do problema

Próximo passo prático: salva esse esqueleto num arquivo seu e usa ele no próximo bug que aparecer

Começa pela sessão limpa com /clear, cola o topo do erro e pede o plano antes do diff

Você vai sentir a diferença já na primeira resposta =)

Até o próximo post!