Encontrar e corrigir bugs

À medida que os agentes de programação escrevem mais código, os engenheiros dedicam mais tempo a revisar esse código e encontrar bugs. Mesmo com a ajuda desses agentes, vale a pena retomar os fundamentos de uma depuração eficaz e buscar maneiras de acelerar o trabalho delegando partes desse processo aos agentes.

Fundamentos da depuração

Uma boa depuração segue os mesmos princípios, seja feita por uma pessoa ou por um agente:

1. Crie uma reprodução confiável. Se você não consegue reproduzir o bug, não consegue verificar a correção. Anote as etapas, entradas e condições exatas que provocam a issue.
2. Reduza a um caso mínimo. Remova tudo que não esteja relacionado ao bug. Quanto menor a reprodução, mais fácil será encontrar a causa raiz.
3. Isole as variáveis. Altere uma coisa por vez. Se você altera três coisas e o bug desaparece, não sabe qual alteração o corrigiu.
4. Formule hipóteses específicas. Elabore algumas hipóteses sobre qual poderia ser a causa raiz. "O bug provavelmente está no código de pagamento" é muito vago. "O bug ocorre porque calculateTotal() não considera descontos negativos" é específico o suficiente para ser testado.
5. Instrumente seu código. Adicione logs nas entradas e saídas onde você suspeita que esteja a issue. Compare os valores esperados com os valores observados.
6. Evite regressões com testes. Depois de encontrar e corrigir o bug, escreva um teste que o teria detectado. Isso impede que o mesmo bug volte a ocorrer.

Duas abordagens para depuração

Como resolver erros simples rapidamente

Para bugs com mensagens de erro claras ou causas evidentes, o agente geralmente consegue encontrar e corrigir o problema. Cole o erro, forneça algum contexto sobre quando ele ocorre e deixe o agente trabalhar.

TypeError: Cannot read properties of undefined (reading 'profile')
at getProfile (src/services/UserService.ts:45)
at UserController.show (src/controllers/UserController.ts:23)

Isso funciona bem quando a causa está visível na mensagem de erro. O agente pode ler o stack trace, encontrar o código e aplicar a correção. No entanto, isso nem sempre funciona, e talvez seja necessário adotar uma abordagem mais sistemática para encontrar a causa raiz.

Modo de Depuração: evidências em primeiro lugar

Para bugs mais difíceis, o Modo de Depuração adota uma abordagem diferente. Em vez de tentar adivinhar soluções, ele primeiro coleta evidências de tempo de execução.

O Modo de Depuração segue cinco etapas que refletem os fundamentos da depuração:

1. Gera hipóteses sobre o que pode dar errado
2. Instrumenta seu código com logs específicos
3. Pede que você reproduza o bug enquanto coleta dados
4. Analisa os logs para identificar a causa raiz
5. Faz uma correção específica com base nas evidências coletadas

O Modo de Depuração pode ajudar você a encontrar e corrigir seus bugs mais difíceis. Ele aplica os fundamentos que abordamos anteriormente e capacita o agente a ser um depurador eficaz, automatizando a investigação que você faria manualmente.

Execute vários modelos em paralelo

Para bugs complexos, modelos diferentes às vezes encontram problemas diferentes. O Cherri Code permite executar o mesmo prompt de depuração em vários modelos simultaneamente. Cada agente trabalha de forma isolada, portanto não interfere nos demais.

O fluxo de trabalho:

1. Escreva um briefing de depuração claro com as etapas de reprodução e suas hipóteses
2. Selecione vários modelos no menu suspenso de agentes
3. Envie o prompt; cada modelo trabalha de forma independente
4. Compare as correções propostas por cada modelo
5. Mantenha a abordagem com as evidências mais sólidas

O Cherri Code sugerirá a solução que considera melhor, mas você deve avaliar o raciocínio, não apenas a solução final. Para confirmar a precisão da correção, você pode pedir ao modelo que verifique o próprio trabalho e confirme se essa é a solução correta.

Inclua dados de tempo de execução no loop do agente

