Decodificador de errores con Claude Code: de logs a correcciones reproducibles

Cuando empiezas con Claude Code, es tentador pegar un mensaje de error enorme y pedir: “arréglalo”. A veces funciona, pero no es una práctica fiable. Claude Code no puede saber automáticamente qué comando ejecutaste, qué variables de entorno había, qué versión de Node usabas o qué diferencia existe entre tu portátil y CI. El flujo correcto es convertir el error en un informe reproducible y pedir hipótesis, próximos comandos y verificación.

Esta guía cubre stack traces, errores de TypeScript, logs de ejecución de Node.js, Docker/Kubernetes y fallos de GitHub Actions. Para la base oficial, ten a mano Claude Code common workflows, Claude Code troubleshooting y Claude Code settings.

Flujo base: no adivinar, reproducir

Un mensaje de error no es un acertijo: es evidencia. Tu trabajo es conservarla y reducirla sin destruir la pista principal.

flowchart TD
  A["Guardar la salida del comando fallido"] --> B["Reducir ruido sin borrar el log completo"]
  B --> C["Pedir hipótesis y pasos de reproducción"]
  C --> D["Crear el caso mínimo que falla"]
  D --> E["Corregir y repetir el mismo comando"]
  E --> F["Añadir prevención: test, checklist o CLAUDE.md"]

Fuente del error	Material para Claude Code	Qué pedir	Qué verificar tú
TypeScript	Salida completa de tsc --noEmit --pretty false y rutas	Contrato de tipos roto, fix seguro, fix peligroso	Sin any, sin ts-ignore, strict sigue activo
Stack trace Node.js	Primera línea de Error, frames de app, entrada usada	Primer frame útil y entrada mínima	Reproduce con la misma entrada
Docker/Kubernetes	describe, logs anteriores, events	OOM, env, probe, imagen o error de app	Línea de evidencia y comando kubectl
GitHub Actions	Log del job fallido y archivos cambiados	Step fallido, comando local, diferencias de CI	Local y CI pasan

Caso 1: guardar errores de npm y tsc

No copies solo las últimas líneas. Guarda la salida original.

mkdir -p tmp/error-cases
npm test 2>&1 | tee tmp/error-cases/test.log
npx tsc --noEmit --pretty false 2>&1 | tee tmp/error-cases/tsc.log

Luego pide un plan de depuración, no una respuesta mágica.

claude -p "
I need a reproducible fix, not a guess.

Read these files if they exist:
- tmp/error-cases/test.log
- tmp/error-cases/tsc.log

Return:
1. One-line failure summary
2. Likely root cause with confidence level
3. Minimal reproduction steps
4. Next 3 commands to run
5. Smallest safe code change to try
6. Verification command after the fix

Do not hide TypeScript errors with any or ts-ignore.
"

El nivel de confianza evita una trampa común: aceptar una explicación segura en tono, pero débil en evidencia.

Caso 2: minimizar un stack trace de Node.js

Los stack traces largos suelen estar llenos de node_modules. Conserva el log completo y crea una versión corta para el primer análisis.

// scripts/minimize-stacktrace.mjs
import { readFileSync } from "node:fs";

const input = readFileSync(0, "utf8");
const lines = input.split(/\r?\n/);
const kept = [];
let dependencyFrames = 0;

for (const line of lines) {
  const isStackFrame = /^\s+at /.test(line);
  const isDependencyFrame = line.includes("node_modules");

  if (!isStackFrame || !isDependencyFrame || dependencyFrames < 3) {
    kept.push(line);
  }

  if (isStackFrame && isDependencyFrame) {
    dependencyFrames += 1;
  }
}

const important = kept.filter((line) =>
  /Error:|TypeError:|ReferenceError:|SyntaxError:|Caused by:|^\s+at |src\/|app\/|packages\//.test(line)
);

console.log(important.slice(0, 80).join("\n"));

node scripts/minimize-stacktrace.mjs < tmp/error-cases/test.log > tmp/error-cases/test.min.log

claude -p "
Analyze tmp/error-cases/test.min.log first.
If the minimized log is not enough, ask for the full log instead of guessing.

Explain:
- Which application frame is the first useful frame
- What input or state is needed to reproduce it
- Whether this looks like async timing, null data, missing env, or dependency mismatch
- The smallest test that would fail before the fix
"

El script no diagnostica por sí solo. Solo baja el ruido para que el primer frame de la aplicación sea visible.

Caso 3: leer TypeScript como un contrato roto

Type X is not assignable to type Y suele significar que una función esperaba una forma de datos y recibió otra. Es un contrato roto entre quien llama y quien recibe.

claude -p "
Explain this TypeScript error as a broken contract between caller and callee.

