Como Depurar Código de Software em 7 Passos Repetíveis

Um carrinho pode compilar com sucesso e ainda assim dar $5 de desconto extra. Neste exercício controlado, o defeito foi solicitado de forma deliberada: aplique um cupom uma vez e, depois, faça com que uma mudança de quantidade o desconte novamente. A pergunta útil é como provar onde essa dedução extra acontece.

A aritmética torna a investigação concreta. Um carrinho de $54 se torna** $49** com um cupom. Ao adicionar outro item de** $24**, o total correto com desconto deveria ser** $73**. O cálculo com bug produz** $68**. Você pode usar essa discrepância para rastrear a transição de estado, em vez de adivinhar qual linha parece suspeita.

Ao explicar como depurar código de software, eu começo com uma regra: preserve a falha antes de editar o programa. Defina o resultado esperado, restrinja o caminho e teste uma causa. Um patch se torna convincente quando explica a discrepância e sobrevive à mesma sequência que a expôs.

Entenda o Bug Antes de Depurá-lo

Separe o Sintoma da Causa Raiz

O sintoma é o que você pode observar: um total errado, uma falha, uma página vazia ou uma requisição que nunca termina. A causa raiz é a suposição violada que produz isso. No exemplo do carrinho, a dedução aumenta quando a quantidade muda, mesmo que o valor fixo do cupom devesse permanecer em $5.

Eu não começaria alterando o formatador de moeda. Ele apenas exibe o resultado que recebe. Siga o valor de trás para frente, pelo componente de resumo, pelo cálculo do total, pela ação de quantidade e pelo estado do cupom, até encontrar a primeira divergência em relação ao cálculo esperado.

Esse é um hábito útil ao depurar código que você não escreveu. Um stack trace ou um nome de componente suspeito fornece um ponto de partida, não um veredito. A origem pode estar mais atrás no fluxo de dados, ou fora do processo que exibe a falha.

Classifique a Falha

Um erro de sintaxe impede a execução do código quando sua estrutura viola as regras da linguagem de programação.

Um erro de sintaxe impede o parsing; uma** exceção em tempo de execução** interrompe a execução; um** erro de lógica** produz um resultado incorreto. Defeitos de integração aparecem nas fronteiras entre sistemas. Falhas de ambiente dependem de configuração, permissões ou dependências; defeitos de concorrência dependem de timing e estado compartilhado.

Nosso defeito no cupom é principalmente um problema de estado e lógica. As ferramentas de build podem aceitar todos os arquivos enquanto o cálculo de negócio permanece errado. Você deve escolher evidências que correspondam à classe da falha, em vez de esperar que um único comando bem-sucedido comprove a correção.

Preserve Evidências e Avalie o Impacto

Registre o resultado esperado, o resultado real, a entrada exata, a sequência de ações e a versão com falha. Adicione detalhes do ambiente, timestamps, identificadores de requisição, logs e mudanças recentes quando forem relevantes. Você quer que outra pessoa chegue à mesma falha sem precisar reconstruir sua sessão de memória.

Eu distingo investigação de contenção. Se um defeito em produção está cobrando o valor errado, primeiro pare ou restrinja o caminho afetado por meio de uma mitigação autorizada. Um exercício descartável com carrinho permite experimentação; um incidente de pagamento ao vivo exige mudanças controladas e um responsável claro.

Como Depurar Código de Software em 7 Passos Repetíveis

Os passos formam uma sequência, mas você pode alternar entre inspeção e teste de hipóteses. Cada ciclo deve reduzir a incerteza. Se você estiver repetidamente editando arquivos não relacionados, pare e pergunte qual observação separaria com mais força as explicações restantes.

Uma investigação repetível preserva a reprodução enquanto reduz o número de causas plausíveis.

Passo 1 — Defina e Reproduza a Falha

Substitua "o cupom está quebrado" por uma sequência: carregue o carrinho, aplique o cupom de $5, aumente a quantidade do item de $24 de um para dois, depois compare o total com $78 − $5 = $73. Inclua as quantidades iniciais para que o resultado esperado seja inequívoco.

