Claude Code Fehlermeldungen entschlüsseln: Von Logs zu reproduzierbaren Fixes

Wer neu mit Claude Code arbeitet, möchte eine lange Fehlermeldung einfügen und schreiben: “Bitte reparieren.” Manchmal klappt das. Verlässlich ist es nicht. Claude Code kennt nicht automatisch den ausgeführten Befehl, die Umgebungsvariablen, die installierten Versionen oder den Unterschied zwischen lokalem Rechner und CI. Besser ist ein Ablauf, der aus dem Fehler einen reproduzierbaren Bug-Report macht und dann Hypothesen, nächste Befehle und Verifikation anfordert.

Dieser Artikel behandelt Stacktraces, TypeScript-Fehler, Node.js-Laufzeitlogs, Docker/Kubernetes und GitHub-Actions-Fehler. Als offizielle Referenzen helfen Claude Code common workflows, Claude Code troubleshooting und Claude Code settings.

Grundprinzip: Reproduzieren statt raten

Eine Fehlermeldung ist Beweismaterial. Sie sollte vollständig gesichert und dann vorsichtig gekürzt werden.

flowchart TD
  A["Ausgabe des fehlgeschlagenen Befehls speichern"] --> B["Rauschen reduzieren, vollständiges Log behalten"]
  B --> C["Claude Code nach Hypothesen und Reproduktion fragen"]
  C --> D["Kleinsten fehlschlagenden Fall bauen"]
  D --> E["Fix anwenden und denselben Befehl erneut ausführen"]
  E --> F["Prävention ergänzen: Test, Checkliste oder CLAUDE.md"]

Fehlerquelle	Material für Claude Code	Gewünschte Ausgabe	Manuelle Prüfung
TypeScript	Vollständige Ausgabe von tsc --noEmit --pretty false und Pfade	Gebrochener Typvertrag, sicherer Fix, riskanter Fix	Kein any, kein ts-ignore
Node.js Stacktrace	Erste Error-Zeile, App-Frames, Eingabe	Erster nützlicher App-Frame, Reproduktionszustand	Gleiche Eingabe reproduziert lokal
Docker/Kubernetes	describe, previous logs, events	OOM, env, probe, image oder App-Fehler	Beweiszeile und kubectl-Befehl
GitHub Actions	Fehlgeschlagenes Job-Log und geänderte Dateien	Fehlgeschlagener Step, lokaler Befehl, CI-Unterschiede	Lokal und CI bestehen

Fall 1: npm- und tsc-Fehler sichern

Kopiere nicht nur die letzten Zeilen. Sichere zuerst die komplette Ausgabe.

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

Bitte Claude Code dann um einen Diagnoseplan.

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

Das Confidence Level ist wichtig. Wenn Claude Code unsicher ist, brauchst du zuerst einen Prüf-Befehl, nicht direkt einen Patch.

Fall 2: Node.js-Stacktrace verkleinern

Node.js-Stacktraces werden oft von node_modules dominiert. Das Originallog bleibt erhalten, eine gekürzte Kopie dient dem ersten Triage-Schritt.

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

Das Skript diagnostiziert nicht. Es macht nur den ersten relevanten App-Frame sichtbar.

Fall 3: TypeScript als gebrochenen Vertrag lesen

Type X is not assignable to type Y heißt oft: Eine Funktion erwartet eine Datenform, bekommt aber eine andere. Das ist ein gebrochener Vertrag zwischen Caller und Callee.

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

So trennst du echte Fixes von Compiler-Unterdrückung. Bei User | null ist meist ein leerer Login-Zustand, API-Validierung oder ein korrigiertes Test-Fixture besser als ein Cast.

Fall 4: Kubernetes-Logs in Bestätigungsbefehle umwandeln

CrashLoopBackOff ist keine Ursache, sondern ein Symptom.

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

Wenn die Antwort keine Beweiszeile nennt, ist sie weiterhin nur eine Hypothese.

Fall 5: GitHub Actions triagieren

CI-Logs verstecken den ersten Fehler oft hinter Folgeausgaben. Hole das Log und unterscheide lokale Reproduktion von CI-Spezifika.

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

Das hilft besonders bei flaky Tests, Zeitzonenfehlern, fehlenden Secrets, Cache-Problemen und Berechtigungen.

Kopierbare Bug-Report-Vorlage

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

Häufige Fallen

Füge nicht nur die letzten drei Zeilen ein. Die eigentliche Ursache steht oft in der Mitte.

Lass den exakten Befehl nicht weg. npm test, npm run build und vitest --run src/foo.test.ts haben unterschiedliche Kontexte.

Akzeptiere any, ts-ignore oder gelöschte Tests nicht als normalen TypeScript-Fix. Das kann ein Notbehelf sein, aber kein Standard.

Füge keine Secrets ein. Entferne API-Keys, Cookies, JWTs und Datenbank-URLs. Für Teams lohnt ein Blick in die offiziellen settings.

Verifiziere zuerst mit dem Befehl, der fehlgeschlagen ist. Danach kannst du auf lint, build und CI erweitern.

Training, Templates und Beratung

Allein reichen die Prompts aus diesem Artikel für den Start. Im Team geht es um Standards: Welche Logs dürfen geteilt werden, welche Fixes sind verboten, wie wird CI triagiert, welche Beweise erwartet Review?

ClaudeCodeLab bietet Claude-Code-Produkte und Templates sowie Claude-Code-Training und Beratung für wiederverwendbare Debugging-Prompts, Bug-Report-Vorlagen, CI-Checklisten und CLAUDE.md-Regeln.

Mehr dazu: Claude Code Fehlerdiagnose, Claude Code Debugging-Techniken und Claude Code Logging und Monitoring.

Fazit

Claude Code soll nicht stärker raten. Es soll genug Beweise bekommen, um den nächsten reproduzierbaren Schritt zu liefern. Sichere den Befehl, behalte das vollständige Log, reduziere Rauschen vorsichtig, verlange Confidence und prüfe mit demselben Befehl.

Nach dem Test dieses Ablaufs in echter ClaudeCodeLab-Wartung sah Masa den größten Gewinn in den ersten zehn Minuten. tsc --pretty false zu speichern, Stacktraces zu kürzen ohne das Originallog zu löschen und CI-Fehler in job, step, command und reproduction aufzuteilen, machte Claude Codes Vorschläge prüfbar statt nur plausibel.