Use this output:
$(npx tsc --noEmit --pretty false 2>&1)

Return a table with:
- Error location
- Plain Spanish explanation
- Data shape expected
- Data shape actually provided
- Safe fix
- Risky fix to avoid

Do not suggest any, ts-ignore, or disabling strict mode unless there is no other option.
"

Así separas un arreglo real de una forma de callar al compilador. Si aparece User | null, lo seguro suele ser manejar el estado sin sesión, validar la respuesta de la API o corregir fixtures de test.

Caso 4: convertir logs de Kubernetes en comandos de confirmación

CrashLoopBackOff no es una causa raíz. Es un síntoma.

kubectl get pod -n app
kubectl describe pod web-abc123 -n app > tmp/error-cases/pod.describe.txt
kubectl logs web-abc123 -n app --previous > tmp/error-cases/pod.previous.log
kubectl get events -n app --sort-by=.lastTimestamp > tmp/error-cases/events.log

claude -p "
Triage this Kubernetes crash.

Files:
- tmp/error-cases/pod.describe.txt
- tmp/error-cases/pod.previous.log
- tmp/error-cases/events.log

Return:
1. Most likely category: OOMKilled, missing env, image pull, app exception, probe failure, or dependency outage
2. Evidence lines from the logs
3. One kubectl command to confirm each remaining hypothesis
4. Temporary mitigation
5. Permanent fix
6. Rollback check

If evidence is insufficient, say what command is missing.
"

Si Claude Code no puede señalar la línea de evidencia, todavía estás ante una hipótesis.

Caso 5: triage de GitHub Actions

Los logs de CI esconden el fallo inicial detrás de salidas posteriores. Extrae el log y pide separación entre reproducción local y diferencias de CI.

gh run list --limit 5
gh run view RUN_ID --log > tmp/error-cases/github-actions.log

claude -p "
You are triaging a GitHub Actions failure.

Analyze tmp/error-cases/github-actions.log and return:
1. Failed job and failed step
2. Exact command that failed
3. Whether this should reproduce locally
4. Local reproduction command
5. CI-only differences to inspect: Node version, env vars, cache, timezone, OS, permissions
6. Smallest patch to try
7. Verification plan for local and CI

Do not assume the root cause if the log only shows a downstream symptom.
"

Esto ayuda con tests flaky, zona horaria, secrets ausentes, caché corrupta y diferencias de permisos.

Plantilla de informe de bug

# Bug report: short title

## Goal
What I was trying to do:

## Environment
- OS:
- Node version:
- Package manager:
- Branch:
- Commit:

## Exact command
```bash
paste the exact command here
```

## Expected result
What should have happened:

## Actual result
What happened instead:

## Logs
Paste the full error or attach the saved log file path.

## Minimal reproduction
Smallest steps that still fail:

## What I already tried
- Attempt 1:
- Attempt 2:

## Verification plan
Command that must pass after the fix:

Errores frecuentes

No pegues solo las últimas tres líneas. La causa real suele estar en medio.

No omitas el comando exacto. npm test, npm run build y vitest --run src/foo.test.ts tienen contextos diferentes.

No aceptes any, ts-ignore o tests borrados como solución normal a TypeScript. Pueden ser parches de emergencia, pero no una práctica segura.

No pegues secretos. Quita API keys, cookies, JWT y URLs de base de datos. En equipos, revisa permisos y configuración en settings.

No verifiques primero con otro comando. Repite el comando que falló y luego amplía a lint, build y CI.

Formación, plantillas y consultoría

Para uso individual, estos prompts bastan para empezar. En equipo, lo difícil es normalizar qué logs se comparten, qué fixes están prohibidos, cómo se revisa CI y qué evidencia necesita el reviewer.

ClaudeCodeLab ofrece productos y plantillas de Claude Code y formación y consultoría para crear prompts de debugging reutilizables, plantillas de bug report, checklists de CI y reglas de CLAUDE.md.

Lecturas relacionadas: diagnóstico de errores, técnicas de depuración y logging y monitoreo.

Conclusión

Claude Code no debe adivinar mejor; debe recibir mejor evidencia. Guarda el comando fallido, conserva el log completo, reduce ruido con cuidado, pide hipótesis con confianza y verifica con el mismo comando.

Después de probar este flujo en el mantenimiento real de ClaudeCodeLab, Masa vio la mayor mejora en los primeros 10 minutos de depuración. Guardar tsc --pretty false, minimizar stack traces sin borrar el log original y convertir fallos de CI en job, step, command y reproduction hizo que las sugerencias de Claude Code fueran fáciles de verificar, no algo que hubiera que creer a ciegas.