Loop de triagem de erros de build com Claude Code em 15 minutos

Faça triagem antes de pedir correção

Quando um build de Node, Astro, Vite ou Next.js falha, parece rápido colar o log inteiro no Claude Code e pedir para corrigir tudo. Na prática, isso mistura primeira linha com falha, stack traces posteriores, ruído do package manager e limpeza sem relação. O build pode ficar verde, mas o review fica fraco porque ninguém sabe qual mudança resolveu a causa real.

Este loop aplica o template de bug report, o checklist de review e o workflow de verification receipt a erros de build. A meta não é uma correção heroica. A meta é reduzir a causa a uma hipótese em 15 minutos, fazer a menor mudança e deixar prova revisável.

Harness significa a estrutura de apoio do agente. Claude Code lê e raciocina sobre o repositório, mas você define qual trecho do log importa, qual hipótese é permitida e qual comando prova a correção. Essa estrutura impede que um build fix vire refactor amplo.

flowchart LR
  A[State] --> B[Build log]
  B --> C[First failing line]
  C --> D[One hypothesis]
  D --> E[Small fix]
  E --> F[Proof command]
  F --> G[Receipt]

O loop de 15 minutos

Divida o trabalho em três blocos de cinco minutos. O primeiro bloco só captura evidências: git status, comando de build com falha, primeira linha com falha e arquivos relacionados. Não edite nada ainda. O segundo bloco escolhe uma hipótese: dependência, import path, frontmatter, shape de dados, permissão, rede ou expectativa de teste.

Somente o terceiro bloco permite mudança de código ou configuração. Depois da mudança, rode o comando que falhou e registre a prova. Em um site de conteúdo ou receita, build verde não basta. Confira URL do artigo, h1, canonical, hero image, CTA, link de produto e link de training. Se o build passa mas quebra conversão, ainda é problema de produção.

A nota de trabalho de Masa para esse fluxo tem três linhas: causa, mudança, evidência. O reviewer precisa ver por que a hipótese foi escolhida, o que mudou e qual comando ou URL provou. Pedir essas três linhas ao Claude Code encurta o review e deixa ponto de partida para a próxima falha.

Capture evidências na mesma ordem

Use sempre os mesmos comandos na mesma ordem. Em macOS, Linux ou WSL, este shell salva o log e preserva o exit code original.

git status --short
npm run build 2>&1 | tee build.log
status=${PIPESTATUS[0]}
if [ "$status" -ne 0 ]; then
  grep -Ein "error|failed|ERR_|Cannot|TypeError" build.log | head -n 20
  exit "$status"
fi
npm test -- --runInBand

No Windows PowerShell, chame npm.cmd explicitamente para reduzir diferenças entre shells.

$ErrorActionPreference = "Continue"
git status --short
npm.cmd run build *> build.log
$buildExit = $LASTEXITCODE

if ($buildExit -ne 0) {
  Select-String -Path build.log -Pattern "error|failed|ERR_|Cannot|TypeError" |
    Select-Object -First 20
  exit $buildExit
}

npm.cmd test -- --runInBand

A primeira execução não precisa passar. O papel dela é guardar a primeira falha útil. O último stack trace pode ser consequência; a primeira linha de erro costuma estar mais perto da causa raiz.

Classifique a primeira falha com Node

Salve o script como scripts/triage-build-log.mjs e rode node scripts/triage-build-log.mjs build.log. Ele não corrige nada; apenas reduz um log grande a um grupo e uma próxima direção.

#!/usr/bin/env node
import { readFileSync } from "node:fs";

const logPath = process.argv[2];

if (!logPath) {
  console.error("Usage: node scripts/triage-build-log.mjs build.log");
  process.exit(1);
}

const rules = [
  { name: "dependency or import path", regex: /Cannot find module|ERR_MODULE_NOT_FOUND|Cannot resolve/i },
  { name: "runtime null or shape mismatch", regex: /TypeError:.*undefined|undefined is not|Cannot read/i },
  { name: "test expectation drift", regex: /Expected.*received|AssertionError|Snapshot/i },
  { name: "permission or sandbox boundary", regex: /EACCES|EPERM|permission denied/i },
  { name: "Astro content or frontmatter", regex: /frontmatter|content collection|InvalidContentEntry|MDX/i },
];

const lines = readFileSync(logPath, "utf8").split(/\r?\n/);
const firstFailure = lines.find((line) => /error|failed|ERR_|Cannot|TypeError/i.test(line));
const matchedRule = rules.find((rule) => firstFailure && rule.regex.test(firstFailure));

console.log(JSON.stringify({
  firstFailure: firstFailure || "No obvious failure line found",
  bucket: matchedRule ? matchedRule.name : "needs manual reading",
  nextDiagnostic: matchedRule
    ? "Run one command that proves or disproves this bucket before editing files."
    : "Read the 30 lines before the first failure and classify manually.",
}, null, 2));

