Decodificador de erros com Claude Code: de logs a correções reproduzíveis

Ao começar com Claude Code, é tentador colar uma mensagem de erro enorme e pedir: “corrija isso”. Às vezes funciona, mas não é um processo confiável. Claude Code não sabe automaticamente qual comando você rodou, quais variáveis de ambiente estavam presentes, quais versões estavam instaladas ou como a CI difere da sua máquina. O fluxo mais forte é transformar o erro em um relatório reproduzível e pedir hipóteses, próximos comandos e plano de verificação.

Este guia cobre stack traces, erros TypeScript, logs de runtime Node.js, Docker/Kubernetes e falhas do GitHub Actions. Como referência oficial, use Claude Code common workflows, Claude Code troubleshooting e Claude Code settings.

Fluxo principal: reproduzir antes de concluir

Mensagem de erro é evidência, não adivinhação. Guarde o sinal completo e só depois reduza o ruído.

flowchart TD
  A["Salvar a saída do comando que falhou"] --> B["Reduzir ruído sem apagar o log completo"]
  B --> C["Pedir hipóteses e passos de reprodução"]
  C --> D["Criar o menor caso que falha"]
  D --> E["Corrigir e rodar o mesmo comando"]
  E --> F["Adicionar prevenção: teste, checklist ou CLAUDE.md"]

Fonte do erro	Material para Claude Code	O que pedir	O que verificar
TypeScript	Saída completa de `tsc --noEmit --pretty false` e caminhos	Contrato de tipos quebrado, correção segura, correção arriscada	Sem `any`, sem `ts-ignore`
Stack trace Node.js	Primeira linha Error, frames da app, entrada usada	Primeiro frame útil, estado necessário	Mesma entrada reproduz localmente
Docker/Kubernetes	`describe`, logs anteriores, events	OOM, env, probe, imagem ou erro de app	Linha de evidência e comando `kubectl`
GitHub Actions	Log do job que falhou e arquivos alterados	Step que falhou, comando local, diferenças de CI	Local e CI passam

Caso 1: salvar erros de npm e tsc

Não copie só as últimas linhas. Salve a saída completa.

mkdir -p tmp/error-cases
npm test 2>&1 | tee tmp/error-cases/test.log
npx tsc --noEmit --pretty false 2>&1 | tee tmp/error-cases/tsc.log

Depois peça um plano de depuração.

claude -p "
I need a reproducible fix, not a guess.

Read these files if they exist:
- tmp/error-cases/test.log
- tmp/error-cases/tsc.log

Return:
1. One-line failure summary
2. Likely root cause with confidence level
3. Minimal reproduction steps
4. Next 3 commands to run
5. Smallest safe code change to try
6. Verification command after the fix

Do not hide TypeScript errors with any or ts-ignore.
"

O nível de confiança evita que uma hipótese fraca pareça certeza. Se a confiança for baixa, o próximo comando de confirmação vem antes do patch.

Caso 2: reduzir um stack trace de Node.js

Stack traces de Node.js geralmente são dominados por node_modules. Mantenha o log original e gere uma cópia curta para triagem.

// scripts/minimize-stacktrace.mjs
import { readFileSync } from "node:fs";

const input = readFileSync(0, "utf8");
const lines = input.split(/\r?\n/);
const kept = [];
let dependencyFrames = 0;

for (const line of lines) {
  const isStackFrame = /^\s+at /.test(line);
  const isDependencyFrame = line.includes("node_modules");

  if (!isStackFrame || !isDependencyFrame || dependencyFrames < 3) {
    kept.push(line);
  }

  if (isStackFrame && isDependencyFrame) {
    dependencyFrames += 1;
  }
}

const important = kept.filter((line) =>
  /Error:|TypeError:|ReferenceError:|SyntaxError:|Caused by:|^\s+at |src\/|app\/|packages\//.test(line)
);

console.log(important.slice(0, 80).join("\n"));

node scripts/minimize-stacktrace.mjs < tmp/error-cases/test.log > tmp/error-cases/test.min.log

claude -p "
Analyze tmp/error-cases/test.min.log first.
If the minimized log is not enough, ask for the full log instead of guessing.

Explain:
- Which application frame is the first useful frame
- What input or state is needed to reproduce it
- Whether this looks like async timing, null data, missing env, or dependency mismatch
- The smallest test that would fail before the fix
"

O script não diagnostica. Ele só diminui ruído para que o primeiro frame da aplicação apareça.

Caso 3: ler TypeScript como contrato quebrado

Type X is not assignable to type Y normalmente significa que uma função esperava um formato de dado e recebeu outro. É um contrato quebrado entre quem chama e quem recebe.

