Claude Code Build-Fehler-Triage: Ursache in 15 Minuten eingrenzen

Erst triagieren, dann reparieren lassen

Wenn ein Node-, Astro-, Vite- oder Next.js-Build fehlschlägt, wirkt es schnell, das komplette Log in Claude Code zu kopieren und eine vollständige Reparatur zu verlangen. Genau dann vermischen sich erste Fehlerzeile, spätere Stacktraces, Package-Manager-Rauschen und Aufräumarbeiten. Der Build kann danach grün sein, aber im Review bleibt unklar, welcher Change die Ursache wirklich gelöst hat.

Diese Schleife überträgt das Bug-Report-Template, die Review-Workflow-Checkliste und den Verification-Receipt-Workflow auf Buildfehler. Ziel ist nicht der große Reparaturwurf. Ziel ist, die Ursache in 15 Minuten auf eine Hypothese einzugrenzen, minimal zu ändern und prüfbare Evidenz zu hinterlassen.

Ein Harness ist das Gerüst für den Agenten. Claude Code liest und denkt mit, aber Sie legen fest, welches Log zählt, welche Hypothese erlaubt ist und welcher Befehl den Fix beweist. Dieses Gerüst verhindert, dass ein Build-Fix in einen breiten Refactor kippt.

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]

Die 15-Minuten-Schleife

Teilen Sie die Arbeit in drei Blöcke zu je fünf Minuten. Der erste Block sammelt Belege ohne Dateiänderung: git status, fehlgeschlagener Buildbefehl, erste Fehlerzeile und relevante Dateien. Der zweite Block wählt genau eine Hypothese: Dependency, import path, Frontmatter, Datenform, Berechtigung, Netzwerk oder Test-Erwartung.

Erst im dritten Block wird Code oder Konfiguration geändert. Danach wird der fehlgeschlagene Befehl erneut ausgeführt und der Beweis notiert. Bei Content- und Revenue-Sites reicht ein grüner Build nicht. Prüfen Sie Artikel-URL, h1, canonical, hero image, CTA, Produktlink und Training-Link. Ein Build, der die Conversion bricht, ist immer noch ein Produktionsproblem.

Masas Arbeitsnotiz besteht aus drei Zeilen: Ursache, Änderung, Beweis. Reviewer müssen sehen, warum diese Hypothese gewählt wurde, was geändert wurde und welcher Befehl oder welche URL es bewiesen hat. Wenn Claude Code am Ende diese drei Zeilen liefert, wird der nächste Vorfall schneller.

Belege immer gleich erfassen

Führen Sie die Befehle immer in derselben Reihenfolge aus. Unter macOS, Linux oder WSL speichert dieses Shell-Beispiel das Log und behält den Exit-Code.

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

In Windows PowerShell ist npm.cmd explizit besser, weil verschiedene Shells npm unterschiedlich auflösen können.

$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

Der erste Lauf muss nicht erfolgreich sein. Er soll die erste brauchbare Fehlermeldung sichern. Der letzte Stacktrace kann Folgefehler sein; die erste Error-Zeile liegt meist näher an der Ursache.

Erste Fehlerzeile mit Node klassifizieren

Speichern Sie dieses Skript als scripts/triage-build-log.mjs und führen Sie node scripts/triage-build-log.mjs build.log aus. Es repariert nichts, sondern reduziert ein großes Log auf eine Kategorie und eine nächste Diagnose.

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

Diese Klassifikation muss nicht perfekt sein. Sie ändert die Aufgabe von “Build reparieren” zu “diese Kategorie vor Dateiänderungen beweisen oder ausschließen”. Dadurch sinkt die Gefahr von unnötigen Dependency-Upgrades, breiten Null-Checks und kosmetischen Änderungen.

Offizielle Doku als Grenze nutzen

Verbindungs-, Authentifizierungs-, Limit- und Runtime-Meldungen von Claude Code gehören in die Claude Code Error reference. Wenn CLAUDE.md, settings, hooks oder MCP nicht zu laden scheinen, nutzen Sie Debug your configuration.

Bei Astro-Content-Sites sind Frontmatter und Content Collections gegen Astro Content Collections zu prüfen. Node-Codes wie ERR_MODULE_NOT_FOUND gehören zu Node.js Errors. Diese Trennung verhindert, dass ein App-Build-Problem als Claude-Code-Problem behandelt wird.

Erste Aktion nach Log-Form

Log-Form	Erste Vermutung	Erste Aktion
Cannot find module	import path, generierte Datei, Dependency	Datei und Pfad prüfen, bevor ein Paket installiert wird
ERR_MODULE_NOT_FOUND	ESM/CJS, Extension, package exports	Node-Error und Package-Konfiguration vergleichen
undefined is not	Datenform, Frontmatter, API-Antwort	Einen echten Datensatz ausgeben, bevor Null-Checks kommen
Expected ... received	Spec-Änderung, Fixture, Snapshot	Erst gewollte Änderung oder Regression klassifizieren
permission denied	Sandbox, CI-User, Schreibpfad	Working directory und Rechte prüfen
nur Build failed	erste Upstream-Fehlerzeile	Erste Error-Zeile extrahieren, nicht den letzten Trace

