Diagnóstico de erros com Claude Code: de logs a testes de regressão

Diagnosticar um erro não é olhar a última linha vermelha do terminal e alterar código por intuição. É transformar uma falha em evidência que outra pessoa, um runner de testes ou o Claude Code consiga reproduzir.

Três conceitos bastam para começar. Log é o registro emitido por um comando ou aplicação. Stack trace é o caminho de chamadas de função que levou ao erro. Reprodução mínima é o menor exemplo que continua falhando depois de remover UI, dados e configuração sem relação.

O Claude Code funciona melhor quando você não pede apenas “corrija isto”. Informe o comando que falhou, a primeira linha relevante, poucas hipóteses e o comando que deve passar depois da correção.

Para completar, veja o loop de triagem de erro de build, o decodificador de mensagens de erro e o template de bug report.

Fluxo de diagnóstico

flowchart LR
  A["Salvar comando que falhou"] --> B["Encontrar primeira falha"]
  B --> C["Limitar a três hipóteses"]
  C --> D["Criar reprodução mínima"]
  D --> E["Adicionar teste de regressão"]
  E --> F["Aplicar menor correção"]
  F --> G["Verificar com mesmo comando"]
  G --> H["Escrever nota de handoff"]

Essa ordem evita editar primeiro e provar depois. O Claude Code consegue ler muitos arquivos; instruções amplas podem virar limpeza sem relação. O objetivo não é mudar mais código, e sim estreitar a causa.

Colete quatro evidências.

Evidência	Por que importa	Exemplo para Claude Code
Comando que falhou	Fixa a reprodução	npm run build, node --test
Primeira linha da falha	Evita ruído do fim do log	TypeError, ERR_MODULE_NOT_FOUND
Contexto de execução	Separa diferenças de ambiente	Versão do Node.js, OS, CI
Comportamento esperado	Define a correção certa	null vira array vazio, 404 não tenta de novo

Para nomes de erros JavaScript, consulte MDN JavaScript error reference. Em Node.js, a documentação de Node.js Errors ajuda a preferir error.code a textos de mensagem frágeis. Para E2E, Playwright debugging docs mostra Inspector, Trace Viewer e depuração no VS Code.

Workflow prático com Claude Code

Use este prompt como unidade de trabalho.

claude -p "
Diagnose the following error.

1. Confirm the failing command
2. Separate the first failure from unrelated log noise
3. List up to three root-cause hypotheses
4. Create a minimal reproduction
5. Add a regression test
6. Apply the smallest fix
7. Verify with the same command and write a handoff note

Constraints:
- Do not perform unrelated refactors
- Explain any public API change before making it
- Do not call the fix complete if verification still fails
"

“Até três” é intencional. Dez hipóteses raramente são verificadas bem. Para Cannot read properties of undefined, as causas úteis costumam ser formato de API alterado, valor inicial ausente ou renderização antes de dados assíncronos.

Caso 1: undefined no React

Um caso comum: a API retorna null, mas a UI chama users.map(...). Parece problema de React, porém a causa costuma ser o contrato de dados.

// user-list.mjs
export function names(users) {
  if (!Array.isArray(users)) {
    return [];
  }

  return users.map((user) => user.name ?? "(no name)");
}

// user-list.test.mjs
import assert from "node:assert/strict";
import test from "node:test";
import { names } from "./user-list.mjs";

test("names returns an empty array when the API returns null", () => {
  assert.deepEqual(names(null), []);
});

test("names keeps valid user names", () => {
  assert.deepEqual(names([{ name: "Masa" }]), ["Masa"]);
});

node --test user-list.test.mjs

Se a implementação antiga era só return users.map(...), o primeiro teste falha. Peça ao Claude Code para adicionar o teste falhando primeiro e depois fazer a menor correção.

Caso 2: ENOENT e imports no Node.js

ENOENT normalmente indica arquivo ou diretório ausente. A armadilha é config/local.json existir localmente, mas não na CI ou na imagem Docker.

Verifique comando, error.code, error.path, COPY do Dockerfile, .gitignore e working directory da CI.

claude -p "
Diagnose this Node.js ENOENT failure.
Inspect error.code, error.path, current working directory, Dockerfile, and CI config.
Suggest only fixes that do not depend on a local-only file.
"

Não pare em “criar o arquivo”. Se a configuração for obrigatória, falhe cedo com mensagem clara. Se for opcional, forneça padrão. Se a CI precisar de exemplo, copie um arquivo sample versionado.

Caso 3: Playwright falha apenas na CI

Timeouts do Playwright podem misturar bug da aplicação, espera incorreta, CI lenta, autenticação expirada ou rede diferente. Aumentar timeout costuma esconder o problema.

Guarde traces em falhas.

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  use: {
    screenshot: "only-on-failure",
    trace: "retain-on-failure",
    video: "retain-on-failure",
  },
});