Os valores $49 e $68 aparecem em capturas sucessivas da prévia com bug. O $54 inicial está especificado no plano e no relatório de build; uma prévia posterior, já corrigida e redefinida, também mostra $54. Capturas de tela preservam esses estados, enquanto uma gravação ou um teste de interação verificaria toda a sequência de cliques.

Para uma falha intermitente, registre frequência e condições em vez de inventar uma sequência determinística. "Três falhas em vinte tentativas após reconectar" é uma evidência útil se essas tentativas foram registradas. "Às vezes quebra" dá pouco para comparar.

Os valores esperados seguem os preços da demo. O resultado com bug subtrai o mesmo cupom de $5 uma segunda vez.

Passo 2 — Reduza ao Menor Caso de Falha

Remova qualquer coisa que não afete a discrepância. Nossa aritmética precisa de preços e quantidades dos itens, estado do cupom e cálculo do total. Imagens de produtos, busca, frete e integração de pagamento não explicam uma dedução fixa extra neste exercício controlado.

Eu mantenho a transição importante intacta enquanto reduzo o código ao redor. Um exemplo mínimo que remove a ação de quantidade também pode remover o bug. Você precisa de uma reprodução menor da mesma falha, não de um programa diferente que por acaso funciona.

Documente o que você removeu e confirme que o sintoma ainda ocorre. Essa confirmação te protege de tirar conclusões sobre um teste que não exercita mais o caminho original. Para um bug dependente de dados, reduza o conjunto de entradas sem alterar o valor que o dispara.

Passo 3 — Inspecione Erros, Logs, Stack Frames e Estado

Leia a primeira falha relevante antes da cascata posterior. Inspecione os valores reais na fronteira: quantidades de itens, subtotal, valor do cupom e total exibido antes e depois da mudança. A pergunta importante é se o desconto está sendo aplicado duas vezes, não se a interface renderiza um rótulo específico.

As ferramentas de depuração do VS Code expõem variáveis, expressões de watch, stack frames e controles de execução. Use um breakpoint onde o total é atribuído, depois inspecione os chamadores e os valores atuais. Eu observo o mesmo valor em escritas sucessivas, em vez de parar no primeiro que parece plausível.

Uma interface de debugger real capturada da documentação do VS Code. O painel mostra vários tipos de evidência juntos.

Um defeito de lógica pode não ter nenhuma exceção. Você pode registrar temporariamente as entradas e o resultado calculado, ou pausar logo antes da atribuição errada. Mantenha as observações estreitas o suficiente para interpretar; um console repleto de objetos inteiros muitas vezes enterra a transição que você precisa.

Passo 4 — Restrinja o Espaço de Busca

Divida o caminho suspeito em fronteiras úteis. O estado do item está errado, o subtotal está errado, ou o total exibido fica errado depois disso? Se o subtotal é $78 mas a exibição mostra** $68**, você pode parar de investigar a multiplicação e inspecionar a aplicação do desconto.

Para uma regressão, o git bisect busca entre uma revisão boa e uma ruim conhecidas. Em uma busca binária ideal, 1.024 candidatos se reduzem a um em 10 rodadas de divisão pela metade. Investigações reais também precisam de pontos finais confiáveis, builds reproduzíveis e uma verificação confiável de bom ou ruim.

O bisect encontra a mudança associada a uma regressão; ele não explica por si só a causa subjacente.

O gráfico ilustra uma busca ideal. Builds quebrados, revisões ignoradas, ou várias falhas não relacionadas podem complicar uma execução real.

Eu executaria um bisect em um worktree limpo ou em um branch descartável, preservando primeiro qualquer trabalho não commitado. Marque uma revisão como ruim somente quando a mesma reprodução falhar. Um problema de instalação de dependência não relacionado não é evidência de que o cálculo do cupom esteja com defeito.

Passo 5 — Teste Uma Hipótese por Vez

