Template de bug report para Claude Code: de erro vago a correção reproduzível

Quando você diz ao Claude Code apenas “a página quebrou” ou “os testes falham”, ele começa no palpite. O primeiro patch pode parecer bom, mas muitas vezes pula a causa raiz, o comando de verificação e o contexto que a pessoa revisora precisa. Um bom bug report transforma dor vaga em tarefa reproduzível.

Este guia traz um template para sessões com Claude Code: sintoma, comportamento esperado, comportamento real, reprodução mínima, logs, ambiente, teste falhando, restrições e handoff de PR. Use depois do runbook da primeira tarefa, aprofunde com técnicas de debugging e finalize com a checklist de qualidade de PR.

Deixe abertas as referências oficiais: CLI reference, commands reference, common workflows e GitHub Actions guide. Elas esclarecem quando usar --verbose, /debug, /feedback, /bug e automação em PR.

O que um report útil contém

Campo	O que escrever	Por que ajuda Claude Code
Sintoma	Página, comando, rota ou API afetada	Ponto de entrada
Esperado	Regra correta de produto ou UI	Critério de “corrigido”
Real	Erro, status, quebra visual, saída incorreta	Fatos, não chute
Reprodução	Menor caminho que falha rápido	Como testar hipóteses
Ambiente	OS, runtime, navegador, branch, nomes de env	Diferença local/CI
Evidência	Logs, screenshot, stack trace, teste falhando	Prova antes/depois
Restrições	O que pode ou não ser tocado	Diff menor
Handoff	Causa, verificação, risco, follow-up	Review mais rápido

O erro mais comum é não escrever o comportamento esperado. “Tirar o erro” não é requisito. A API deve retornar lista vazia, 400, aviso ao usuário ou retry? Escreva uma regra verificável.

Template para copiar

Salve como bug-report.md, preencha e entregue ao Claude Code antes de pedir edição.

# Bug report for Claude Code

## Goal
- Bug to fix:
- Desired outcome:
- Out of scope:

## Environment
- OS:
- Node / package manager:
- Browser / device:
- Branch:
- Relevant env var names, not values:

## Symptom
- Where it happens:
- Who sees it:
- Frequency: always / intermittent / unknown

## Expected behavior
-

## Actual behavior
-

## Minimum reproduction
1.
2.
3.

## Evidence
- Error message:
- Logs:
- Screenshot:
- Failing command:

## Recent changes
- PR / commit:
- Likely files:

## Constraints
- Allowed scope:
- Do not touch:
- Do not paste secrets or customer data:

## Request to Claude Code
1. Do not patch immediately
2. List the top three hypotheses
3. Propose the smallest check that could disprove each hypothesis
4. Create a minimum reproduction or failing test first
5. Apply the smallest useful fix
6. Report verification commands and remaining risk

Serve para ticket interno, suporte e comentário de PR. O ponto é definir sucesso antes da edição.

Script executável para coletar contexto

Branch, versão do Node e diff atual são fáceis de esquecer. Este script Node não usa dependências externas e mascara secrets óbvios.

// scripts/collect-bug-context.mjs
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { platform, release } from "node:os";
import { cwd } from "node:process";

function run(command, args) {
  try {
    return execFileSync(command, args, {
      cwd: cwd(),
      encoding: "utf8",
      stdio: ["ignore", "pipe", "pipe"],
    }).trim();
  } catch (error) {
    return `(failed: ${command} ${args.join(" ")})`;
  }
}

function maskSecrets(text) {
  return text
    .replace(/(api[_-]?key|token|secret|password)=([^\\s]+)/gi, "$1=***")
    .replace(/Bearer\\s+[A-Za-z0-9._-]+/g, "Bearer ***");
}

function readPackageScripts() {
  if (!existsSync("package.json")) return "package.json not found";
  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
  return JSON.stringify(pkg.scripts ?? {}, null, 2);
}

const report = {
  generatedAt: new Date().toISOString(),
  cwd: cwd(),
  os: `${platform()} ${release()}`,
  node: process.version,
  branch: run("git", ["branch", "--show-current"]),
  status: run("git", ["status", "--short"]),
  lastCommit: run("git", ["log", "-1", "--oneline"]),
  diffStat: run("git", ["diff", "--stat"]),
  packageScripts: readPackageScripts(),
};

console.log(maskSecrets(JSON.stringify(report, null, 2)));

Execução:

mkdir -p scripts
# Salve o código acima em scripts/collect-bug-context.mjs
node scripts/collect-bug-context.mjs > bug-context.json

Máscara não substitui cuidado. Não cole chaves reais, dados de clientes ou logs completos de produção.

Caso 1: CTA mobile estoura

Report fraco:

A página mobile quebrou.

Report útil:

Symptom:
  Em viewport de 390px, o CTA de pricing passa da borda direita.

