Modulo 3.7 - Workflow: Debug com Logs e Erros

📋 Colando erros diretamente

A forma mais rapida de debugar com Claude Code e simplesmente colar o stack trace ou mensagem de erro diretamente na conversa. O Claude le o erro, identifica o arquivo e linha, analisa o contexto e sugere a correcao. Sem precisar explicar nada - o erro fala por si.

🎯 Conceito Principal

O Claude e treinado para interpretar stack traces de praticamente qualquer linguagem: Python tracebacks, Node.js errors, Java exceptions, Go panics, Rust panics e muito mais. Ele extrai automaticamente o arquivo, linha, funcao e tipo de erro para dar um diagnostico preciso.

• Cole e pergunte: Literalmente copie o erro do terminal e cole no Claude. Ele entende o formato automaticamente
• Contexto automatico: O Claude le o arquivo mencionado no stack trace para entender o contexto completo, nao apenas a linha do erro
• Diagnostico + fix: Alem de explicar o erro, o Claude sugere (e pode aplicar) a correcao imediatamente
• Erros de build: Erros de compilacao, linting, TypeScript, webpack - todos podem ser colados e resolvidos

💻 Exemplo no Terminal

# Simplesmente cole o erro

> TypeError: Cannot read properties of undefined (reading 'map')

at UserList (src/components/UserList.tsx:23:18)

at renderWithHooks (node_modules/react-dom/...)

# O Claude vai:

1. Ler src/components/UserList.tsx

2. Identificar que 'users' pode ser undefined na linha 23

3. Sugerir: users?.map() ou verificacao de loading state

💡 Dica Pratica

Nao filtre o stack trace - cole ele completo. Mesmo as linhas de frameworks internos (React, Express, Django) ajudam o Claude a entender o contexto de execucao e dar um diagnostico mais preciso.

Se o erro aconteceu apos uma mudanca recente, mencione: "Este erro comecou a aparecer depois que eu modifiquei o arquivo X." Isso ajuda o Claude a focar na causa provavel.

📥 Pipe de logs (cat error.log | claude)

Para logs grandes ou arquivos de erro, o pipe direto para o Claude e a abordagem mais eficiente. Em vez de copiar e colar manualmente, voce redireciona o conteudo do arquivo de log diretamente para analise, aproveitando o poder do modo headless.

🎯 Conceito Principal

O pipe de logs combina o poder do Unix com a inteligencia do Claude. Voce pode filtrar, recortar e direcionar logs especificos para analise, sem precisar abrir uma sessao interativa. O Claude recebe o conteudo via stdin e responde com o diagnostico.

• Pipe direto: cat error.log | claude -p "Analise estes erros" - envia o log inteiro para analise
• Filtrado com grep: grep ERROR app.log | claude -p "Classifique estes erros" - envia apenas as linhas de erro
• Ultimas N linhas: tail -100 app.log | claude -p "O que aconteceu?" - analisa os ultimos 100 registros
• Logs de Docker: docker logs container_id 2>&1 | claude -p "Diagnostique" - logs de containers

💻 Exemplo no Terminal

# Log completo

$ cat /var/log/app/error.log | claude -p "Identifique os 3 erros mais criticos e sugira fixes"

# Filtrado por horario

$ grep "2026-03-09" app.log | grep ERROR | claude -p "O que causou estes erros hoje?"

# Output de teste falhando

$ npm test 2>&1 | claude -p "Analise as falhas de teste e sugira correcoes"

# Logs de multiplos servicos

$ docker-compose logs --tail=50 2>&1 | claude -p "Identifique problemas de comunicacao entre servicos"

💡 Dica Pratica

Para logs muito grandes (>1000 linhas), filtre antes de enviar. O Claude funciona melhor com contexto focado. Use tail -200, grep ERROR ou grep -A5 "Exception" para enviar apenas o relevante.

Crie um alias para debugging rapido: alias debug-log='tail -200 | claude -p "Analise estes logs e identifique o problema"'

🔎 Tracando root cause (analise de arquivos)

Encontrar o erro e so o comeco - o verdadeiro desafio e encontrar a causa raiz. O Claude Code se destaca nisso porque pode ler multiplos arquivos, tracar a cadeia de chamadas e identificar onde exatamente o problema se origina, mesmo que o erro apareca em outro lugar.

🎯 Conceito Principal

Root cause analysis com Claude segue o principio dos "5 porques": o erro aparece na linha X, mas por que? Porque a variavel e nula. Por que e nula? Porque o fetch falhou. Por que falhou? Porque a URL esta errada no config. O Claude faz essa cadeia automaticamente, lendo cada arquivo relevante.

