Identificando o Bug
Todo bug fix comeca com uma descricao clara do sintoma. Quanto mais preciso voce for ao descrever o problema para o Claude Code, mais rapido ele vai encontrar a causa raiz. Nao diga apenas "esta quebrado" — descreva o que acontece, quando acontece e o que deveria acontecer.
🎯 Conceito Principal
A qualidade do diagnostico depende diretamente da qualidade da descricao do sintoma. O Claude Code precisa de tres informacoes essenciais para iniciar uma investigacao eficaz:
- • Sintoma: O que esta acontecendo de errado? Qual e o comportamento observado? Uma mensagem de erro, um resultado incorreto, um crash, um timeout?
- • Reproducao: Quais passos reproduzem o bug? Acontece sempre ou intermitentemente? Em qual ambiente (dev, staging, producao)?
- • Expectativa: O que deveria acontecer em vez do bug? Qual e o comportamento correto esperado?
💡 Dica Pratica
Use este template para descrever bugs ao Claude Code. Ele funciona como um bug report estruturado que maximiza a chance de diagnostico correto na primeira tentativa:
Forcando Investigacao Antes do Fix
Um dos erros mais comuns e pedir ao Claude Code para "consertar o bug" sem antes investigar. Isso leva a fixes superficiais que tratam o sintoma mas nao a causa raiz. O segredo e forcar a leitura e o diagnostico antes de qualquer mudanca no codigo.
🎯 Conceito Principal
A abordagem "read first, diagnose second, fix third" e a chave para correcoes duradouras. Quando voce pede ao Claude para ler os arquivos relevantes antes de sugerir qualquer mudanca, ele constroi um modelo mental mais completo do problema.
- • Leia primeiro: Peca ao Claude para ler os arquivos relevantes e tracar a logica do fluxo onde o bug ocorre
- • Diagnostique: Peca uma explicacao da causa raiz antes de ver qualquer sugestao de fix
- • Confirme: Valide se o diagnostico faz sentido com seu conhecimento do sistema antes de autorizar mudancas
💡 Dica Pratica
Use este prompt para forcar investigacao antes do fix:
O Claude vai usar as tools Read, Grep e Glob para investigar o codebase, e so depois apresentar um diagnostico estruturado. Isso evita o padrao "chuta e reza" que gera bugs secundarios.
Colando Stack Traces Completos
Stack traces sao ouro puro para diagnostico. Cada linha do stack trace conta uma parte da historia: onde o erro aconteceu, qual funcao chamou qual, e em que ponto a execucao falhou. Nao resuma, nao corte — cole o stack trace completo.
🎯 Conceito Principal
O contexto completo do erro e o que permite ao Claude Code navegar diretamente aos arquivos e linhas relevantes. Um stack trace completo contem nomes de arquivos, numeros de linha e a cadeia de chamadas que levou ao erro.
- • Cole tudo: Stack traces completos, mensagens de erro, warnings. Nao resuma — o Claude precisa dos detalhes para encontrar o arquivo e a linha exatos
- • Inclua contexto: Qual comando voce rodou? Qual endpoint foi chamado? Qual input gerou o erro? O contexto ao redor do erro e tao importante quanto o erro em si
-
•
Use pipe: Para erros em arquivos de log, use
cat error.log | claude -p "O que esta causando estes erros?"para alimentar o Claude diretamente
💡 Dica Pratica
Ao colar um erro no Claude Code, inclua o maximo de contexto possivel. O Claude vai automaticamente usar as tools para navegar ate os arquivos mencionados no stack trace:
[cole o stack trace completo aqui]
Ajude-me a identificar e corrigir a causa raiz.
Aplicando o Fix com Seguranca
Depois de confirmar o diagnostico, e hora de aplicar a correcao. Mas um fix sem teste e uma bomba-relogio. O workflow correto e: aplicar o fix, rodar os testes existentes e, idealmente, adicionar um teste que cobre o cenario do bug para garantir que ele nunca volte.
🎯 Conceito Principal
O padrao "fix + test" e inegociavel. Toda correcao de bug deve vir acompanhada de verificacao automatizada:
- • Aplique o fix: Deixe o Claude fazer as mudancas necessarias. Revise o diff cuidadosamente antes de aceitar — preste atencao especial em efeitos colaterais
- • Rode os testes: Peca ao Claude para rodar a suite de testes completa. Se algum teste quebrar, o fix pode estar incorreto ou incompleto
- • Adicione teste de regressao: Peca ao Claude para criar um teste que reproduz o bug original e verifica que o fix resolve. Isso e sua garantia contra regressoes futuras
💡 Dica Pratica
Use este prompt para garantir que o fix inclui verificacao:
Commitando a Correcao
Com o fix aplicado e os testes passando, e hora de registrar a correcao no historico do projeto. O comando /commit do Claude Code analisa suas mudancas e gera uma mensagem de commit descritiva automaticamente.
🎯 Conceito Principal
O /commit nao e um simples git commit. Ele analisa o diff, entende o contexto das mudancas e gera uma mensagem de commit semantica que explica o "porque" da mudanca, nao apenas o "o que":
- • Analise automatica: O Claude le o diff e entende quais arquivos mudaram, quais funcoes foram alteradas e qual era o objetivo da mudanca
- • Mensagem semantica: Gera mensagens no formato convencional (fix:, feat:, refactor:) com descricao clara do que foi corrigido
- • Revisao antes de confirmar: Voce ve a mensagem gerada e pode aceitar, editar ou rejeitar antes do commit ser feito
💡 Dica Pratica
Depois de confirmar que os testes passam, simplesmente digite:
O Claude vai analisar todas as mudancas staged e unstaged, gerar uma mensagem de commit e perguntar se voce quer confirmar. E o jeito mais rapido e consistente de manter um historico de commits limpo.
Post-mortem: Aprendendo com o Bug
O bug esta corrigido, mas o trabalho nao termina ai. O passo final — e mais subestimado — e entender por que o bug existiu em primeiro lugar. Isso transforma cada bug fix em uma oportunidade de aprendizado que previne bugs futuros similares.
🎯 Conceito Principal
A analise de causa raiz (root cause analysis) responde perguntas que vao alem do fix imediato:
- • Por que o bug existiu? Foi um erro de logica, uma falta de validacao, um edge case nao considerado, ou uma mudanca em outra parte do sistema que causou efeito colateral?
- • Por que nao foi pego antes? Faltavam testes? O code review nao cobriu? A documentacao estava incompleta?
- • Como prevenir? Que regras, testes ou padroes podemos adicionar para que bugs deste tipo nunca mais passem?
💡 Dica Pratica
Apos o commit do fix, peca ao Claude uma analise post-mortem:
As respostas do Claude podem revelar gaps no seu CLAUDE.md, testes faltantes ou padroes de codigo que precisam de reforcamento. Use essas insights para atualizar a documentacao do projeto.
Exercicio Pratico
Reproduzir e corrigir bug real num repo de exemplo
Neste exercicio, voce vai aplicar o workflow completo de bug fix usando Claude Code em um projeto real.
Clone um repo com bugs conhecidos
Escolha qualquer projeto open source que tenha issues abertas marcadas como "bug".
Descreva o bug para o Claude
Use o template: sintoma + reproducao + expectativa.
Force investigacao antes do fix
Peca leitura e diagnostico antes de qualquer mudanca.
Aplique o fix + rode testes + commit
Complete o ciclo: fix, teste de regressao, e /commit.
✅ Criterios de Sucesso
📋 Resumo do Modulo
Proximo Modulo:
3.2 - Workflow: Construir Feature Nova