Passe ao Claude Code o spec que falhou, locator, estado esperado da tela, caminho do trace e comando da CI. A instrução deve ser: “antes de aumentar timeouts, separe estado da UI, resposta da API, autenticação e problema de locator”.

Caso 4: erros TypeScript em cascata

Vinte erros TypeScript podem nascer de um único tipo de API alterado.

npx tsc --noEmit --pretty false 2>&1 | tee tsc.log
claude -p "
Read tsc.log and choose the first type error to fix.
Separate derived errors from the likely root cause.
After the fix, verify with npx tsc --noEmit --pretty false.
"

Não corrija tudo de uma vez. Corrija o tipo raiz, rode o mesmo comando de novo e veja apenas o que restou. Esse ciclo reduz as any desnecessário.

Classifique logs antes de ler tudo

Este script pode ser executado diretamente e entrega uma primeira categoria.

// triage-log.mjs
import fs from "node:fs";

const sample = `
TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (src/ProductList.tsx:42:18)
`;

const input = process.argv[2]
  ? fs.readFileSync(process.argv[2], "utf8")
  : sample;

const rules = [
  [/ERR_MODULE_NOT_FOUND|Cannot find module/i, "dependency or import path"],
  [/ENOENT/i, "file path or working directory"],
  [/TypeError:.*undefined|Cannot read properties/i, "data shape or initial value"],
  [/Timeout.*expect|locator/i, "E2E wait condition or screen state"],
  [/TS\d{4}/, "TypeScript type error"],
];

const matches = rules
  .filter(([pattern]) => pattern.test(input))
  .map(([, label]) => label);

console.log(matches.length ? matches.join("\n") : "Unclassified: inspect first failure");

node triage-log.mjs
node triage-log.mjs tsc.log

Ele não substitui diagnóstico. Só separa dependências, caminhos, formato de dados, espera E2E e erros TypeScript antes da conversa ficar grande.

Template de bug report reproduzível

Antes de pedir investigação, reformate o bug assim. Em GitHub Issues, a sintaxe oficial de GitHub issue forms transforma os mesmos campos em formulário.

## Summary
Describe the broken behavior in one sentence.

## Failed command
`npm run build`

## Expected result
The build succeeds and creates `dist/`.

## Actual result
The command fails with `TypeError: Cannot read properties of undefined`.

## First failing line
`src/components/ProductList.tsx:42:18`

## Reproduction steps
1. `npm ci`
2. `npm run build`

## Environment
- Node.js: 22.x
- OS: Windows 11 / GitHub Actions ubuntu-latest
- Branch: feature/product-list

## Already tried
- Regenerated lockfile
- Checked API response fixture

## Verification after fix
- `node --test`
- `npm run build`

A frase importante não é “algo quebrou”, mas “estes passos reproduzem a mesma falha”.

Armadilhas comuns

Primeiro, colar só a última linha do log. Guarde a primeira falha e as linhas ao redor.

Segundo, depender do texto da mensagem. Em Node.js, prefira error.code ou name quando existirem.

Terceiro, pular a reprodução mínima. Em uma tela completa, é difícil saber se a causa foi corrigida ou se só mudou o timing.

Quarto, corrigir sem teste de regressão. O bug volta no próximo refactor.

Quinto, dar escopo amplo demais ao Claude Code. Peça a menor alteração que faça esta falha específica passar. Para limites de revisão, veja a checklist de workflow de review.

Nota de handoff

Quando a verificação passar, deixe uma nota curta.

## Diagnosis note
- Failure: `npm run build`
- Cause: `users.map` was called when the API returned null
- Fix: Normalize non-array input to an empty array in `names()`
- Regression test: `node --test user-list.test.mjs`
- Verification: `npm run build` passed
- Remaining risk: Confirm separately whether API null is intentional

claude -p "
Write a Markdown diagnosis note for this fix.
Include cause, changed files, regression test, verification command,
and remaining risk. Keep it short enough for a reviewer to read in five minutes.
"

Templates e consultoria

Em projetos pessoais, copiar estes comandos e templates já ajuda. Em times, defina quais logs podem ser compartilhados, quais segredos nunca devem entrar no Claude Code, onde ficam reproduções mínimas, quais artifacts da CI são obrigatórios e qual prova o revisor espera.

ClaudeCodeLab oferece produtos e templates de Claude Code e treinamento e consultoria em Claude Code para times que querem padronizar bug reports, prompts de triagem CI, testes de regressão e notas de handoff.

Ao aplicar esse fluxo na manutenção do ClaudeCodeLab, Masa viu o maior ganho em três hábitos: preservar a primeira linha da falha, criar reprodução mínima e rodar o mesmo comando após a correção. As sugestões do Claude Code passaram a vir com evidência, hipótese, teste e verificação.