Bei einer Astro-Artikelsite kann undefined is not an object bedeuten, dass in einer Locale heroImage, pubDate oder lang fehlt. Ein globaler Guard kann den Build grün machen und trotzdem ein redaktionelles Qualitätsproblem verstecken.

Kopierbarer Claude-Code-Prompt

Lies dieses fehlgeschlagene build log.
Schlage keine breiten Refactors vor.
Bearbeite noch keine Dateien.

Gib zurück:
1. erste fehlgeschlagene Zeile
2. eine wahrscheinlichste Ursache
3. kleinstes Diagnosekommando für diese Ursache
4. kleinster erlaubter Code- oder Config-Change
5. Prüfkommando nach dem Fix
6. drei PR-Zeilen: Ursache, Änderung, Beweis

Wenn andere Personen im Repository arbeiten, ergänzen Sie den Scope: nur diesen Slug prüfen, keine Reports ändern, keine fremden Änderungen zurücksetzen und Frontmatter-Identitätsfelder erhalten. Diese Grenzen verhindern Konflikte.

Vier praktische Use Cases

Der erste Fall ist eine mehrsprachige Astro-Content-Site. Ungültiges Frontmatter in einer Locale, eine offene MDX-Code-Fence, fehlendes Hero-Bild oder ein falscher interner Link kann den Build brechen. Claude Code sollte nur die zehn Dateien des Slugs vergleichen und YAML, Fences und Body-Länge prüfen.

Der zweite Fall ist ein Node-CLI- oder Package-Importfehler. Cannot find module heißt nicht automatisch fehlende Dependency. Es kann ein Tippfehler, eine nicht generierte Datei, eine exports-Regel oder ESM/CJS-Mischung sein. Vor Dependency-Änderungen hilft node -p "require.resolve('package-name')" oder eine direkte Dateiprüfung.

Der dritte Fall ist ein Fehler nur in CI. Ursachen sind oft Berechtigungen, case-sensitive paths, andere Node-Version, falsch benannter Secret oder fehlender Proxy. Vor App-Code-Änderungen sollten CI-OS, working directory, Node-Version, Variablennamen und Schreibziele sichtbar sein.

Der vierte Fall ist Test-Erwartungsdrift. Expected ... received lässt sich leicht durch Snapshot-Update kaschieren, kann aber eine Regression freigeben. Bei CTA, Preistext, Gumroad-Link, Training-Formular oder Artikel-Metadata muss zuerst klar sein, ob die Änderung beabsichtigt war.

Konkrete Fallen

Erste Falle: nur das Log-Ende lesen. Der letzte Stacktrace kann Folge sein, nicht Ursache. Speichern Sie die erste Fehlerzeile und die 30 Zeilen davor.

Zweite Falle: Dependencies zu früh aktualisieren. Ein Package-Update verändert Lockfile, CI-Cache und Runtime-Kompatibilität. Bei einem import path typo macht es den Review nur größer.

Dritte Falle: beim grünen Build stoppen. Eine öffentliche Site muss auch /en/products/, /en/training/, Free-PDF-Formular, h1 und canonical bestätigen.

Vierte Falle: opportunistisches Aufräumen. Ein Build-Fix-PR braucht eine sichtbare Hypothese. Wenn Formatting, Refactor, Dependencies und Content gemischt werden, verschwindet der Beweis.

Produkte und Beratung

Wenn diese Schleife als wiederverwendbare Prompts, Checklisten und Setup-Material gebraucht wird, starten Sie mit ClaudeCodeLab products. Wenn Ihr Team CI-Gates, CLAUDE.md, Permission-Regeln, Review-Receipts und Produktionsprüfung für ein echtes Repository braucht, nutzen Sie Claude Code training and consultation.

Als nächste Lektüre passen permission audit checklist und CI/CD setup. Einzelpersonen können mit dem kostenlosen PDF Kommandos festigen; Teams brauchen ein gemeinsames Prompt, ein gemeinsames Beweisformat und klare Freigabeverantwortung.

Ergebnis im Einsatz

Mit dieser Schleife wird der Diff kleiner. Statt Claude Code das ganze Log zu geben, beginnt die Sitzung mit einer Fehlerzeile, einer Hypothese und einem Prüfkommando. So lassen sich fehlendes Frontmatter, fehlende generierte Dateien, import path typos und CI-Permissions schneller trennen. Der wichtigste Gewinn ist der kurze Beweis, der für den nächsten Fehler bleibt.