O agente consegue identificar problemas de desempenho e bugs comuns apenas lendo o código. Mas, quanto mais evidências de tempo de execução você fornecer, mais a fundo ele poderá investigar.

Comece com uma pergunta

Nem sempre você precisa de logs ou ferramentas de profiling para começar a investigar. Faça uma pergunta direta ao agente, e ele analisará seu código em busca de problemas comuns.

No exemplo acima, o agente encontrou uma query lenta ao analisar o código. Não foram necessários logs nem profiling de desempenho. Para alguns problemas de desempenho, isso é suficiente.

Forneça evidências do tempo de execução

Quando a análise de código por si só não for suficiente, forneça dados reais ao agente. Cole a saída do terminal, logs de consultas ou outros dados na conversa. O agente pode usar esses dados para encontrar a causa raiz com mais eficiência.

Por exemplo, se você estiver investigando uma consulta lenta ao banco de dados, poderá executar EXPLAIN ANALYZE em uma consulta lenta do Postgres, colar a saída, e o agente poderá rastrear o problema até o seu schema:

Seq Scan on orders  (cost=0.00..45892.00 rows=47 width=244) (actual time=0.423..1203.112 rows=47 loops=1)
Filter: (user_id = 'usr_abc123')
Rows Removed by Filter: 2341856
Planning Time: 0.089 ms
Execution Time: 1203.298 ms

O mesmo padrão funciona para logs de aplicações, dados de análise de desempenho ou saída de build e testes.

Use o navegador para depurar o frontend

Para problemas no frontend, o navegador integrado do Cherri Code dá ao agente acesso direto ao seu app web. Ele pode ler logs do console, inspecionar solicitações de rede e observar o DOM sem que você precise copiar nada.

Peça ao agente para abrir uma página, reproduzir um problema e verificar se há erros no console ou solicitações lentas na aba de rede. O agente vê o mesmo que você veria no DevTools e pode rastrear os problemas até o código-fonte.

Conecte ferramentas de monitoramento com o MCP

Servidores MCP dão novos recursos ao seu agente e o conectam a ferramentas de observabilidade em produção. Em vez de colar dados manualmente, o agente busca o que precisa sob demanda.

No exemplo acima, o agente consulta o Sentry pelo MCP e busca os detalhes relevantes do erro. Ele correlaciona o erro com os logs, encontra o código problemático e propõe uma correção, tudo na mesma conversa.

Servidores MCP úteis para depuração:

• Sentry: Detalhes de erros, stack traces e breadcrumbs
• Datadog: Logs de produção e traces de APM
• Bancos de dados: Consulte dados de produção para verificar hipóteses
• Linear ou GitHub Issues: Traga relatos de bugs e etapas de reprodução para a conversa

Você pode configurar fluxos de trabalho em que alertas de monitoramento no seu app em produção acionam automaticamente investigações por agentes. Se a taxa de erros aumentar, um ticket será criado no Linear, e um agente começará a diagnosticar a issue antes mesmo de alguém analisá-la. Isso pode reduzir o tempo para resolver erros relatados por clientes ou até corrigir issues antes que os clientes percebam.

Padrão comum de falha: aceitar correções que você não entende

Se você não entende a correção, não consegue validar se ela está certa. O agente pode adicionar uma verificação de nulo que faz o erro desaparecer, mas a inconsistência subjacente nos dados permanece.

Quando o agente propuser uma correção, faça perguntas até entendê-la. Por que esse valor é nulo? O que mudou para causar isso? Esta é a causa raiz ou estamos apenas mascarando o sintoma? Como vimos em foundations, agentes podem alucinar explicações aparentemente plausíveis. Você precisa desenvolver seu próprio entendimento e usar os dados da sua investigação para confirmar que o agente identificou a verdadeira causa raiz.

Próximos passos

Agora que você entende a depuração e como agentes de programação podem acelerar sua investigação, precisa garantir que suas alterações estejam corretas e não introduzam regressões. No próximo capítulo, você aprenderá a revisar código e testá-lo sistematicamente.