Corrigir um bug significa fazer um defeito reproduzível parar de se reproduzir e deixar a evidência de que ele não volta. A primeira metade é "mudar o código". A segunda é "fechar direito" — e a maioria dos times faz só a primeira, então o mesmo problema reaparece três meses depois por outra porta. A qualidade de uma correção não se mede pelo quão engenhosa foi a mudança. Mede-se por se a próxima rodada de regressão, a próxima pessoa que herdar o código e você mesmo em três meses conseguem concluir, só com o registro, que o defeito realmente sumiu.
Este artigo cobre apenas "como corrigir, como verificar, como fechar". Qual bug corrigir primeiro é assunto de triagem — veja o guia de triagem de defeitos. Como escrever um relato que possa ser corrigido está em o que um relato de bug deve conter.
O ciclo de seis passos
Cada passo tem um requisito mínimo de evidência. Se não cumprir, volte um passo em vez de avançar — é a regra mais útil daqui.
| Passo |
O que você faz |
Evidência mínima |
Se não tiver |
| 1 Ler |
Decidir se o relato dá para começar |
URL, ambiente (navegador / SO / versão), esperado versus obtido |
Devolva; não adivinhe |
| 2 Reproduzir |
Provocar o problema uma vez, você mesmo |
Uma reprodução confirmada ou um "não reproduzível" explícito |
Registre o que tentou, deixe em espera; nunca feche |
| 3 Localizar |
Descobrir qual camada está errada |
Um erro literal, uma requisição com falha ou um resultado de bissecção |
Pare de editar; adicione observabilidade |
| 4 Corrigir |
Remover a causa com a menor mudança |
Uma mudança, uma causa |
Divida o commit |
| 5 Verificar |
Provar que corrigiu e que nada mais quebrou |
Mesmo caminho + casos de borda + matriz de regressão |
"Parece bom" não é verificação |
| 6 Fechar |
Tornar legível para a próxima pessoa |
Uma linha de causa raiz + um link para a evidência |
"Corrigido" sozinho não é fechamento |
Passo 1: ler o relato e decidir se dá para começar
Um relato iniciável tem três coisas: onde, em que ambiente e em que o real difere do esperado. Faltando qualquer uma, a ação correta é devolver, não abrir o código para dar uma olhada.
O custo do "dar uma olhada" é muito subestimado. Uma parte relevante das páginas que um desenvolvedor deduz após 40 minutos de suposição não é a página que quem relatou tinha em mente. Uma devolução custa dois minutos.
Passo 2: reproduzir, ou dizer claramente que não consegue
A reprodução é a divisória. Um defeito que reproduz de forma confiável é só questão de tempo. Um que não reproduz transforma qualquer mudança em aposta.
Três coisas precisam ser fixadas na reprodução, senão você não está reproduzindo o mesmo defeito:
Estado dos dados. Qual conta, há cache envolvido, sobrou dado antigo no localStorage.
Versão do build. Bundle do front, commit do back, alguma flag ativa.
Sequência de ações. Clicou logo ao carregar, depois de alguns segundos, depois de trocar de aba, com rede lenta.
Se realmente não reproduzir, registre como "não reproduzível" junto com três perguntas, em vez de fechar:
- Em qual página e por qual entrada você estava? (A URL original costuma trazer parâmetros.)
- Está preso a uma conta, papel ou permissão específicos?
- A que horas aconteceu? (Se casar com um log ou um deploy, você tem uma pista.)
Passo 3: localizar — primeiro a camada
Correções lentas raramente são problemas difíceis; são problemas procurados na camada errada. Três movimentos reduzem a uma camada:
| Movimento |
O que você olha |
O que descarta |
| Console |
O erro literal e a pilha |
Descarta problemas "só de estilo / só de dados" |
| Painel de rede |
Qualquer 4xx / 5xx e se os corpos de requisição e resposta batem |
Separa "o front nunca enviou" de "o back devolveu algo errado" |
| Bissecção / rollback |
Qual versão ou commit funcionava por último |
Descarta "sempre foi assim" |
Ler erros: níveis de log explicados e tipos de erros em programação. Abrir o console: abrir o console do navegador. Para perfis não técnicos que querem dar uma primeira olhada: DevTools para não desenvolvedores.
Uma ordem concreta: API responde 500 → back. API responde 200 mas um campo está errado → contrato. API nunca foi chamada → lógica ou validação do front. API está bem, a interface não → renderização. Essas quatro linhas cobrem a maior parte do que acontece num time web.
Passo 4: corrigir com a menor mudança
"Menor mudança" não é cautela, é verificabilidade. Um pull request que ao mesmo tempo corrige o bug, refatora um módulo e sobe uma dependência deixa você sem saber qual das três causou o próximo problema — o que torna o passo 5 impossível.
Duas regras:
- Um commit, uma causa. Se encontrar um segundo problema durante a correção, abra um ticket separado.
- Refatoração tem tempo próprio. Fazer isso durante uma correção mistura risco conhecido com risco desconhecido.
Passo 5: verificar — provar que está corrigido, não escondido
Aqui este artigo se separa da maioria dos textos de "como corrigir bugs". As quatro práticas abaixo fazem o defeito desaparecer enquanto o problema continua:
| Prática |
Aparência |
Realidade |
try / catch vazio |
O erro sumiu |
A lógica seguinte falha em silêncio, os dados são gravados errados |
| Afrouxar a validação |
Não dá mais erro |
Dado sujo entra no banco, descoberto meses depois |
| Esconder o ponto de entrada |
O usuário não consegue mais clicar |
A necessidade continua, chega por outro caminho, o comportamento diverge |
| Uma flag que nunca é religada |
O sintoma não aparece |
A flag vira código que ninguém ousa apagar |
O único critério válido: o usuário consegue agora fazer o que queria fazer? Não "o erro sumiu".
Verificar tem três partes:
Percorrer o caminho original — exatamente o descrito no relato, do primeiro ao último passo.
Repetir as bordas — valores vazios, texto muito longo, emoji, fusos horários, valores com centavos, conta sem permissão. É aí que a reincidência mora.
Rodar a matriz de regressão — qual funcionalidade antiga essa mudança pode ter tocado, conforme como executar testes de regressão.
Passo 6: fechar com uma linha de causa raiz
Fechar um defeito com "corrigido" empurra o custo para a próxima pessoa. Uma nota de causa raiz completa tem três partes:
text
Causa raiz: ao concluir o pedido, o formulário era limpo antes de enviar a
requisição; uma falha deixava o formulário vazio, e a nova
tentativa enviava dados vazios, recebia 500 e um catch silencioso
engolia o erro.
Correção: enviar primeiro e limpar ao receber sucesso; o catch silencioso foi
removido e uma mensagem de erro passou a ser exibida.
Verificado: Chrome 141 / macOS 14, três tentativas com a rede desligada
exibiram "Falha ao enviar, tente novamente" e mantiveram o
conteúdo; regressão: checkout, cupons, endereços.
Essas três partes respondem "por que estava quebrado", "o que mudou" e "como você provou". Elas sobrevivem ao diff — seis meses depois o diff foi reescrito, o arquivo dividido, o módulo substituído, e o comentário continua lá.
Não deixe a evidência só no chat. Capturas, gravações e requisições com falha precisam ficar junto do registro, senão em três meses, quando a regressão falhar, "como era na época" vai dar num link morto. A extensão do BugCapturer anexa erros de console, requisições com falha, URL, navegador e viewport no envio e gera um link compartilhável; no plano de equipe os relatos ficam retidos a longo prazo, por um motivo simples: que "o relato original ainda abre" continue verdadeiro em três meses.
Por que a reprodução falha: três causas reais
"Não reproduzível" é um buraco negro num sistema de defeitos. Raramente é sorte; é uma de três diferenças.
1. Ambiente. As cinco de sempre: versão do build (local roda o main mais recente), caches (navegador, service worker, CDN), feature flags, papéis e permissões, fuso horário e idioma. O movimento é alinhar esses cinco um a um, não pedir para tentar de novo.
2. Dados. O registro do usuário tem uma observação de 300 caracteres, um apelido com emoji, um nome do meio null, um valor negativo. A interface está sempre correta com "dados normais". Quem consegue reproduzir normalmente tem o ID do registro específico.
3. Tempo. Corridas assíncronas, carregamento preguiçoso, debounce, ordem de callbacks de terceiros. Nunca aparecem em rede rápida e sempre em rede lenta; na máquina do desenvolvedor vão sempre bem. A ferramenta é limitar banda e injetar atraso, não mais log.
Quando não conseguir reproduzir, registre como em espera + lista de condições já testadas + três perguntas (entrada / conta / horário). Fechar é a pior opção: você perde a informação de que aconteceu, e vai voltar.
Patch, hotfix, correção comum: três ritmos que não se misturam
O mesmo bug segue uma de três rotas conforme impacto e urgência, não dificuldade:
| Correção comum |
Patch |
Hotfix |
| Situação |
Não trava o fluxo principal, pode esperar |
Escopo pequeno, mas precisa sair logo |
Produção parada / dinheiro em risco / segurança |
| Processo |
Iteração normal com revisão |
Sai na próxima versão menor |
Pula o processo normal, revisão depois |
| Obrigatório extra |
Matriz de regressão |
Matriz + nota de mudança |
Matriz + nota de mudança + postmortem |
| Mais esquecido |
Verificação de bordas |
Avisar usuários afetados |
Corrigir o sintoma e não a causa |
O risco do hotfix não é a velocidade, é que ninguém volta depois. Mudanças provisórias ficam no código, a regressão nunca é adicionada, o postmortem nunca é escrito. Um hotfix deve deixar três coisas: uma nota de versão, uma passada de regressão direcionada e uma frase sobre como aquilo chegou em produção. As notas ficam no changelog.
Cinco regras para o time
Se você só levar cinco:
Devolva o relato que não dá para começar; não adivinhe. Dois minutos de devolução contra quarenta de suposição.
Um commit, uma causa. Mudança misturada não se verifica nem se reverte.
Feche com causa raiz e link para a evidência. A única regra que economiza um dia de alguém, seis meses depois.
"Não reproduzível" é motivo para esperar, não para fechar.
Correção sem preencher a matriz não está terminada. A linha que você pulou é a entrada do próximo incidente.
A fronteira entre defeito, requisito, erro e bug se confunde — veja bug vs defect vs issue vs error. Se o que você precisa é "como avisamos o cliente de que foi corrigido", veja compartilhar relatos de bug com clientes.
Perguntas frequentes
Como priorizo correções contra funcionalidades novas?
Por impacto vezes frequência, não por quem grita mais. A matriz de severidade por prioridade está no guia de triagem. Um acréscimo: não reordene a fila no meio do sprint. Times que re-triam o tempo todo costumam não terminar nenhuma das duas frentes.
Dá para corrigir vários bugs numa mesma mudança?
Só com uma única causa e um único ponto — uma causa com três sintomas continua sendo um bug. Causas independentes no mesmo commit tornam o rollback impossível: quando produção quebra, você só pode desfazer tudo.
Todo bug precisa de teste unitário?
Não. Três tipos merecem: os que reincidem (com histórico de regressão), os de lógica ramificada (muitos casos de borda) e qualquer coisa que calcule dados (valores, proporções, datas). Correções puramente visuais e de texto ficam cobertas pela passada de regressão.
Encontrei outro problema enquanto corrigia. Corrijo também?
Não. Abra um ticket separado. Misturar invalida o passo 5: você não consegue dizer qual mudança fez o problema sumir.
Devemos avisar os usuários depois de um bug em produção?
Se dados enviados, valores ou status de pedido foram afetados, avise de forma proativa e diga o que foi reparado. Se foi uma indisponibilidade breve já resolvida, uma atualização de status basta. Registrar no changelog também responde "existe algum registro disso" quando um cliente pergunta.