Como corrigir um bug: o ciclo de seis passos

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.