• Trace de chamadas: O Claude segue o stack trace, lendo cada arquivo e funcao na cadeia para encontrar a origem real do problema
• Leitura multi-arquivo: O Claude le automaticamente os arquivos referenciados no erro, imports, configuracoes e dependencias
• Hipoteses e verificacao: O Claude formula hipoteses sobre a causa e verifica cada uma lendo o codigo relevante
• Historico git: Quando relevante, o Claude pode usar git log e git blame para identificar quando e quem introduziu o bug

💻 Exemplo no Terminal

# Pedir analise de root cause

> Este erro aparece no UserList.tsx:23 mas acho que a causa real esta em outro lugar. Trace a cadeia de chamadas e encontre a root cause:

TypeError: Cannot read properties of undefined (reading 'map')

# Claude vai ler:

1. UserList.tsx → identifica que 'users' vem de useQuery()

2. hooks/useUsers.ts → identifica que o fetch usa getApiUrl()

3. config/api.ts → encontra URL incorreta no .env

Root cause: REACT_APP_API_URL nao definida no .env.local

💡 Dica Pratica

Quando o bug e misterioso, peca ao Claude para trabalhar em Plan Mode primeiro: "Antes de mudar qualquer coisa, analise o problema e me diga onde voce acha que esta a root cause." Isso evita fixes prematuros que mascariam o problema real.

Use git bisect com Claude: "Execute git bisect para encontrar o commit que introduziu este bug" - o Claude pode automatizar o processo inteiro.

🔧 Aplicando o fix (correcao + verificacao)

Com a root cause identificada, e hora de aplicar a correcao e verificar que funciona. O Claude Code nao apenas sugere o fix - ele edita o arquivo, roda os testes e confirma que o erro foi resolvido. O ciclo completo de debug acontece em uma unica sessao.

🎯 Conceito Principal

O ciclo de fix e: diagnostico → correcao → teste → verificacao. O Claude executa todas as etapas, garantindo que o fix nao apenas resolve o erro original mas tambem nao introduz novos problemas (regressoes).

• Fix cirurgico: O Claude faz a menor mudanca possivel para resolver o problema, minimizando risco de efeitos colaterais
• Verificacao automatica: Apos aplicar o fix, o Claude roda os testes e/ou reproduz o cenario de erro para confirmar a resolucao
• Teste de regressao: O Claude pode gerar um teste especifico para o bug, garantindo que nao volte no futuro
• Commit descritivo: O Claude pode criar um commit com mensagem que descreve o bug e a correcao para referencia futura

💻 Exemplo no Terminal

# Pedir fix + verificacao completa

> Corrija o bug que voce identificou. Depois:

1. Rode os testes para confirmar que o fix funciona

2. Crie um teste de regressao para este bug

3. Faca um commit com mensagem descritiva

# Resultado tipico:

Fix aplicado em src/config/api.ts

Teste de regressao criado em __tests__/api-config.test.ts

Todos os 47 testes passando

Commit: "fix: add fallback for undefined API URL in config"

💡 Dica Pratica

Sempre peca um teste de regressao junto com o fix. O teste garante que o mesmo bug nunca mais volte. Sem o teste, voce (ou outro dev) pode reintroduzir o mesmo problema no futuro.

Padrao de commit para bugs: "fix: [o que foi corrigido] - [causa raiz]". Ex: "fix: prevent null crash in UserList - add API URL fallback"

🎲 Erros intermitentes (flaky debugging)

Os erros mais frustrantes sao os intermitentes: as vezes acontecem, as vezes nao. Race conditions, timing issues, flaky tests e erros que dependem do estado. O Claude Code pode ajudar a identificar padroes nesses erros e sugerir solucoes robustas.

🎯 Conceito Principal

Erros intermitentes geralmente tem causas sistematicas que se manifestam sob condicoes especificas. O Claude pode analisar multiplas ocorrencias do mesmo erro, identificar padroes (horario, carga, estado) e propor solucoes que tratam a causa raiz.

• Race conditions: Duas operacoes concorrentes acessando o mesmo recurso. Claude identifica shared state e sugere locks, mutexes ou reestruturacao
• Flaky tests: Testes que passam e falham aleatoriamente. Geralmente causados por dependencia de timing, estado global ou ordem de execucao
• Analise de padroes: Colete varias ocorrencias do erro e peca ao Claude para encontrar o que elas tem em comum
• Reproducao: O Claude pode sugerir como reproduzir o erro de forma consistente, o que e metade da solucao

💻 Exemplo no Terminal

# Analisar flaky test

> O teste "should update user profile" falha intermitentemente (3 de 10 execucoes). Analise o teste e o codigo que ele testa para encontrar a causa da intermitencia.

