Debugging Sistemático
Toda vez que um bug for identificado, siga rigorosamente estas 5 etapas, nesta ordem. Não pule etapas, mesmo que a causa pareça óbvia — bugs "óbvios" são a principal fonte de correções superficiais que escondem a causa raiz.
As 5 Etapas Obrigatórias
1. Reproduzir o Bug
Antes de tocar em qualquer código, reproduza o bug de forma confiável.
- Determine os passos exatos, inputs e condições que disparam o bug.
- Rode a aplicação (ou o trecho relevante) e confirme que o comportamento incorreto acontece consistentemente.
- Se não for possível reproduzir, pare aqui e colete mais informações (logs, stack traces, versão, ambiente, dados de entrada) antes de prosseguir. Nunca corrija um bug que não foi reproduzido.
- Anote o comportamento esperado vs. o comportamento observado.
2. Identificar a Causa Raiz
Não confunda sintoma com causa.
- Investigue de trás para frente: comece no ponto onde o erro se manifesta (stack trace, log, output incorreto) e vá subindo até a origem real do problema.
- Use debugger, prints/logs temporários, bisect de commits (
git bisect), ou leitura cuidadosa do fluxo de dados — o que for mais apropriado ao contexto.
- Pergunte repetidamente "por quê" até chegar na causa estrutural (ex: não é "a variável estava null", é "a função X não valida o input antes de Y").
- Documente a causa raiz em uma frase clara antes de seguir para a correção. Se você não consegue explicar a causa raiz em uma frase, ainda não a encontrou.
3. Corrigir a Causa Raiz
- Corrija a causa identificada na etapa 2 — não o sintoma.
- Evite correções que só tratam o caso específico reproduzido (ex: um
if especial para aquele input); prefira corrigir a lógica subjacente que permite a classe inteira do problema.
- Aplique os princípios de YAGNI/KISS/DRY: a correção deve ser o mínimo necessário para resolver a causa raiz, sem introduzir complexidade ou abstrações não solicitadas.
- Se a correção da causa raiz for arriscada ou grande demais para o momento, isso é um sinal para discutir com o usuário antes de prosseguir — não para aplicar um workaround silencioso.
4. Testar o Bug (Testes Unitários)
- Escreva um teste unitário que reproduza o bug original e falhe sem a correção.
- Rode esse teste contra o código corrigido e confirme que ele passa.
- Rode a suíte de testes existente completa para garantir que a correção não quebrou nada mais (regressão).
- O teste do bug deve ficar no repositório permanentemente — ele é a prova de que o bug não vai voltar silenciosamente.
5. Validar os Testes
- Revise se o teste escrito na etapa 4 realmente testa a causa raiz, e não apenas o sintoma superficial.
- Confirme que o teste falha corretamente se a correção for revertida (teste do teste: comente a correção e veja o teste falhar).
- Confirme que os testes são determinísticos (sem flakiness) e legíveis para quem for revisar depois.
- Só considere o bug fechado depois que todas as etapas acima estiverem confirmadas.
Regras Gerais
- Nunca pule da etapa 1 direto para a 3. Corrigir sem reproduzir e sem identificar a causa raiz é a forma mais comum de introduzir bugs novos ou mascarar o problema original.
- Se em algum momento a causa raiz parecer incerta, volte para a etapa 2 antes de continuar.
- Sempre comunique ao usuário, de forma breve, qual foi a causa raiz identificada antes de aplicar a correção — isso evita corrigir o problema errado.
- Ao final, resuma as 5 etapas realizadas de forma objetiva (o que foi reproduzido, qual a causa raiz, o que foi corrigido, qual teste foi criado, como foi validado).
1---2name: debugging-sistematico3description: Use esta skill sempre que um bug, erro, comportamento inesperado, falha ou exceção for encontrado em qualquer aplicação — seja reportado pelo usuário, encontrado em logs, em testes, ou observado durante desenvolvimento. Aplique também quando o usuário pedir para "corrigir um bug", "investigar um erro", "consertar isso", "por que está falhando", ou similar. Esta skill impõe um processo obrigatório de 5 etapas (Reproduzir → Identificar Causa Raiz → Corrigir Causa Raiz → Testar com Testes Unitários → Validar os Testes) e proíbe pular direto para uma correção sem antes reproduzir e entender a causa raiz do problema. Não é uma skill de escrita de código genérica — é especificamente sobre o processo de diagnóstico e correção de bugs.4---56# Debugging Sistemático78Toda vez que um bug for identificado, siga rigorosamente estas 5 etapas, nesta ordem. Não pule etapas, mesmo que a causa pareça óbvia — bugs "óbvios" são a principal fonte de correções superficiais que escondem a causa raiz.910## As 5 Etapas Obrigatórias1112### 1. Reproduzir o Bug1314Antes de tocar em qualquer código, reproduza o bug de forma confiável.1516- Determine os passos exatos, inputs e condições que disparam o bug.17- Rode a aplicação (ou o trecho relevante) e confirme que o comportamento incorreto acontece consistentemente.18- Se não for possível reproduzir, pare aqui e colete mais informações (logs, stack traces, versão, ambiente, dados de entrada) antes de prosseguir. **Nunca corrija um bug que não foi reproduzido.**19- Anote o comportamento esperado vs. o comportamento observado.2021### 2. Identificar a Causa Raiz2223Não confunda sintoma com causa.2425- Investigue de trás para frente: comece no ponto onde o erro se manifesta (stack trace, log, output incorreto) e vá subindo até a origem real do problema.26- Use debugger, prints/logs temporários, bisect de commits (`git bisect`), ou leitura cuidadosa do fluxo de dados — o que for mais apropriado ao contexto.27- Pergunte repetidamente "por quê" até chegar na causa estrutural (ex: não é "a variável estava null", é "a função X não valida o input antes de Y").28- Documente a causa raiz em uma frase clara antes de seguir para a correção. Se você não consegue explicar a causa raiz em uma frase, ainda não a encontrou.2930### 3. Corrigir a Causa Raiz3132- Corrija a causa identificada na etapa 2 — não o sintoma.33- Evite correções que só tratam o caso específico reproduzido (ex: um `if` especial para aquele input); prefira corrigir a lógica subjacente que permite a classe inteira do problema.34- Aplique os princípios de YAGNI/KISS/DRY: a correção deve ser o mínimo necessário para resolver a causa raiz, sem introduzir complexidade ou abstrações não solicitadas.35- Se a correção da causa raiz for arriscada ou grande demais para o momento, isso é um sinal para discutir com o usuário antes de prosseguir — não para aplicar um workaround silencioso.3637### 4. Testar o Bug (Testes Unitários)3839- Escreva um teste unitário que reproduza o bug original e falhe sem a correção.40- Rode esse teste contra o código corrigido e confirme que ele passa.41- Rode a suíte de testes existente completa para garantir que a correção não quebrou nada mais (regressão).42- O teste do bug deve ficar no repositório permanentemente — ele é a prova de que o bug não vai voltar silenciosamente.4344### 5. Validar os Testes4546- Revise se o teste escrito na etapa 4 realmente testa a causa raiz, e não apenas o sintoma superficial.47- Confirme que o teste falha corretamente se a correção for revertida (teste do teste: comente a correção e veja o teste falhar).48- Confirme que os testes são determinísticos (sem flakiness) e legíveis para quem for revisar depois.49- Só considere o bug fechado depois que todas as etapas acima estiverem confirmadas.5051## Regras Gerais5253- **Nunca pule da etapa 1 direto para a 3.** Corrigir sem reproduzir e sem identificar a causa raiz é a forma mais comum de introduzir bugs novos ou mascarar o problema original.54- Se em algum momento a causa raiz parecer incerta, volte para a etapa 2 antes de continuar.55- Sempre comunique ao usuário, de forma breve, qual foi a causa raiz identificada antes de aplicar a correção — isso evita corrigir o problema errado.56- Ao final, resuma as 5 etapas realizadas de forma objetiva (o que foi reproduzido, qual a causa raiz, o que foi corrigido, qual teste foi criado, como foi validado).
Just1cup