# Debugging Sistematico

> 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.

- Skill: `just1cup/debugging-sistematico` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add just1cup/debugging-sistematico`
- Raw SKILL.md: https://api.skillmd.com/api/skills/just1cup/debugging-sistematico/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Just1cup (https://skillmd.com/u/just1cup)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/just1cup/debugging-sistematico

---


# 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).