A classificação não precisa ser perfeita. Ela muda o pedido de “corrija o build” para “prove ou descarte este grupo antes de editar”. Isso reduz upgrades de dependência, null checks defensivos e limpezas que escondem a causa.

Use documentação oficial como limite

Problemas de conexão, autenticação, limites e mensagens runtime do Claude Code ficam em Claude Code Error reference. Se CLAUDE.md, settings, hooks ou MCP parecem não carregar, consulte Debug your configuration.

Em sites Astro, frontmatter e content collections devem ser comparados com Astro Content Collections. Para códigos Node como ERR_MODULE_NOT_FOUND, use Node.js Errors. Separar essas fontes evita tratar problema de build da aplicação como problema do Claude Code.

Primeiro passo por formato de log

Formato do log	Suspeita inicial	Primeiro passo
Cannot find module	import path, arquivo gerado, dependência	Verificar arquivo e path antes de instalar
ERR_MODULE_NOT_FOUND	ESM/CJS, extensão, package exports	Comparar erro Node com configuração do package
undefined is not	data shape, frontmatter, API response	Imprimir um registro real antes de null checks
Expected ... received	mudança de spec, fixture, snapshot	Classificar mudança intencional ou regressão
permission denied	sandbox, usuário CI, caminho de escrita	Conferir working directory e permissões
só Build failed	primeiro erro acima	Extrair o primeiro error, não a última trace

Em um site Astro, undefined is not an object pode ser apenas heroImage, pubDate ou lang ausente em uma locale. Um guard global pode deixar o build verde e esconder problema editorial.

Prompt copiável para Claude Code

Leia este build log com falha.
Não sugira refactors amplos.
Ainda não edite arquivos.

Retorne:
1. primeira linha que falhou
2. uma causa mais provável
3. menor comando diagnóstico para essa causa
4. menor mudança de código ou configuração permitida
5. comando de prova após a correção
6. três linhas para PR: causa, mudança, evidência

Quando outras pessoas trabalham no mesmo repositório, inclua o escopo: somente este slug, não tocar reports, não reverter mudanças não relacionadas e preservar campos de identidade do frontmatter. Isso evita conflito melhor do que um prompt bonito.

Quatro usos práticos

O primeiro uso é um site Astro multilíngue. Uma locale com frontmatter inválido, code fence MDX aberta, imagem hero faltando ou link interno errado pode quebrar o build. Peça ao Claude Code comparar só os dez arquivos do slug e validar YAML, fences e tamanho do corpo.

O segundo uso é falha de import em Node CLI ou package. Cannot find module nem sempre pede instalação de dependência. Pode ser typo, arquivo gerado ausente, regra exports ou mistura ESM/CJS. Antes de mexer em dependências, use node -p "require.resolve('package-name')" ou teste direto de existência de arquivo.

O terceiro uso é falha apenas em CI. Causas comuns são permissão, paths case-sensitive, versão Node diferente, secret com nome errado ou proxy ausente. Antes de mudar código da aplicação, liste OS do CI, working directory, Node version, variáveis e destinos de escrita.

O quarto uso é drift de expectativa de teste. Expected ... received pode ser silenciado com snapshot update, mas isso pode aprovar regressão. Para CTA, preço, links Gumroad, formulário de training ou metadata, confirme se a mudança era intencional.

Armadilhas concretas

Primeira armadilha: ler só o fim do log. A trace final pode ser consequência, não causa. Guarde a primeira linha falha e as 30 linhas anteriores.

Segunda armadilha: atualizar dependências cedo demais. Um package update altera lockfile, cache CI e compatibilidade runtime. Se a causa era import path typo, o review fica maior sem necessidade.

Terceira armadilha: parar no build verde. Um site público também precisa confirmar /en/products/, /en/training/, formulário PDF gratuito, h1 e canonical.

Quarta armadilha: permitir limpeza oportunista. Um PR de build-fix deve manter a hipótese visível. Se formatting, refactor, dependências e conteúdo se misturam, a prova desaparece.

CTA de produtos e consultoria

Para transformar este loop em prompts, checklists e material reutilizável, comece por ClaudeCodeLab products. Se sua equipe precisa de CI gates, CLAUDE.md, regras de permissão, review receipts e verificação de produção em um repositório real, use Claude Code training and consultation.

Como próxima leitura, veja permission audit checklist e CI/CD setup. Individualmente, o PDF gratuito ajuda a fixar comandos; em equipe, são necessários prompt compartilhado, formato comum de evidência e responsável claro por aprovação.

Resultado ao testar

Com este loop, o diff fica menor. Em vez de entregar todo o log ao Claude Code, a sessão começa com uma linha falha, uma hipótese e um comando de prova. Isso separa mais cedo frontmatter ausente, arquivo gerado faltando, import path typo e permissão de CI. O maior valor é o receipt curto que fica para a próxima falha.