Torne a hipótese refutável: "A ação de quantidade adiciona mais $5 à dedução de cupom armazenada." Se isso for verdade, a dedução deveria subir de $5 para $10 após a primeira mudança de quantidade enquanto o cupom permanece ativo. Remover esse acúmulo deveria restaurar exatamente um desconto fixo.

Não combine uma mudança de cálculo com uma reescrita de componente, atualização de dependência e nova regra de cupom. Eu quero que o resultado de um experimento distinga uma explicação. Um resultado aprovado após quatro edições não relacionadas deixa a causa incerta.

Se a hipótese falhar, registre o motivo e escolha a próxima a partir das evidências. Repetir a mesma explicação sem suporte com prompts levemente diferentes não é um novo experimento. Você deve conseguir dizer o que mudou no seu entendimento depois de cada tentativa.

Passo 6 — Corrija a Causa Raiz

O modelo de estado aponta para um reparo focado: derive a dedução fixa do estado do cupom em vez de acumulá-la durante as mudanças de quantidade. Isso segue a orientação do React sobre evitar estado redundante. Se um valor pode ser calculado a partir das entradas atuais, uma cópia armazenada separadamente pode acabar divergindo.

O exemplo da documentação usa nomes; o mesmo princípio se aplica a um total de carrinho derivado dos itens e do estado do cupom.

Um padrão de reparo simplificado deriva o desconto do estado atual do cupom:

const subtotal = getSubtotal(state.quantities);
const couponDeduction = state.couponApplied ? COUPON_VALUE : 0;
const total = subtotal - couponDeduction;

Eu prefiro esse reparo porque uma mudança de quantidade não acumula mais o histórico de desconto. Você ainda precisa de regras de negócio claras: se o cupom é fixo ou proporcional, se pode exceder o subtotal, e como a moeda é representada. Um cálculo em produção normalmente usa unidades inteiras menores ou outra representação monetária deliberada.

Uma mudança de quantidade deve alterar o estado do item e o subtotal enquanto o cupom fixo permanece em $5. Inspecione o diff real do projeto para confirmar que a dedução acumulativa foi removida.

Passo 7 — Verifique, Documente e Monitore o Reparo

Repita a sequência original, depois teste casos próximos: diminua a quantidade, remova o cupom, aplique-o novamente e remova um item. Preserve a falha como um teste de regressão. Uma verificação que apenas monta o carrinho não protege a transição de mudança de quantidade.

Você também deve revisar as regras adjacentes que o patch toca. Se os totais são enviados a um servidor ou provedor de pagamento, verifique a concordância nessa fronteira também. Eu registraria a causa, os arquivos alterados, os resultados dos testes e o status de release ou rollback antes de encerrar um problema em produção.

Combine o Método de Depuração com o Tipo de Bug

Saber como depurar código de software inclui saber qual ferramenta pode expor a evidência faltante. Um breakpoint é excelente para estado local; é menos útil para uma falha que ocorreu ontem em três serviços diferentes. Escolha o método pela fronteira que você precisa inspecionar.

Use Breakpoints e Stepping para Estado em Tempo Real

Um breakpoint de linha pausa em um local; um breakpoint condicional pausa apenas quando sua condição é verdadeira. A documentação de breakpoints do Chrome também cobre breakpoints de evento, DOM, requisição e exceção. Você pode escolher o gatilho mais próximo do sintoma.

A visão geral oficial mapeia diferentes sintomas para diferentes condições de pausa.

Use step over para inspecionar o resultado de uma chamada, step into quando precisar da implementação dela, e step out depois de verificar a função atual. Eu uso expressões de watch para um pequeno conjunto de valores relevantes. Observar tudo pode ser quase tão distrativo quanto logar tudo.

A declaração debugger do JavaScript pode solicitar uma pausa quando recursos de depuração estão disponíveis. Remova declarações de depuração temporárias antes do lançamento. Se o código implantado estiver empacotado ou transpilado, inspecione a configuração de source-map para que o código-fonte exibido corresponda ao código que está realmente em execução.

