📝 Structured Bug Report (Template Completo)
Voce ja conhece o Structured Bug Report do modulo 4.1. Agora vamos aprofundar o template completo com todas as variacoes: bugs visuais, bugs de dados, bugs de integracao e bugs de performance. Cada tipo tem nuances que mudam o diagnostico.
🎯 Conceito Principal
O template base com extensoes para tipos especificos de bug:
- •Bug type: Classificar o tipo ajuda o Claude a focar na area certa. Bugs visuais requerem inspecao de CSS/layout. Bugs de dados requerem analise de queries e transformacoes
- •Environment: Bugs que so acontecem em Safari, ou so em mobile, ou so no Windows. Essa informacao muda completamente o diagnostico
- •Reproducibility: "Sempre" e facil de debugar. "As vezes" sugere race condition ou state management. "Raro" pode ser memory leak ou edge case
💡 Dica Pratica
Para bugs visuais, descreva o layout esperado vs o atual em palavras. "O botao deveria estar alinhado a direita do container, mas aparece no centro" e muito mais util do que "o layout esta errado". Se possivel, inclua dimensoes de tela e breakpoints.
📊 Log Analysis Prompt
Logs de aplicacao podem ter centenas de linhas. O Log Analysis prompt faz o Claude parsear, agrupar e priorizar erros automaticamente. Em vez de voce ler linha por linha, ele identifica padroes, agrupa erros relacionados e aponta a causa raiz dos mais criticos.
🎯 Conceito Principal
- •Agrupamento inteligente: 50 erros de "connection refused" nao sao 50 problemas - sao 1 problema que se manifestou 50 vezes. O Claude identifica isso
- •Ranking por severidade: Critical (sistema fora do ar), High (funcionalidade quebrada), Medium (degradacao), Low (warning cosmético). Voce sabe o que atacar primeiro
- •Root cause dos criticos: O Claude nao so identifica o erro - ele traceia de volta a causa. "Connection refused em PostgreSQL indica que o pool de conexoes esgotou, provavelmente por queries N+1 no endpoint /users"
💡 Dica Pratica
Para logs muito grandes, use o Claude Code para ler os arquivos de log diretamente em vez de copiar e colar. Diga: "Read the file /var/log/app.log and analyze errors from the last hour." O Claude usa as tools Read e Grep para processar o arquivo no servidor.
🔍 Stack Trace Diagnosis
Stack traces sao a melhor pista para encontrar bugs, mas muitos desenvolvedores nao sabem le-los completamente. O Claude Code le stack traces com precisao cirurgica: identifica a linha exata do problema, navega ate o arquivo, e entende o contexto ao redor.
🎯 Conceito Principal
- •Navegacao automatica: O Claude le o stack trace, encontra os arquivos mencionados no seu projeto, e abre eles para entender o contexto. Nao precisa de nada manual
- •Contexto ao redor: Nao basta ver a linha do erro. O Claude analisa as funcoes que chamam, os dados que chegam, e as condicoes que levaram ao erro
- •Fix com explicacao: O Claude nao so corrige - explica por que o erro aconteceu e por que o fix funciona. Isso constroi entendimento para a proxima vez
💡 Dica Pratica
Sempre cole o stack trace completo, nao so a ultima linha. As linhas intermediarias mostram a cadeia de chamadas e frequentemente revelam o problema real, que pode estar muito acima da linha onde o erro efetivamente aconteceu.
👻 Intermittent Bug Prompt
Bugs que acontecem "as vezes" sao os mais dificeis de resolver. Race conditions, state leaks, cache stale, timing issues. O Intermittent Bug prompt guia o Claude a investigar as causas mais comuns de bugs nao-deterministicos.
🎯 Conceito Principal
- •Race conditions: Duas operacoes async que dependem uma da outra mas nao tem sincronizacao. O Claude procura por promisses nao-awaited, shared state sem lock, e operacoes de banco sem transacao
- •State/cache stale: Dados em cache que ficam desatualizados, state do React que nao atualiza quando deveria, localStorage com dados velhos
- •Resource exhaustion: Pool de conexoes que esgota sob carga, memory leaks que so aparecem depois de horas de uso, file descriptors que nao sao fechados
💡 Dica Pratica
Para bugs intermitentes, adicione logs temporarios antes de tentar fixes. Peca ao Claude: "Add debug logging to [area] so we can capture the state when this bug occurs next." Depois de reproduzir com logs, voce tem dados concretos para o diagnostico.
⚡ Performance Debugging
"Ta lento" nao e um bug report. Performance debugging requer metricas especificas e investigacao sistematica. O Performance Debugging prompt guia o Claude a encontrar queries N+1, gargalos de I/O, renderizacoes desnecessarias e bottlenecks de rede.
🎯 Conceito Principal
- •N+1 queries: O problema de performance mais comum. O Claude analisa o codigo e identifica loops que fazem queries individuais em vez de batch/join
- •Network waterfalls: Chamadas de API sequenciais que poderiam ser paralelas. Transformar 5 requests sequenciais em Promise.all() pode cortar o tempo em 80%
- •Metricas concretas: Sempre diga quanto tempo leva e quanto deveria levar. "500ms mas deveria ser 50ms" da ao Claude um target claro
💡 Dica Pratica
Apos o Claude identificar o gargalo, peca para ele medir o antes e depois: "Fix this performance issue and add a console.time/timeEnd to verify the improvement." Assim voce tem prova concreta de que o fix funcionou.
🚨 Production Incident Workflow
Quando algo quebra em producao, voce esta sob pressao. O Production Incident workflow e uma sequencia de prompts otimizada para diagnostico rapido sob stress. Triagem, diagnostico, fix, validacao e post-mortem - tudo estruturado.
🎯 Conceito Principal
O workflow de incidente em producao segue 5 etapas:
- •1. Triagem rapida: "Production is down. Error: [error]. Read recent changes (git log -5) and identify the most likely cause. Be fast." - Foco em velocidade, nao perfeccao
- •2. Diagnostico focado: Use o Log Analysis ou Stack Trace Diagnosis no erro especifico. Nao tente entender tudo, so a causa imediata
- •3. Fix minimo: "Fix this with the smallest possible change. No refactoring. Just stop the bleeding." - Em producao, fix minimo e rei
- •4. Validacao: "Verify this fix resolves the issue without introducing new problems." - O Claude checa side effects
- •5. Post-mortem: Depois da crise, use Teach Me para entender o que aconteceu e como prevenir no futuro
💡 Dica Pratica
Em incidentes de producao, resista a tentacao de refatorar. O Claude pode sugerir um fix elegante que muda 10 arquivos. Em producao, voce quer a mudanca de 1 linha que para o sangramento. O refactoring vem depois, na calma, com testes.
Exercicio Pratico
Diagnosticar 3 bugs usando prompts estruturados
Encontre 3 bugs no seu projeto (ou crie bugs intencionais) e diagnostique cada um com o prompt adequado:
- 1.Use o Structured Bug Report para um bug funcional (algo que nao funciona como esperado)
- 2.Use o Stack Trace Diagnosis para um erro com stack trace (um crash ou exception)
- 3.Use o Performance Debugging para identificar um gargalo (query lenta, renderizacao pesada)
✅ Criterios de Sucesso
📋 Resumo do Modulo
Proximo Modulo:
4.5 - Prompts de Code Quality e Auditoria