Claude Code Fehlerdiagnose: Von Logs zu Regressionstests

Fehlerdiagnose bedeutet nicht, die letzte rote Zeile im Terminal zu lesen und dann nach Gefühl Code zu ändern. Es geht darum, einen Fehlschlag in Belege zu verwandeln, die ein anderer Entwickler, ein Test-Runner oder Claude Code reproduzieren kann.

Drei Begriffe reichen für den Einstieg. Ein Log ist die Aufzeichnung einer Anwendung oder eines Befehls. Ein Stack Trace zeigt den Pfad der Funktionsaufrufe bis zum Fehler. Eine minimale Reproduktion ist das kleinste Beispiel, das nach dem Entfernen unnötiger UI, Daten und Konfiguration immer noch fehlschlägt.

Claude Code liefert bessere Ergebnisse, wenn die Aufgabe nicht nur “fix this” lautet. Gib den fehlgeschlagenen Befehl, die erste relevante Fehlerzeile, wenige Hypothesen und den Verifikationsbefehl mit.

Ergänzend passen der Claude Code Build Error Triage Loop, der Claude Code Error Message Decoder und das Claude Code Bug Report Template.

Diagnoseablauf

flowchart LR
  A["Fehlbefehl speichern"] --> B["Erste Fehlerzeile finden"]
  B --> C["Auf drei Hypothesen begrenzen"]
  C --> D["Minimale Repro erstellen"]
  D --> E["Regressionstest ergänzen"]
  E --> F["Kleinsten Fix anwenden"]
  F --> G["Mit gleichem Befehl prüfen"]
  G --> H["Übergabenotiz schreiben"]

Diese Reihenfolge verhindert “erst ändern, später beweisen”. Claude Code kann viele Dateien lesen; eine zu breite Anweisung führt leicht zu nicht zusammenhängenden Aufräumarbeiten. Das Ziel ist nicht mehr Änderung, sondern eine engere Ursache.

Sammle zuerst vier Belege.

Beleg	Zweck	Beispiel für Claude Code
Fehlgeschlagener Befehl	Fixiert die Reproduktion	npm run build, node --test
Erste Fehlerzeile	Vermeidet Log-Rauschen am Ende	TypeError, ERR_MODULE_NOT_FOUND
Laufzeitkontext	Trennt Umgebungsfehler	Node.js Version, OS, CI
Erwartetes Verhalten	Definiert den richtigen Fix	null wird leeres Array, 404 wird nicht wiederholt

Für JavaScript-Fehlernamen ist die MDN JavaScript error reference hilfreich. Für Node.js ist die Dokumentation zu Node.js Errors wichtig, weil stabile Diagnose eher error.code als fragile Nachrichtentexte nutzt. Bei E2E-Tests helfen die Playwright debugging docs mit Inspector, Trace Viewer und VS Code Debugging.

Praktischer Claude Code Workflow

Nutze diesen Prompt als Standardauftrag.

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
"

“Bis zu drei” ist Absicht. Zehn Hypothesen werden selten sauber geprüft. Bei Cannot read properties of undefined reichen oft API-Shape geändert, Initialwert fehlt oder Rendering passiert vor der asynchronen Datenladung.

Fall 1: React undefined Fehler

Ein typischer Fall: Die API liefert null, aber die UI ruft users.map(...) auf. Das sieht nach React aus, ist aber meist ein gebrochener Datenvertrag.

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

Wenn der alte Code nur return users.map(...) war, schlägt der erste Test fehl. Claude Code sollte zuerst diesen Test ergänzen und dann nur die kleinste Änderung vornehmen.

Fall 2: Node.js ENOENT und Importfehler

ENOENT bedeutet meist, dass eine Datei oder ein Ordner fehlt. Die Falle: config/local.json existiert lokal, aber nicht in CI oder im Docker-Image.

Prüfe den Fehlbefehl, error.code, error.path, Dockerfile COPY, .gitignore und das working directory der 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.
"