# Analisar logs de multiplas ocorrencias

$ grep "ConnectionTimeout" app.log | claude -p "Estas timeouts acontecem em padroes? Qual a causa provavel?"

💡 Dica Pratica

Para flaky tests, peca ao Claude para rodar o teste 10 vezes em loop e analisar os resultados: "Rode este teste 10 vezes. Se falhar em alguma, analise a diferenca entre as execucoes que passaram e as que falharam."

Erros intermitentes em producao: colete pelo menos 5 ocorrencias antes de analisar. Uma unica ocorrencia pode ser ruido, mas 5 revelam padroes.

📊 Logs de producao (analise segura)

Analisar logs de producao requer cuidado extra: eles podem conter dados sensiveis (tokens, emails, IPs). O Claude Code pode ajudar a diagnosticar problemas de producao de forma segura, desde que voce siga boas praticas de sanitizacao antes de compartilhar os logs.

🎯 Conceito Principal

Logs de producao sao a fonte mais rica de informacao para debugging, mas vem com responsabilidades. O Claude processa os logs localmente na sua maquina, mas e boa pratica sanitizar dados sensiveis antes de enviar para analise.

• Sanitizacao: Remova tokens, senhas, emails e dados pessoais antes de enviar ao Claude. Use sed/awk para mascarar
• Filtragem por relevancia: Nao envie 10GB de logs. Filtre por timestamp, nivel de severidade ou servico especifico
• Correlacao de eventos: O Claude pode correlacionar logs de multiplos servicos para tracar o fluxo de uma request que falhou
• Metricas e tendencias: Alem de erros pontuais, o Claude pode identificar tendencias: "erros aumentaram 300% nas ultimas 2 horas"

💻 Exemplo no Terminal

# Sanitizar e analisar

$ cat prod.log | sed 's/Bearer [^ ]*/Bearer [REDACTED]/g' | \

sed 's/[a-zA-Z0-9._%+-]*@[a-zA-Z0-9.-]*/[EMAIL]/g' | \

claude -p "Analise estes logs de producao. Identifique erros criticos e padroes."

# Logs de multiplos servicos

$ kubectl logs -l app=api --tail=200 | claude -p "Correlacione erros entre os pods"

💡 Dica Pratica

Crie um script de sanitizacao reutilizavel para seus logs de producao. Isso torna seguro e rapido enviar logs para analise sem risco de vazamento de dados.

Nunca envie logs de producao com dados de pagamento, credenciais de banco ou tokens de API. Use grep -v para remover linhas que contenham palavras-chave sensiveis antes do pipe.

🏋️ Exercicio Pratico

Diagnosticar 3 erros diferentes via pipe de logs e stack traces

Criar cenarios de erro

Introduza 3 bugs intencionais no projeto e colete os erros:

# Bug 1: Referencia undefined

# Bug 2: Import incorreto

# Bug 3: Tipo errado de parametro

$ npm test 2>&1 > erros.log

Diagnosticar via pipe

Use pipe para enviar cada erro ao Claude:

$ cat erros.log | claude -p "Identifique todos os erros, trace a root cause de cada um e sugira fixes"

Aplicar fixes e verificar

Peca ao Claude para corrigir cada erro interativamente:

> Corrija os 3 bugs identificados. Apos cada fix, rode os testes para confirmar.

Todos os 3 erros devem estar resolvidos e os testes passando.

Criar testes de regressao

Garanta que os bugs nao voltem:

> Crie um teste de regressao para cada um dos 3 bugs corrigidos.

✅ Criterios de Sucesso

☐ Colou stack trace e obteve diagnostico

☐ Usou pipe de logs para analise

☐ Encontrou root cause de cada erro

☐ Aplicou fixes e testes passam

☐ Criou testes de regressao

☐ Sanitizou dados sensiveis em logs

📋 Resumo do Modulo

✓

Cole o erro e receba diagnostico - Stack traces colados diretamente sao interpretados automaticamente pelo Claude.

✓

Pipe de logs para analise em massa - cat, grep, tail combinados com claude -p para processamento eficiente.

✓

Root cause analysis multi-arquivo - O Claude segue a cadeia de chamadas ate encontrar a origem real do problema.

✓

Fix + verificacao + regressao - Ciclo completo: corrige, testa, cria teste de regressao e comita.

✓

Erros intermitentes tem padroes - Colete multiplas ocorrencias e peca ao Claude para encontrar o padrao.

✓

Logs de producao com seguranca - Sempre sanitize dados sensiveis antes de enviar para analise.

Proximo Modulo:

3.8 - Workflow: Migracao Multi-arquivo

← Modulo Anterior Voltar para Trilha Proximo Modulo →