Uma declaração debugger é um auxílio de inspeção. Ela não tem efeito de pausa útil quando nenhum recurso de depuração está disponível.

Use Logs, Tracing e Profiling para Evidências Distribuídas

Logs estruturados registram eventos com campos consistentes; tracing acompanha o trabalho através de fronteiras; profiling examina onde tempo ou recursos são gastos. Um identificador de requisição permite conectar eventos relacionados sem adivinhar a partir de timestamps vizinhos. Não registre credenciais, segredos de pagamento ou dados pessoais desnecessários em logs.

Para o carrinho, campos de diagnóstico úteis podem ser quantidade, subtotal, estado do cupom, motivo do cálculo e total resultante. Para um fluxo de pedido remoto, você também precisa do valor aceito pelo servidor e do resultado. Eu evito afirmar que um valor do frontend comprova o que um serviço separado realmente processou.

Logpoints podem registrar um valor sem editar o código-fonte ou pausar a aplicação.

Use Testes, Assertions e Busca Binária para Isolar a Causa

Uma assertion transforma uma suposição em uma verificação. Um teste unitário pode verificar uma função de total pura; um teste de interação pode exercitar a aplicação do cupom seguida de uma mudança de quantidade. Você precisa de ambos quando o cálculo e a sequência de eventos podem falhar de forma independente.

Eu escolho o menor teste que preserva o defeito, depois adiciono uma verificação mais ampla onde a falha cruza uma fronteira. Isso mantém o teste informativo. Uma falha grande de ponta a ponta pode te dizer que a ordem está errada, deixando pouco claro qual camada é a defeituosa.

Depure Código Gerado por IA Sem Confiar Ciegamente no Patch

Revise a Mudança Gerada Antes de Executá-la

A IA para debug de código pode ajudar a organizar hipóteses e inspecionar código desconhecido, mas explicações plausíveis não são evidência de execução. Revise arquivos afetados, comandos, dependências, chamadas externas e mutações de dados. Você deve entender o escopo do patch antes de aceitá-lo.

Eu separo verificação de tipos, build, execução de testes e comportamento observado. Eles respondem a perguntas diferentes. Um teste de reducer pode passar enquanto um handler de botão permanece quebrado, então mantenha o escopo do teste explícito ao depurar código gerado por IA em seus próprios projetos.

Dê ao Modelo Evidências em Vez de Pedir uma Reescrita

Forneça o menor código relevante, a discrepância exata, a reprodução, o ambiente e o invariante. Para este carrinho, o invariante é "o cupom fixo de $5 é aplicado uma vez, independentemente das mudanças de quantidade." Peça uma explicação ranqueada e a menor mudança capaz de testá-la.

Uma solicitação focada poderia ser: "Rastreie como o couponDeduction muda depois de SET_QUANTITY. Explique por que o subtotal de $78 se torna $68. Proponha um patch mínimo que mantenha o cupom fixo em $5, e adicione um teste para aplicar o cupom antes de mudar a quantidade." Você dá ao modelo algo sobre o qual ele pode raciocinar e algo que você pode verificar.

Inspecione o Diff e Verifique de Forma Independente

Leia a diferença proposta antes de aceitar um resumo reconfortante. O reparo removeu a dedução acumulativa na ação de quantidade, ou apenas escondeu sua consequência na exibição? Ele mudou o valor do cupom, introduziu um pacote, ou alterou um componente não relacionado?

Eu quero testes que falhem contra o defeito e passem contra o reparo, com os comandos e a saída preservados. Você também deve executar novamente a reprodução original. Um teste gerado pode afirmar a expectativa errada com a mesma confiança com que um código de aplicação gerado pode calcular o total errado.

Depure um App Enter Pro da Prévia até o Código

A Coupon Debugging Demo mostra como depurar código de software em um projeto Enter Pro controlado. Seis capturas seguem o prompt, o plano, a prévia com bug, o pedido de reparo e a prévia reparada. O defeito foi plantado deliberadamente para este exercício.

