Debugging mit KI-Agenten: systematisch statt raten

Agenten debuggen am besten mit reproduzierbarem Fehler, echten Logs und einer Hypothese vor dem Fix – nicht mit „fix den Bug".

Der häufigste Fehler

Viele geben einem Agenten nur „Fix den Bug" – ohne Fehlermeldung, ohne Kontext. Dann rät der Agent. Systematisches Debugging funktioniert anders.

Schritt 1: Fehler reproduzieren

Gib dem Agenten das Kommando, mit dem der Fehler auftritt, und lass ihn den Fehler selbst auslösen. Die Claude-Code-Doku empfiehlt genau das: dem Agenten sagen, wie er das Problem reproduziert und einen Stacktrace bekommt. Ein Fehler, den der Agent selbst auslösen kann, ist auch einer, den er nach dem Fix selbst verifizieren kann.

Schritt 2: Logs und Stacktraces füttern

Füge die komplette Fehlermeldung ein, statt sie zu beschreiben. Auch per Pipe möglich: cat error.log | claude -p "erkläre die Ursache". Sag dazu, ob der Fehler immer oder nur manchmal auftritt.

Schritt 3: Hypothese vor Fix

Lass den Agenten erst wahrscheinliche Ursachen nennen, sortiert nach Wahrscheinlichkeit – und dann gezielt eine prüfen. Wichtig: die Ursache beheben, nicht das Symptom. Die offizielle Doku formuliert es als Prompt-Regel: „address the root cause, don't suppress the error".

Diagnose-Tools

Für Probleme mit Claude Code selbst gibt es /doctor: einen automatischen Check von Installation, Einstellungen, Erweiterungen und Kontext-Nutzung. Startet claude gar nicht, hilft claude doctor direkt aus der Shell.

BEISPIEL

Prompt: „npm test schlägt fehl. Hier der komplette Stacktrace: [einfügen]. Reproduziere den Fehler, nenne die wahrscheinlichste Ursache und schreib erst einen fehlschlagenden Test, bevor du etwas fixst."

🛠️ ÜBUNG — MACH DAS BEI DIR

Baue absichtlich einen kleinen Bug in ein Übungsprojekt ein (z. B. einen Tippfehler in einem Variablennamen) und lass einen Agenten ihn systematisch finden.

Löse den Fehler aus und kopiere die komplette Fehlermeldung samt Stacktrace.
Gib dem Agenten Fehlermeldung und Reproduktions-Kommando – und verlange zuerst eine Hypothese, noch keinen Fix.
Lass den Fix erst umsetzen, nachdem du die Hypothese gelesen hast, und lass den Agenten den Erfolg mit demselben Kommando verifizieren.

✅ SELBST-CHECK

☐ Hat der Agent die richtige Ursache genannt, bevor er etwas geändert hat?
☐ Hat er den Fix mit dem Reproduktions-Kommando belegt (Ausgabe gezeigt), statt nur „erledigt" zu sagen?
☐ Was hätte gefehlt, wenn du nur „da ist ein Bug" geschrieben hättest?

KURZ-QUIZ

Was ist der sinnvollste erste Schritt, wenn ein Agent einen Bug beheben soll?