Bucle de triaje de errores de build con Claude Code en 15 minutos

Divide el error antes de pedir el arreglo

Cuando falla un build de Node, Astro, Vite o Next.js, parece rápido pegar todo el log en Claude Code y pedir una reparación completa. En la práctica, ese log mezcla la primera línea fallida, trazas posteriores, ruido del gestor de paquetes y limpieza no relacionada. El build puede terminar pasando, pero el review queda débil porque nadie sabe qué cambio corrigió la causa real.

Este artículo aplica la plantilla de bug report, el checklist de review y el workflow de verificación a errores de build. La meta no es una reparación heroica, sino reducir la causa a una hipótesis en 15 minutos, hacer el cambio mínimo y dejar evidencia revisable.

Un harness es el andamio del agente. Claude Code puede leer y razonar sobre el repositorio, pero tú decides qué parte del log importa, qué hipótesis se permite y qué comando demuestra el arreglo. Ese andamio evita que un build fix se convierta en refactor amplio.

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]

El bucle de 15 minutos

Divide el trabajo en tres bloques de cinco minutos. En el primero solo capturas evidencia: git status, comando de build fallido, primera línea fallida y archivos relacionados. No edites todavía. En el segundo bloque eliges una hipótesis: dependencia, import path, frontmatter, forma de datos, permisos, red o expectativa de test.

Solo en el tercer bloque cambias código o configuración. Después ejecutas el comando que falló y guardas la prueba. En un sitio de contenido o ingresos, una build verde no basta. También revisa URL del artículo, h1, canonical, imagen hero, CTA, enlace de producto y enlace de training. Si el build pasa pero rompe la conversión, sigue siendo un problema de producción.

La nota de trabajo de Masa para este flujo tiene tres líneas: causa, cambio, evidencia. El reviewer necesita ver por qué se eligió esa hipótesis, qué se tocó y qué comando o URL lo comprobó. Pedirle a Claude Code esas tres líneas reduce la revisión y deja una pista útil para el siguiente incidente.

Captura evidencia en orden fijo

Ejecuta siempre los mismos comandos en el mismo orden. En macOS, Linux o WSL, este ejemplo shell guarda el log y mantiene el 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

En Windows PowerShell, usa npm.cmd de forma explícita para evitar diferencias 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

El primer intento no tiene que pasar. Su trabajo es conservar la primera falla útil. La última traza puede ser ruido; la primera línea de error suele estar más cerca de la raíz.

Clasifica la primera falla con Node

Guarda este script como scripts/triage-build-log.mjs y ejecútalo con node scripts/triage-build-log.mjs build.log. No arregla nada; convierte un log grande en un grupo y una dirección de diagnóstico.

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

La clasificación no necesita ser perfecta. Su valor es cambiar el prompt de “arregla el build” a “demuestra o descarta este grupo antes de editar”. Así reduces upgrades de dependencias, null checks defensivos y limpiezas que ocultan la causa.

Usa documentación oficial como frontera

Los problemas de conexión, autenticación, límites y errores de runtime de Claude Code se verifican en Claude Code Error reference. Si parece que CLAUDE.md, settings, hooks o MCP no cargan, revisa Debug your configuration.

En sitios Astro, frontmatter y content collections se contrastan con Astro Content Collections. Para códigos de Node como ERR_MODULE_NOT_FOUND, usa Node.js Errors. Separar estas fuentes evita culpar a Claude Code cuando el problema es del build de la app, o al revés.

Primera acción según la forma del log

Forma del log	Primera sospecha	Primera acción
Cannot find module	import path, archivo generado, dependencia	Verificar archivo y path antes de instalar
ERR_MODULE_NOT_FOUND	ESM/CJS, extensión, package exports	Comparar error de Node y package config
undefined is not	data shape, frontmatter, API response	Imprimir un registro real antes de añadir null checks
Expected ... received	cambio de spec, fixture, snapshot	Clasificar si es cambio previsto o regresión
permission denied	sandbox, usuario CI, ruta de escritura	Revisar working directory y permisos
solo Build failed	primer error aguas arriba	Extraer el primer error, no la última traza

En un sitio Astro, undefined is not an object puede ser un heroImage, pubDate o lang faltante en un locale. Un null guard amplio podría pasar el build y esconder un problema de calidad editorial.

Prompt copiable para Claude Code

Lee este build log fallido.
No propongas refactors amplios.
Todavía no edites archivos.

Devuelve:
1. primera línea fallida
2. una causa más probable
3. comando diagnóstico mínimo para esa causa
4. cambio mínimo de código o configuración permitido
5. comando de prueba después del arreglo
6. tres líneas para PR: causa, cambio, evidencia

Si hay otras personas editando el repositorio, añade el alcance: solo este slug, no tocar reports, no revertir cambios no relacionados y preservar los identity fields del frontmatter. Ese marco evita conflictos más que cualquier prompt elegante.

Cuatro casos de uso reales

El primer caso es un sitio Astro multilingüe. Un locale con frontmatter inválido, una code fence MDX sin cerrar, una imagen hero ausente o un enlace interno roto puede tumbar el build. Pide a Claude Code comparar solo los diez archivos del slug y validar YAML, fences y longitud del body.

El segundo caso es un fallo de import en Node CLI o package. Cannot find module no siempre significa instalar algo. Puede ser typo, archivo generado ausente, regla exports o mezcla ESM/CJS. Antes de tocar dependencias, usa node -p "require.resolve('package-name')" o una verificación directa de archivos.

El tercer caso es una falla solo en CI. Puede venir de permisos, rutas case-sensitive, versión de Node, secret mal nombrado o proxy. Antes de cambiar código, lista OS de CI, working directory, Node version, variables de entorno y rutas de escritura.

El cuarto caso es deriva de expectativas de test. Expected ... received se puede silenciar actualizando snapshots, pero eso puede aceptar una regresión. En CTA, precios, enlaces Gumroad, formularios de training o metadata, decide si el cambio era esperado.

Errores comunes

Primer error: leer solo el final del log. La traza final puede ser consecuencia, no causa. Guarda la primera línea fallida y las 30 líneas anteriores.

Segundo error: actualizar dependencias demasiado pronto. Un package update toca lockfile, cache de CI y compatibilidad runtime. Si la causa era un typo de import path, la revisión se vuelve innecesariamente grande.

Tercer error: parar con build verde. En un sitio público confirma /en/products/, /en/training/, formulario de PDF gratuito, h1 y canonical.

Cuarto error: aceptar limpieza oportunista. Un PR de build-fix debe mantener visible la hipótesis. Si mezclas formatting, refactor, dependencias y contenido, nadie sabrá qué corrigió el fallo.

CTA de productos y formación

Para convertir este flujo en prompts, checklists y material reutilizable, empieza por ClaudeCodeLab products. Si tu equipo necesita CI gates, CLAUDE.md, permisos, receipts de review y verificación de producción adaptados a un repositorio real, usa Claude Code training and consultation.

Como lectura siguiente, revisa permission audit checklist y CI/CD setup. Para práctica individual basta fijar comandos con el PDF gratuito; para equipos hacen falta prompt compartido, formato común de evidencia y dueño claro de aprobación.

Resultado al probarlo

Al usar este bucle, el diff se vuelve más pequeño. En vez de entregar todo el log a Claude Code, la sesión empieza con una línea fallida, una hipótesis y un comando de prueba. Así se separan antes los problemas de frontmatter, archivos generados, import path y permisos de CI. El valor principal no es el primer arreglo, sino el recibo breve que queda para la siguiente falla.