Template de bug report para Claude Code: transforme erros vagos em correções reproduzíveis

Debugging com Claude Code começa no bug report

Se você só escreve “não funciona”, Claude Code precisa adivinhar. Um bom bug report traz sintoma, reprodução, resultado esperado, resultado real, restrições e verificação.

Use depois do runbook da primeira tarefa e junto com o template de handoff quando o contexto continuar.

Template para copiar

Objetivo:
- Bug a corrigir:
- Fora de escopo:

Ambiente:
- OS / browser / runtime:
- branch:
- comandos relacionados:

Reprodução:
1.
2.
3.

Resultado esperado:
-

Resultado real:
-

Logs ou screenshots:
-

Restrições:
- arquivos permitidos:
- arquivos proibidos:
- não enviar para serviços externos:

Verificação:
- build/test:
- URL para revisar visualmente:

Pedido para Claude Code:
Primeiro reduza a causa a 3 hipóteses. Retorne correção mínima,
arquivos tocados e passos de verificação. Não edite antes da aprovação.

Bom exemplo

Bug:
No mobile, o CTA de pricing passa da borda direita.

Reprodução:
1. Abrir /en/products/ com 390px de largura
2. Rolar até pricing card
3. A borda direita do CTA sai do viewport

Verificação:
npm.cmd run build
Screenshot Playwright em 390px

Mau exemplo

O site está estranho. Arrume.

Faltam escopo, critério de sucesso e restrições.

Checklist antes de enviar

• A reprodução leva menos de 3 minutos
• O sucesso é verificável por comando ou screenshot
• Arquivos proibidos estão claros
• Há logs, URL ou imagem

Próximo passo

Guarde comandos no cheatsheet gratuito. Para padronizar prompts de debugging, use 50 Prompt Templates. Para processo de equipe, veja consultoria.

Na prática, separe investigação e correção

O erro comum é pedir patch antes de reduzir a causa. A ordem estável é reproduzir, listar hipóteses e só então aplicar o fix mínimo. Assim cada etapa pode ser revisada.

Com este bug report, investigue sem editar ainda.
1. confirme se reproduz
2. liste 3 hipóteses
3. indique a área de código mais provável
4. diga quais arquivos ler antes do fix
5. decida se basta mudança mínima ou se precisa design

Se a resposta for “não reproduz”, “faltam logs” ou “escopo amplo demais”, não avance para o fix. Um bom bug report cria uma investigação verificável.