Defina Uma Regra Antes de Construir

O prompt fixa os preços em $24, $18 e $12, começa cada quantidade em um, e exclui frete e impostos. A regra é simples: um cupom ativo deduz exatamente $5. Ele solicita a versão com bug primeiro, para que a falha possa ser preservada antes do reparo.

Prompt de build do Enter Pro: plantar deliberadamente uma segunda dedução de $5 após uma mudança de quantidade.

O plano prevê $54 inicialmente, $49 após a aplicação do cupom, e um total exibido de $68 contra o correto $73 após aumentar a quantidade da chaleira. Um plano registra o comportamento pretendido; a prévia fornece a próxima evidência.

O plano do projeto registra os preços, os totais esperados e o defeito planejado na ação de quantidade.

Capture a Falha na Prévia

Com todas as quantidades em um e o cupom ativo, a prévia mostra subtotal de $54, dedução de $5, e ambos os totais em $49. Aumentar a quantidade da chaleira para dois eleva o subtotal para $78, mas a dedução se torna $10. O $68 exibido e o $73 calculado de forma independente expõem a discrepância.

Antes da mudança de quantidade: subtotal $54, dedução de cupom $5, totais exibido e correto $49.

Depois de aumentar a quantidade da chaleira para dois: subtotal $78, dedução $10, exibido $68, correto $73.

O plano visível armazena couponDeduction. APPLY_COUPON o define como $5; SET_QUANTITY adiciona mais $5 quando o cupom está ativo. Esse caminho de estado planejado corresponde ao aumento de dedução observado. Inspecione o código do reducer correspondente antes de aplicar o patch.

Solicite um Reparo Focado

O pedido de reparo mantém o projeto, os produtos e a regra do cupom. Ele pede um teste de regressão que falhe antes do patch e passe depois, os nomes reais dos arquivos alterados e o diff, os comandos exatos, e quaisquer verificações que não puderam ser executadas. Isso dá ao agente um invariante específico a proteger.

O prompt de reparo pede uma mudança mínima e evidência real de regressão enquanto a falha 68/73 permanece visível.

Verifique o Reparo no Nível Correto

A captura final rotula o defeito do cupom como reparado e diz que a dedução agora é derivada do estado do cupom. Sua prévia está redefinida: cada quantidade é um, o cupom está inativo, e ambos os totais são $54. Isso captura a linha de base reparada; não mostra o total reparado de $73 após a mudança de quantidade.

Prévia reparada no estado redefinido: ambos os totais $54. O relatório identifica separadamente as verificações de UI não executadas.

O relatório cita uma captura de log de teste npm antes da correção com código de saída 1. A captura de tela não exibe as execuções brutas completas de falha e sucesso, ou o diff real. Também afirma que os testes cobrem as funções do reducer e do total, sem um ambiente jsdom e Testing Library para testes de UI/DOM.

O botão Apply fica desabilitado enquanto o cupom está ativo, então a reaplicação é uma verificação em nível de reducer. Larguras mobile e estilo escuro também estão marcados como não verificados. Para concluir a verificação, redefina o carrinho reparado e repita $54 → $49 → $73 duas vezes, depois verifique diminuições e remoção de cupom. Mantenha o diff e a saída completa da regressão.

Escale o Bug e Encerre com Evidências

Escale Quando o Risco Supera o Valor de Outro Experimento

Escale quando o defeito envolver pagamentos, perda de dados, exposição de segurança, comportamento inseguro, ou um sistema que você não pode inspecionar. Você ainda pode coletar evidências não invasivas, mas o responsável precisa decidir sobre contenção e lançamento. Eu não testaria um patch especulativo de cupom contra transações reais de clientes.

Transfira um Pacote de Evidências Reproduzível

Uma transferência deve incluir a versão com falha, a reprodução, o resultado esperado e real, logs relevantes, hipóteses testadas e a mitigação atual. Adicione identificadores de requisição e timing quando a falha cruzar serviços. Você está transferindo o estado da investigação, não apenas atribuindo uma reclamação vaga.

