Debugging com IA: do stack trace à causa raiz

Bug é onde o vibe coding mostra serviço de verdade. Não porque a IA "adivinha" o problema — mas porque ela rastreia rápido entre as camadas que, num monorepo, ninguém segura inteiras na cabeça. Este post fecha o Módulo 2 mostrando como debugamos com Claude Code.

Por que debugging combina com IA

Um bug no ClubPetro pode nascer no componente React, passar pelo procedimento tRPC, morrer numa query Drizzle ou esbarrar numa policy de RLS no Supabase. Seguir esse fio à mão é lento. A IA lê todas as camadas de uma vez e conecta os pontos — é tradução de "sintoma" pra "causa" em velocidade.

O fluxo que funciona

1. Dê o sintoma completo

Cole o erro inteiro: stack trace, mensagem, o que você fez pra disparar, o que esperava. Erro pela metade gera diagnóstico pela metade.

2. Use /investigate

Nossa skill de investigação (#15) conduz isso de forma estruturada — em vez de chutar a primeira causa plausível, ela levanta hipóteses e testa.

3. Exija a causa, não o band-aid

A pergunta certa não é "como faço o erro sumir?", é "por que isso acontece?". Tratar sintoma esconde o bug pra ele voltar pior depois.

4. Confirme antes de corrigir

Causa identificada, valide que faz sentido (reproduz? explica todos os sintomas?) antes de aplicar a correção. Depois, ciclo normal: plano → geração → revisão.

Os suspeitos de sempre (no nosso stack)

A IA acelera, mas conhecer os clássicos ajuda a guiar:

• tRPC — erro inclui detalhe do Zod; ótima pista de validação.
• DATABASE_URL — precisa ser porta 6543 (pooler) com prepare:false; porta 5432 dá SASL_SIGNATURE_MISMATCH.
• RLS — "sumiu dado pela API" muitas vezes é policy faltando, não bug de código.
• Build — dep faltando entre pacotes aparece no pnpm build.

Dar essas pistas no prompt encurta o caminho.

Onde o humano decide

A IA encontra a causa provável e propõe a correção. Validar que é a causa certa e que a correção não cria outro problema é julgamento humano. Bug "resolvido" sem entender a causa é bug que volta — e a gente é Leal a Dados: a correção tem que se sustentar na evidência, não na esperança.

⚠️ Armadilha #17: aceitar a primeira correção que faz o erro sumir sem entender por que ele acontecia. Você não corrigiu o bug — você mudou onde ele vai aparecer da próxima vez.

Fim do Módulo 2 — Claude Code. Próximo: Módulo 3 (#18) — Dados com Supabase.