Identificando e corrigindo bugs com o Claude Code

Ao final deste capítulo, você saberá transformar uma mensagem de erro, um log confuso ou um comportamento estranho em uma correção segura, com o Claude Code fazendo o trabalho braçal de investigar e você mantendo o controle das decisões. Vamos reaproveitar as técnicas de instrução do capítulo quatro e a API de tarefas com o campo de prazo que criamos no capítulo sete.

Comece pela mensagem de erro completa

O erro mais comum ao depurar com inteligência artificial é resumir o problema. Quando existe uma mensagem de erro, cole-a inteira, incluindo o stack trace, que é a lista de chamadas de função que estavam ativas no momento da falha, da mais recente até a mais antiga. Esse rastro é exatamente o que o Claude Code precisa para abrir os arquivos certos sem adivinhar.

Em seguida, peça a causa raiz, e não a correção. A causa raiz é o motivo original pelo qual o erro acontece, em oposição ao lugar onde ele estoura. Entre no modo de planejamento e escreva algo assim:

Este erro aparece ao chamar POST /tarefas com um prazo preenchido: TypeError: Cannot read properties of undefined (reading 'toISOString')     at formatarTarefa (src/services/tarefas.js:42:31)     at Array.map (<anonymous>)     at listarTarefas (src/services/tarefas.js:58:20) Explique a causa raiz citando arquivo e linha. Não edite nada ainda.

Repare nas três partes: contexto de quando ocorre, o erro literal e a instrução explícita de investigar antes de mudar. Sem essa última frase, a ferramenta tende a propor um remendo no ponto da falha, que quase sempre é o sintoma.

Logs, passos de reprodução e a regra de reproduzir primeiro

Quando não há stack trace, a matéria-prima são os passos de reprodução: o que você fez, o que esperava, o que aconteceu e em qual ambiente. Junte trechos de log relevantes, e não o arquivo inteiro. Cinquenta mil linhas de log consomem a janela de contexto e escondem a informação útil. Filtre pelo intervalo de tempo ou pelo identificador da requisição antes de colar. E, antes de enviar qualquer log, remova ou mascare dados sensíveis, como senhas, tokens, chaves de API e dados pessoais de clientes: exigência das políticas da maioria das empresas e cuidado básico diante da Lei Geral de Proteção de Dados.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Depois, peça que o Claude Code reproduza o bug antes de corrigir. Ele pode escrever um pequeno script, uma chamada com curl ou um caso de teste que exercite o cenário, executar e confirmar que a falha acontece. Isso vale ouro por dois motivos. Primeiro, uma reprodução confirmada prova que a hipótese sobre a causa está certa. Segundo, depois da correção, o mesmo script mostra que o problema realmente sumiu, em vez de você confiar em uma explicação bonita.

Bugs sem mensagem de erro

Nem todo bug grita. Há três famílias que exigem abordagens diferentes.

• Comportamento incorreto. O código roda sem falhar, mas devolve o resultado errado. Use exemplos de entrada e saída: com esta entrada, esperava isto e recebi aquilo. Peça que o Claude Code rastreie o dado desde a entrada até a saída e aponte em qual linha o valor deixa de ser o esperado.
• Problema de performance. Nunca aceite otimização sem número. Informe a medição atual, por exemplo, a listagem demora quatro segundos com dez mil registros, e peça que ele instrumente o código ou use a ferramenta de perfil da linguagem para localizar o gargalo antes de propor mudanças. Uma consulta dentro de um laço costuma ser o culpado, mas você quer a evidência, não o palpite.
• Condição de corrida. É o bug que aparece só às vezes, quando duas operações concorrentes acessam o mesmo recurso em uma ordem inesperada. Descreva a intermitência, peça hipóteses sobre estado compartilhado e solicite uma reprodução que execute a operação muitas vezes em paralelo. Se a falha aparece em uma a cada cem execuções, a reprodução precisa rodar centenas de vezes.

Sintoma ou causa

A correção de sintoma faz o erro desaparecer sem eliminar o motivo. Os exemplos clássicos são o bloco try catch que engole a exceção e o teste de nulo colocado logo antes da linha que falhou. A correção de causa muda o código para que a situação inválida nunca seja criada. Modelos de linguagem são muito bons em produzir correções de sintoma, porque elas são localizadas e fazem a mensagem sumir. Sua função é não aceitá-las.

A defesa mais simples é uma pergunta: por que esse bug existia? Peça a explicação junto com a proposta de correção. Se a resposta for vaga, do tipo o valor podia ser indefinido em alguns casos, desconfie e pergunte em quais casos e por quê. Quando houver mais de um caminho, peça alternativas com trade-offs, como você aprendeu no capítulo quatro, e escolha conscientemente.

Bugs visuais e o histórico do projeto