Complete o Checklist de Depuração de Código

Antes do encerramento, confirme a causa, o diff focado, a reprodução original, a proteção de regressão, os caminhos adjacentes e o status de implantação. Remova diagnósticos temporários ou torne-os seguros e intencionais. Eu também registro qualquer verificação que permaneça sem resolução, para que um futuro revisor não confunda o silêncio com uma aprovação.

O encerramento conecta a causa e o reparo a evidências preservadas. Um build aprovado cobre apenas parte disso.

Considerações Finais: Como Depurar Código de Software de Forma Confiável

Você não precisa de uma reescrita dramática para depurar código de forma eficaz. Você precisa de uma discrepância precisa, uma reprodução preservada e evidências que restrinjam a causa. No exercício do carrinho, a pista decisiva é a dedução subindo de $5 para $10 quando uma quantidade muda.

Meu processo preferido para depurar código gerado por IA é inspecionar primeiro, mudar uma única coisa relevante, e verificar a transição original depois. A demo do Enter Pro torna a aritmética e a mudança de estado visíveis, enquanto seu relatório de reparo distingue verificações de cálculo de verificações de UI não executadas. Mantenha o diff, a saída de regressão e os resultados de prévia repetidos juntos, para que a próxima pessoa possa avaliar o reparo.

Experimente esse workflow no Enter Pro: preserve um caso com falha, solicite um reparo focado, e revise a evidência antes de aceitá-lo.

Perguntas Frequentes

Qual é a Primeira Coisa a Fazer Quando o Código Falha?

Anote o comportamento esperado e o real, preserve a entrada com falha, e estabeleça uma reprodução. Se o defeito estiver causando dano ao vivo, a contenção pode precisar acontecer antes de uma investigação mais profunda.

Como Depuro Código que Falha Apenas Algumas Vezes?

Registre transições de estado, timing, retentativas e identificadores em tentativas repetidas. Compare execuções com falha e com sucesso em condições semelhantes. Uma única reexecução bem-sucedida não mostra que uma causa intermitente desapareceu.

Devo Usar Declarações de Print ou um Debugger?

Use um debugger quando precisar de fluxo de controle em tempo real e valores locais. Use logs para evidências remotas, históricas ou sensíveis a timing. Declarações de print temporárias são úteis quando respondem a uma pergunta específica e são removidas depois.

A IA Pode Depurar Código Para Mim?

A IA para debug de código pode sugerir causas, inspecionar código relevante, e propor testes ou patches. Você ainda precisa revisar a mudança e verificar o resultado. Trate explicações geradas e verificações relatadas de acordo com a evidência disponível.

Como Depuro Código Sem Piorar o Bug?

Preserve o estado original, trabalhe em um ambiente isolado, e mude uma variável relevante por vez. Mantenha uma rota de rollback para mudanças em produção e evite ações de diagnóstico que alterem dados reais de clientes.

Por Que um Bug Retorna Depois de Ser Corrigido?

O patch pode ter escondido o sintoma, perdido outro caminho, ou falhado em preservar o caso em um teste de regressão. Compare a nova falha com a evidência original antes de assumir que tem a mesma causa.

Como Posso Usar o Enter Pro para Depurar Código?

Mantenha a prévia com falha e o reparo em um único projeto. Dê ao Enter Pro a sequência de ações, os totais esperado e real, e a regra que o patch deve preservar. Peça para ele inspecionar o cálculo, fazer uma mudança focada, e preservar evidências de regressão. Revise o diff real e repita a sequência você mesmo.

O Que Devo Verificar Depois que o Enter Pro Reparar um Bug?

Repita a falha original e os caminhos próximos, depois inspecione os resultados completos dos testes. Nesta demo, a prévia reparada deve mostrar $73 após aplicar o cupom e aumentar a quantidade da chaleira para dois. A captura de tela com reset em $54 por si só não pode estabelecer isso. Trate testes de reducer, testes de interação de UI, e verificações de build como evidências separadas.