Expected behavior:
  Os dois CTAs ficam empilhados e não há scroll horizontal.

Minimum reproduction:
  1. Abrir Chrome DevTools em 390px
  2. Abrir a página afetada
  3. Rolar até pricing

Evidence:
  document.documentElement.scrollWidth is 412
  Screenshot attached

Constraints:
  Não mudar links nem copy de produto. Revisar só CSS/layout.

Assim Claude Code pode olhar width, gap, texto do botão e containers. Em páginas monetizadas, verifique também products e training.

Caso 2: API de checkout retorna 500

Em API, informe payload, resposta esperada, erro real e nomes de configuração.

Symptom:
  POST /api/checkout retorna 500 apenas com plan=pro.

Expected behavior:
  Retornar 200 com payment URL. Se faltar configuração, falhar com erro claro de setup.

Actual behavior:
  TypeError: Cannot read properties of undefined (reading 'prices')

Minimum reproduction:
  curl -X POST http://localhost:3000/api/checkout \
    -H "content-type: application/json" \
    -d '{"plan":"pro"}'

Environment:
  Usa STRIPE_SECRET_KEY e PRICE_PRO_ID. Não colar valores.

Constraints:
  Não adicionar chamadas reais ao provider. Verificar primeiro config loading e input validation.

Peça para Claude Code comparar três hipóteses: carregamento de config, validação de request e mapeamento de preço. Se a reprodução é local, o teste falhando normalmente cabe no handler ou no módulo de configuração.

Caso 3: regressão em limite de datas

Para timezone e fim de mês, um teste falhando vale mais do que screenshot.

import { describe, expect, it } from "vitest";
import { exportMonthlyOrderIds } from "../src/export-orders";

describe("exportMonthlyOrderIds", () => {
  it("includes March orders and excludes April 1 UTC", () => {
    const orders = [
      { id: "mar-start", createdAt: "2026-03-01T00:00:00.000Z" },
      { id: "mar-end", createdAt: "2026-03-31T23:59:59.999Z" },
      { id: "apr-start", createdAt: "2026-04-01T00:00:00.000Z" },
    ];

    expect(exportMonthlyOrderIds(orders, "2026-03")).toEqual(["mar-start", "mar-end"]);
  });
});

A instrução precisa ser explícita: “Faça este teste falhar primeiro e corrija sem depender do timezone local.” A armadilha é corrigir só o rótulo da UI e deixar a regra de agregação errada.

Prompt de investigação

Read bug-report.md and bug-context.json.

Process:
1. Do not edit yet
2. Separate facts from guesses
3. Rank the top three root-cause hypotheses
4. Propose the smallest check that could disprove each one
5. Create a minimum reproduction or failing test first
6. After approval, make the smallest useful fix

Done means:
- The expected/actual gap is explained
- A failing test or reproduction command remains
- Verification commands are reported
- The PR handoff includes root cause, fix, risk, and follow-up

Os common workflows oficiais recomendam passar erro, comando de reprodução, passos e se o problema é intermitente. /debug diagnostica a sessão do Claude Code. /feedback e /bug são para problemas no produto Claude Code, não no seu app.

Template de handoff para PR

## Root cause
-

## Fix
-

## Regression coverage
- Added failing test:
- Manual reproduction checked:

## Verification
- [ ] npm test
- [ ] npm run typecheck
- [ ] npm run build
- [ ] mobile / desktop visual check if UI changed

## Risk
-

## Claude Code notes
- Hypotheses rejected:
- Files intentionally not touched:
- Follow-up issue:

Ele combina bem com o template de session handoff e com estratégias de teste.

Armadilhas comuns

Não junte bugs sem relação. Login, checkout e layout precisam de reproduções separadas.

Não cole logs completos. Vinte linhas perto do erro, request ID e comando de reprodução costumam bastar.

Não termine sem teste falhando quando o bug envolve limites, mapeamento de dados, contrato de API ou permissões.

Não peça para Claude Code “olhar tudo”. Reprodução pequena vale mais que permissão ampla.

Não pule o handoff de PR. Reviewer precisa de causa, prova e risco residual.

Inclua a rota de monetização

No ClaudeCodeLab, uma correção pode quebrar CTAs, cards de produto, formulário de PDF gratuito, links Gumroad ou consulta. Se layout ou rotas de produto mudaram, inclua isso na verificação.

Para uso individual, adapte a checklist gratuita ao seu repositório. Para prompts reutilizáveis, review gates e materiais de setup, veja products. Para um time padronizar bug reports, permissões do Claude Code, PR review e CI handoff, comece por training.

Resultado prático

Em testes reais, reports com reprodução, comportamento esperado, teste falhando e handoff de PR geraram diffs menores e menos perguntas de review do que um simples “corrija”. O maior ganho veio de pedir três hipóteses antes da edição. Isso torna barato descartar caminhos errados e transforma a sessão em debugging com evidência.