Plantilla de bug report para Claude Code: de errores vagos a arreglos reproducibles

Si le dices a Claude Code “la página está rota” o “fallan los tests”, empezará adivinando. El primer parche puede parecer correcto, pero suele saltarse la causa raíz, el comando de verificación y el contexto que necesita quien revisa la PR. Un buen bug report convierte una queja vaga en una tarea reproducible.

Esta guía te da una plantilla para sesiones con Claude Code: síntoma, comportamiento esperado, comportamiento real, reproducción mínima, logs, entorno, test fallido, restricciones y traspaso de PR. Úsala después de la guía de primera tarea, profundiza con técnicas de debugging y cierra con la checklist de calidad de PR.

Ten a mano la documentación oficial: CLI reference, commands reference, common workflows y GitHub Actions guide. Aclara cuándo usar --verbose, /debug, /feedback, /bug o automatización sobre PRs.

Qué debe contener un reporte útil

Campo	Qué escribir	Para qué le sirve a Claude Code
Síntoma	Página, comando, ruta o API afectada	Punto de entrada
Esperado	Regla de negocio o UI correcta	Criterio de éxito
Real	Error, status, fallo visual o salida incorrecta	Hechos, no conjeturas
Reproducción	Camino mínimo que falla en pocos minutos	Cómo probar hipótesis
Entorno	OS, runtime, navegador, branch, nombres de env	Diferencias local/CI
Evidencia	Logs, capturas, stack trace, test fallido	Prueba antes/después
Restricciones	Qué se puede tocar y qué no	Diff más pequeño
Traspaso	Causa raíz, verificación, riesgo, follow-up	Review más rápido

El error más común es omitir el comportamiento esperado. “Quitar el error” no es un requisito. ¿Debe la API devolver lista vacía, 400, aviso al usuario o retry? Escríbelo como una frase verificable.

Plantilla copiable

Guárdala como bug-report.md, rellénala y entrégala a Claude Code antes de pedir cambios.

# 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

Sirve para tickets internos, soporte y comentarios de PR. Lo importante es definir el éxito antes de que Claude Code edite.

Script ejecutable para recopilar contexto

Es fácil olvidar branch, versión de Node o diff actual. Este script de Node no requiere dependencias y enmascara secretos obvios.

// 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)));

Ejecución:

mkdir -p scripts
# Guarda el código anterior en scripts/collect-bug-context.mjs
node scripts/collect-bug-context.mjs > bug-context.json

El enmascarado no sustituye una revisión de seguridad. No pegues claves reales, datos de clientes ni logs completos de producción.

Caso 1: CTA móvil desbordado

Reporte débil:

La página móvil está rota.

Reporte útil:

Symptom:
  En un viewport de 390px, el CTA de pricing se sale por la derecha.

Expected behavior:
  Los dos CTAs se apilan en vertical y no aparece scroll horizontal.

Minimum reproduction:
  1. Abrir Chrome DevTools a 390px
  2. Visitar la página afectada
  3. Bajar hasta la sección de pricing

Evidence:
  document.documentElement.scrollWidth is 412
  Screenshot attached

Constraints:
  No cambiar enlaces ni copy de producto. Revisar solo CSS/layout.

Así Claude Code puede mirar width, gap, texto del botón y contenedores padre. En páginas monetizadas, verifica también que sigan funcionando las rutas a products y training.

Caso 2: API de checkout devuelve 500

En APIs necesitas payload, respuesta esperada, error real y nombres de configuración.

Symptom:
  POST /api/checkout devuelve 500 solo con plan=pro.

Expected behavior:
  Devuelve 200 con payment URL. Si falta configuración, debe fallar con error 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 y PRICE_PRO_ID. No pegar valores.

Constraints:
  No añadir llamadas reales al proveedor. Revisar primero carga de configuración y validación.

Pide a Claude Code comparar tres hipótesis: carga de configuración, validación del request y mapeo de precios. Si se reproduce localmente, el test fallido puede vivir en el handler o en el módulo de configuración.

Caso 3: regresión de límite de fechas

Para timezone y fin de mes, un test fallido vale más que una captura.

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"]);
  });
});

La instrucción debe ser precisa: “Haz que este test falle primero y corrige la implementación sin depender de la timezone local.” El riesgo es arreglar solo la etiqueta visual y dejar mal el cálculo.

Prompt de investigación

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

Los common workflows oficiales recomiendan dar a Claude el error, el comando que reproduce el fallo, los pasos y si ocurre siempre o de forma intermitente. /debug diagnostica la sesión de Claude Code. /feedback y /bug son para reportar problemas del producto Claude Code, no de tu app.

Plantilla de traspaso 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:

Combina bien con la plantilla de handoff de sesión y las estrategias de testing.

Errores frecuentes

No mezcles bugs no relacionados en un reporte. Login, checkout y layout necesitan reproducciones separadas.

No pegues logs completos. Normalmente bastan veinte líneas alrededor del error, request ID y comando de reproducción.

No cierres sin test fallido cuando el bug toca límites, mapeo de datos, contratos de API o permisos.

No pidas a Claude Code “míralo todo”. Una reproducción pequeña vale más que permiso amplio para editar.

No saltes el traspaso de PR. Quien revisa necesita causa, prueba y riesgo residual.

Incluye la ruta de monetización

En ClaudeCodeLab, una corrección puede romper CTAs, tarjetas de producto, formularios de PDF gratuito, enlaces de Gumroad o rutas de consulta. Si cambias layout o rutas de producto, inclúyelas en la verificación.

Para uso individual, adapta la checklist gratuita a tu repositorio. Si necesitas prompts reutilizables, review gates y materiales de setup, revisa products. Si tu equipo necesita un proceso común para bug reports, permisos de Claude Code, PR review y handoff de CI, empieza por training.

Resultado práctico

En pruebas reales, los reportes con reproducción, comportamiento esperado, test fallido y traspaso de PR generaron diffs más pequeños y menos preguntas de review que un “arréglalo”. La mejora más grande vino de pedir tres hipótesis antes de editar. Hace barato descartar teorías equivocadas y convierte la sesión en debugging con evidencia.