Beende die Diagnose nicht mit “Datei anlegen”. Wenn die Konfiguration Pflicht ist, soll die App früh mit klarer Meldung fehlschlagen. Wenn sie optional ist, nutze Defaults. Wenn CI ein Beispiel braucht, kopiere eine versionierte sample-Datei.

Fall 3: Playwright scheitert nur in CI

Playwright-Timeouts mischen App-Bug, falsche Wartebedingung, langsamere CI, abgelaufene Authentifizierung oder Netzwerkunterschiede. Nur den Timeout zu erhöhen versteckt oft die Ursache.

Bewahre Traces bei Fehlern auf.

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

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

Gib Claude Code den fehlgeschlagenen spec, locator, erwarteten Bildschirmzustand, Trace-Pfad und CI-Befehl. Die Anweisung sollte lauten: “Bevor Timeouts erhöht werden, trenne UI-Zustand, API-Antwort, Authentifizierung und Locator-Problem.”

Fall 4: TypeScript-Kettenfehler

Zwanzig TypeScript-Fehler können von einer einzigen geänderten API-Typdefinition stammen.

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

Korrigiere nicht alles auf einmal. Fixe den Ursprungstyp, führe denselben Befehl erneut aus und betrachte nur verbleibende Fehler. Dieser Loop reduziert unnötige as any-Patches.

Logs zuerst grob klassifizieren

Dieses kleine Skript ist direkt ausführbar und gibt eine erste Kategorie aus.

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

Das ersetzt keine Diagnose. Es trennt Abhängigkeiten, Dateipfade, Datenform, E2E-Wartebedingungen und TypeScript-Fehler, bevor die Diskussion unübersichtlich wird.

Reproduzierbare Bug-Report-Vorlage

Vor der Untersuchung sollte der Bug so formuliert werden. Mit GitHub Issues kann die offizielle GitHub issue forms syntax dieselben Felder als Formular abbilden.

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

Wichtig ist nicht “es ist kaputt”, sondern “diese Schritte reproduzieren denselben Fehler”.

Häufige Fallen

Erstens: nur die letzte Logzeile einfügen. Bewahre die erste Fehlerzeile und die Umgebung davon.

Zweitens: auf Nachrichtentext verzweigen. In Node.js sind error.code oder name meist stabiler.

Drittens: keine minimale Reproduktion bauen. In einer kompletten Seite ist unklar, ob die Ursache weg ist oder nur Timing geändert wurde.

Viertens: ohne Regressionstest fixen. Dann kehrt der Fehler beim nächsten Refactor zurück.

Fünftens: Claude Code zu viel Scope geben. Fordere die kleinste Änderung für genau diesen Fehlschlag. Review-Grenzen beschreibt die Claude Code Review Workflow Checklist.

Übergabenotiz schreiben

Wenn die Verifikation durchläuft, bleibt eine kurze Notiz.

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

Templates und Beratung

Für Solo-Projekte reichen die Befehle und Vorlagen aus diesem Artikel. Teams sollten zusätzlich festlegen, welche Logs geteilt werden dürfen, welche Secrets nie in Claude Code gehören, wo minimale Repros liegen, welche CI-Artifacts bleiben und welche Nachweise Reviewer erwarten.

ClaudeCodeLab bietet Claude Code Produkte und Templates sowie Claude Code Training und Beratung für Teams, die Bug-Report-Formulare, CI-Triage-Prompts, Regressionstests und Übergabenotizen standardisieren möchten.

Beim Einsatz in der ClaudeCodeLab-Wartung sah Masa den größten Effekt in drei Gewohnheiten: erste Fehlerzeile sichern, minimale Reproduktion erstellen und denselben Befehl nach dem Fix erneut ausführen. Claude Code Vorschläge wurden dadurch prüfbar: mit Beleg, Hypothese, Test und Verifikation.