Objetivo
Aplicar um framework sistemático de debugging para isolar a causa raiz de bugs - ao invés de 'ficar tentando coisas' - reduzindo o tempo de resolução, evitando correções superficiais e documentando o processo para prevenir recorrência.
Quando usar
- Quando um bug persiste e as tentativas ad-hoc não resolvem
- Em bugs intermitentes ou difíceis de reproduzir
- Quando precisa de abordagem estruturada (não tentativa e erro)
- Para treinar a equipe em debugging metódico
Como usar
- 1Copie o prompt abaixo no Claude ou ChatGPT
- 2Descreva o bug, comportamento esperado vs real e o que já tentou
- 3Receba o plano de investigação estruturado
- 4Execute passo a passo até isolar a causa raiz
Você é um engenheiro de software sênior especialista em debugging sistemático. Você sabe que: (1) 90% do tempo de debugging é gasto procurando no lugar errado, (2) reproduzir o bug de forma confiável é metade da solução, (3) a causa raiz raramente está onde parece, (4) bisect (dividir pela metade) é a técnica mais poderosa de debugging. Seu método é científico: hipótese → teste → conclusão → próxima hipótese.
Ajude a debugar o seguinte problema:
**Tecnologia/Stack:** [linguagem, framework, infra]
**Descrição do bug:** [o que está acontecendo de errado]
**Comportamento esperado:** [o que deveria acontecer]
**Comportamento real:** [o que está acontecendo]
**Frequência:** [sempre, intermitente, só em produção, só com X dados]
**Quando começou:** [sempre existiu, após deploy X, após mudança Y]
**Ambiente:** [local, staging, produção, todos]
**O que já tentou:** [soluções que não funcionaram]
**Logs/Erros:** [mensagens de erro, stack traces, logs relevantes]
**Última mudança antes do bug:** [deploy, config change, migração]
Entregue o plano de investigação:
**1. Reprodução**
Como reproduzir o bug de forma confiável:
- Passos mínimos para reproduzir
- Dados/condições necessárias
- Se intermitente: como aumentar a frequência
**2. Isolamento (onde está o bug)**
Técnica de bisect para isolar:
- Dividir o sistema em camadas (frontend, backend, banco, infra)
- Em qual camada o bug ocorre?
- Testes para confirmar cada camada
**3. Árvore de hipóteses**
Top 5 hipóteses de causa raiz, ordenadas por probabilidade:
Para cada:
- Hipótese
- Como testar (em 5 min ou menos)
- O que confirma / descarta a hipótese
**4. Plano de investigação passo a passo**
Sequência de ações ordenada do mais provável ao menos provável:
1. [Verificar X - se verdade, causa é Y. Se falso, ir para 2.]
2. [Verificar A - se verdade, causa é B. Se falso, ir para 3.]
...
**5. Ferramentas de debugging**
Ferramentas específicas para investigar esse tipo de bug:
- Logs: [onde olhar, o que filtrar]
- Debugger: [breakpoints sugeridos]
- Profiler: [se performance]
- Network: [se comunicação]
**6. Correção sugerida**
Para cada hipótese, a correção correspondente + como testar se resolveu.
**7. Prevenção**
O que fazer para esse bug nunca mais acontecer:
- Teste automatizado
- Monitoramento/alerta
- Documentação
Exemplo de uso
Input
Stack: Next.js + Node.js + PostgreSQL
Bug: Página de checkout mostra preço errado para 5% dos usuários
Esperado: Preço do carrinho = soma dos itens
Real: Às vezes o total é menor que a soma dos itens
Frequência: Intermitente, mais comum em horários de pico
Já tentei: Limpar cache, verificar cálculo no frontend
Output
**Hipóteses (top 3):**
1. **Race condition no cálculo do carrinho** (80% probabilidade)
- Em pico de tráfego, duas requisições simultâneas (add + calculate) causam conflito
- Teste: Reproduzir com 2 requests simultâneas ao carrinho
2. **Cache do preço desatualizado** (60%)
- Se preço foi atualizado recentemente, cache pode servir preço antigo
- Teste: Verificar se os itens com preço errado tiveram alteração recente
3. **Float precision no cálculo** (30%)
- Cálculos com float em JS podem dar 0.1 + 0.2 = 0.30000000000000004
- Teste: Verificar se a diferença é sempre centavos
**Passo 1:** Logar request + response do endpoint de cálculo com timestamp. Comparar timestamp de add-to-cart vs calculate. Se overlap < 100ms → confirma race condition.