claude -p "
Explain this TypeScript error as a broken contract between caller and callee.

Use this output:
$(npx tsc --noEmit --pretty false 2>&1)

Return a table with:
- Error location
- Plain Portuguese explanation
- Data shape expected
- Data shape actually provided
- Safe fix
- Risky fix to avoid

Do not suggest any, ts-ignore, or disabling strict mode unless there is no other option.
"

Assim você separa correção real de silenciar compilador. Um erro User | null deve levar a tratar estado deslogado, validar API ou corrigir fixtures, não a forçar cast.

Caso 4: transformar logs Kubernetes em comandos de confirmação

CrashLoopBackOff é sintoma, não causa raiz.

kubectl get pod -n app
kubectl describe pod web-abc123 -n app > tmp/error-cases/pod.describe.txt
kubectl logs web-abc123 -n app --previous > tmp/error-cases/pod.previous.log
kubectl get events -n app --sort-by=.lastTimestamp > tmp/error-cases/events.log

claude -p "
Triage this Kubernetes crash.

Files:
- tmp/error-cases/pod.describe.txt
- tmp/error-cases/pod.previous.log
- tmp/error-cases/events.log

Return:
1. Most likely category: OOMKilled, missing env, image pull, app exception, probe failure, or dependency outage
2. Evidence lines from the logs
3. One kubectl command to confirm each remaining hypothesis
4. Temporary mitigation
5. Permanent fix
6. Rollback check

If evidence is insufficient, say what command is missing.
"

Se a resposta não aponta uma linha de evidência, trate como hipótese.

Caso 5: triagem de GitHub Actions

Logs de CI escondem o primeiro erro atrás de muita saída posterior. Extraia o log e separe reprodução local de diferença de CI.

gh run list --limit 5
gh run view RUN_ID --log > tmp/error-cases/github-actions.log

claude -p "
You are triaging a GitHub Actions failure.

Analyze tmp/error-cases/github-actions.log and return:
1. Failed job and failed step
2. Exact command that failed
3. Whether this should reproduce locally
4. Local reproduction command
5. CI-only differences to inspect: Node version, env vars, cache, timezone, OS, permissions
6. Smallest patch to try
7. Verification plan for local and CI

Do not assume the root cause if the log only shows a downstream symptom.
"

Isso ajuda em testes flaky, timezone, secrets ausentes, cache quebrado e permissões.

Template de bug report

# Bug report: short title

## Goal
What I was trying to do:

## Environment
- OS:
- Node version:
- Package manager:
- Branch:
- Commit:

## Exact command
```bash
paste the exact command here
```

## Expected result
What should have happened:

## Actual result
What happened instead:

## Logs
Paste the full error or attach the saved log file path.

## Minimal reproduction
Smallest steps that still fail:

## What I already tried
- Attempt 1:
- Attempt 2:

## Verification plan
Command that must pass after the fix:

Armadilhas comuns

Não cole só as últimas três linhas. A causa real costuma estar no meio.

Não omita o comando exato. npm test, npm run build e vitest --run src/foo.test.ts têm contextos diferentes.

Não aceite any, ts-ignore ou testes removidos como correção padrão de TypeScript. Às vezes é emergência, mas não deve ser rotina.

Não cole segredos. Remova API keys, cookies, JWTs e URLs de banco. Em equipes, revise permissões e configuração em settings.

Depois do patch, rode primeiro o comando que falhou. Só então amplie para lint, build e CI.

Treinamento, templates e consultoria

Para uso individual, os prompts acima já resolvem muito. Em equipe, o difícil é padronizar quais logs podem ser compartilhados, quais fixes são proibidos, como triagem de CI acontece e que evidência reviewers exigem.

ClaudeCodeLab oferece produtos e templates de Claude Code e treinamento e consultoria Claude Code para estruturar prompts de debug reutilizáveis, bug reports, checklists de CI e regras de CLAUDE.md.

Conclusão

O objetivo não é fazer Claude Code adivinhar melhor. É dar evidência suficiente para ele produzir o próximo passo reproduzível. Salve o comando, mantenha o log completo, reduza ruído com cuidado, peça confiança e verifique com o mesmo comando.

Depois de testar este fluxo na manutenção real do ClaudeCodeLab, Masa viu o maior ganho nos primeiros 10 minutos de depuração. Salvar tsc --pretty false, reduzir stack traces sem apagar o log original e quebrar falhas de CI em job, step, command e reproduction tornou as sugestões de Claude Code verificáveis, não algo para aceitar no escuro.