Para problemas de interface, uma captura de tela vale mais que três parágrafos. Cole a imagem na sessão, como mostrado no capítulo dois, e descreva o que deveria aparecer no lugar. O Claude Code consegue relacionar o que vê com os componentes e estilos do projeto e localizar a regra que causa o desalinhamento ou a cor errada.

Quando o bug é recente, descobrir quando ele entrou reduz a investigação a um punhado de linhas. Peça que ele consulte o histórico do arquivo suspeito com git log e resuma as mudanças relacionadas ao trecho. Para casos difíceis, existe o git bisect, que faz uma busca binária no histórico de commits para encontrar o primeiro em que o problema aparece. O Claude Code pode conduzir esse processo se você tiver um script de reprodução que devolve sucesso ou falha. Antes de começar, faça commit ou guarde o trabalho em andamento, porque o bisect fica trocando a árvore de trabalho entre commits antigos, e ao terminar rode git bisect reset para voltar ao ponto original. O trabalho detalhado com Git fica para o capítulo onze.

Exemplo passo a passo: o prazo que vira atraso

Voltemos à API de tarefas. Chegou o relato: tarefas com prazo para hoje aparecem como atrasadas na tela, mas os testes passam. Vamos seguir o fluxo.

1. Relatar com reprodução. No modo de planejamento: ao criar uma tarefa com prazo igual à data de hoje e listar as tarefas, o campo atrasada volta verdadeiro. Esperava falso. Acontece com qualquer tarefa cujo prazo é a data de hoje, e os testes atuais não pegam o caso porque só usam prazos futuros. Explique a causa raiz, cite arquivo e linha e não edite nada.
2. Ler a hipótese. O Claude Code lê o serviço e aponta a linha quarenta e dois de src/services/tarefas.js, onde está a comparação new Date(tarefa.prazo) menor que new Date(). Ele explica que o prazo é salvo como texto no formato ano, mês e dia, e que o construtor de Date interpreta esse formato como meia-noite em tempo universal coordenado, o UTC. Como a comparação coloca esse instante de meia-noite contra o instante atual, qualquer tarefa com prazo para hoje já aparece como atrasada em qualquer fuso, assim que o dia começa. Em São Paulo, três horas atrás do UTC, o efeito é ainda pior: essa meia-noite corresponde às vinte e uma horas do dia anterior, então a tarefa nasce atrasada antes mesmo de o dia virar no relógio local.
3. Confirmar reproduzindo. Peça um script que crie a tarefa e liste duas vezes: com a variável de ambiente TZ igual a America/Sao_Paulo e com TZ igual a UTC. Nos dois casos ele mostra atrasada verdadeiro, o que confirma a hipótese e deixa claro que o problema está na comparação com o instante atual, não apenas no fuso.
4. Escolher a causa, não o sintoma. Ele oferece duas opções. A primeira, subtrair um dia da comparação, é sintoma puro e quebraria em outros fusos. A segunda é comparar datas de calendário, sem hora, construindo ambas na mesma zona. Você escolhe a segunda e pergunta se outros pontos do código constroem Date a partir do prazo.
5. Revisar o diff. Ele encontra mais um uso no filtro de tarefas da semana e propõe extrair uma função ehDataPassada usada nos dois lugares. O diff toca dois arquivos, nada mais. Você aprova e roda o script de reprodução de novo. Atrasada agora volta falso.

Não quebre outra coisa e feche com um teste

Toda correção é uma alteração, e alterações têm efeitos colaterais. Três hábitos reduzem o risco. Primeiro, antes de aprovar, peça que o Claude Code liste todos os pontos que usam a função ou o dado alterado, como fizemos com o prazo. Segundo, rode a suíte completa de testes, não só o cenário do bug. Terceiro, mantenha o diff pequeno. Se a correção de um bug de data vier acompanhada de renomeações e limpezas em arquivos sem relação, recuse e peça só a correção, como você aprendeu no capítulo sete.

O fechamento correto de um bug é um teste de regressão: um teste automatizado que falha com o código antigo e passa com o novo, garantindo que o problema não volte despercebido. Peça que o Claude Code transforme o script de reprodução em um teste na suíte do projeto e confirme que ele falha se a correção for revertida. A técnica de escrever bons testes, e os cuidados com testes que apenas congelam o comportamento atual, são o assunto do capítulo nove.

Recapitulando

Cole o erro e o stack trace completos e peça a causa raiz antes de qualquer edição. Forneça passos de reprodução e logs filtrados, e exija que o bug seja reproduzido antes e depois da correção. Para bugs silenciosos, use exemplos de entrada e saída, medições de performance e reproduções repetidas para condições de corrida. Recuse correções de sintoma perguntando sempre por que o bug existia. Use capturas de tela para problemas visuais e o histórico do Git para descobrir quando o defeito entrou. E encerre cada bug verificando outros usos do código alterado, rodando a suíte inteira e criando um teste de regressão.