Diagnóstico de errores con Claude Code: de logs a tests de regresión

Diagnosticar un error no es mirar la última línea roja de la terminal y cambiar código por intuición. Es convertir un fallo en evidencia que otra persona, un runner de tests o Claude Code puedan reproducir.

Hay tres conceptos básicos. Un log es el registro que deja un comando o una aplicación. Un stack trace es la ruta de llamadas que llevó al error. Una reproducción mínima es el ejemplo más pequeño que sigue fallando después de quitar UI, datos y configuración que no aportan.

Claude Code funciona mucho mejor cuando no le pedimos solo “arregla esto”. Dale el comando que falló, la primera línea relevante, un conjunto pequeño de hipótesis y el comando que debe pasar después del arreglo.

Para complementar este flujo, revisa el bucle de triage de errores de build, el decodificador de mensajes de error y la plantilla de reporte de bug.

Flujo de diagnóstico

flowchart LR
  A["Guardar comando fallido"] --> B["Encontrar primera falla"]
  B --> C["Limitar a tres hipótesis"]
  C --> D["Crear repro mínima"]
  D --> E["Añadir test de regresión"]
  E --> F["Aplicar arreglo mínimo"]
  F --> G["Verificar con el mismo comando"]
  G --> H["Escribir nota de traspaso"]

El orden evita un patrón peligroso: editar primero y probar después. Claude Code puede leer muchos archivos, así que una instrucción demasiado amplia puede terminar en limpieza no relacionada. El objetivo no es cambiar más código; es reducir la causa.

Empieza reuniendo cuatro datos.

Evidencia	Para qué sirve	Ejemplo para Claude Code
Comando fallido	Fija la reproducción	npm run build, node --test
Primera línea fallida	Evita ruido del final del log	TypeError, ERR_MODULE_NOT_FOUND
Contexto de ejecución	Separa diferencias de entorno	Versión de Node.js, OS, CI
Comportamiento esperado	Define el arreglo correcto	null se vuelve array vacío, 404 no se reintenta

Para nombres de errores JavaScript, usa MDN JavaScript error reference. En Node.js, la documentación de Node.js Errors ayuda a priorizar campos estables como error.code antes que textos de mensaje. Para E2E, Playwright debugging docs permite mirar Inspector, Trace Viewer y depuración en VS Code.

Flujo práctico con Claude Code

Usa este prompt como unidad estándar de trabajo.

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
"

“Hasta tres” no es un detalle menor. Diez hipótesis no se verifican bien. Para Cannot read properties of undefined, normalmente basta con API con forma distinta, valor inicial ausente o render antes de que llegue la carga asíncrona.

Caso 1: undefined en React

Un caso típico es que la API devuelva null y el componente llame users.map(...). Parece un problema de renderizado, pero suele ser un contrato de datos roto.

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

Si la implementación anterior era return users.map(...), el primer test falla. Pide a Claude Code que añada primero el test fallido y después aplique el cambio más pequeño.

Caso 2: ENOENT e imports en Node.js

ENOENT suele indicar que falta un archivo o directorio. La trampa común es que config/local.json exista en tu máquina pero no en CI ni dentro de Docker.

Mira el comando fallido, error.code, error.path, el COPY del Dockerfile, .gitignore y el working directory de 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.
"

No basta con crear el archivo perdido. Si la configuración es obligatoria, falla temprano con un mensaje claro. Si es opcional, usa un valor por defecto. Si CI necesita un ejemplo, copia un archivo sample versionado.

Caso 3: Playwright falla solo en CI

Los timeout de Playwright mezclan bugs de aplicación, esperas mal definidas, CI lenta, sesión expirada y red distinta. Aumentar timeout puede ocultar el problema.

Guarda trazas en fallos.

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

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

Entrega a Claude Code el spec fallido, locator, estado esperado de pantalla, ruta del trace y comando de CI. La instrucción debe ser: “antes de subir timeouts, separa estado de UI, respuesta de API, autenticación y problema de locator”.

Caso 4: errores TypeScript en cadena

Veinte errores TypeScript pueden venir de una sola definición de API cambiada.

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.
"

No arregles todo a la vez. Corrige el tipo raíz, ejecuta el mismo comando y revisa solo lo que queda. Ese bucle evita parches con as any.

Clasificar logs antes de leer todo

Este script se puede ejecutar tal cual y sirve para crear una primera categoría.

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

No reemplaza el diagnóstico; solo separa dependencias, rutas, forma de datos, esperas E2E y tipos antes de que la conversación crezca.

Plantilla reproducible de bug report

Antes de pedir investigación, reescribe el bug así. En GitHub puedes convertirlo en formulario con la sintaxis oficial de GitHub issue forms.

## 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`

La frase importante no es “algo falla”; es “estos pasos reproducen el mismo fallo”.

Errores frecuentes

Primero, pegar solo la última línea del log. Conserva la primera falla y las líneas cercanas.

Segundo, depender del texto del mensaje. En Node.js, prefiere error.code o name cuando existan.

Tercero, saltar la reproducción mínima. En una pantalla completa es difícil saber si corregiste la causa o solo cambiaste el timing.

Cuarto, arreglar sin test de regresión. El bug puede volver en el próximo refactor.

Quinto, dar demasiado alcance a Claude Code. Pide el cambio mínimo para que pase este fallo concreto. Para límites de revisión, revisa la checklist de workflow de revisión.

Nota de traspaso

Cuando la verificación pasa, deja una nota breve.

## 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.
"

Plantillas y consultoría

En proyectos personales basta con copiar estos comandos y plantillas. En equipos hay que definir qué logs se pueden compartir, qué secretos no deben pegarse en Claude Code, dónde viven las reproducciones mínimas, qué artifacts conserva CI y qué prueba pide el revisor.

ClaudeCodeLab ofrece productos y plantillas de Claude Code y formación y consultoría para equipos que quieren estandarizar reportes de bugs, prompts de triage, tests de regresión y notas de traspaso.

Al aplicar este flujo en mantenimiento real de ClaudeCodeLab, Masa vio la mayor mejora al fijar tres hábitos: guardar la primera línea fallida, crear una reproducción mínima y volver a ejecutar el mismo comando. Las sugerencias de Claude Code dejaron de ser intuiciones y pasaron a venir con evidencia, hipótesis, test y verificación.