Code mit KI debuggen: ein praktischer Workflow

Um Code mit KI zu debuggen, gibst du dem Agenten eine Möglichkeit, den Bug zu reproduzieren, den vollständigen Fehler samt Logs und eine klare Regel: erst die Ursache finden, dann etwas ändern. Ein Coding-Agent wie Claude Code oder Codex kann deine Tests ausführen, Stacktraces lesen, deine Git-Historie per Bisect durchsuchen und Logging einbauen, und ist damit ein starker Partner beim Debuggen. Er scheitert aber auch auf vorhersehbare Weise: Er rät, wenn er den fehlschlagenden Fall nicht ausführen kann, und „behebt“ Symptome, indem er Fehler abfängt oder Tests lockert.

Diese Anleitung ist ein Ablauf, der die Stärken nutzt und gegen die Schwächen absichert: reproduzieren, Beweise liefern, eingrenzen, erklären, fixen, mit einem Test absichern und wissen, wann man die Reißleine zieht.

Warum Agenten beim Debuggen danebenliegen

Die meisten schlechten KI-Fixes haben dieselben paar Ursachen:

• Keine Reproduktion. Der Agent liest den Code, bildet eine Theorie und patcht. Nichts beweist, dass die Theorie stimmte.
• Unvollständige Beweise. Du fügst die letzte Zeile des Fehlers ein. Der nützliche Frame, drei Ebenen tiefer im Stack, erreicht das Modell nie.
• Das Symptom fixen. Ein Null-Check, ein try/catch oder ein Retry lässt den Fehler verschwinden, während der fehlerhafte Zustand, der ihn verursacht hat, bestehen bleibt.
• Die Torpfosten verschieben. Der Test schlägt fehl, also bearbeitet der Agent den Test.
• Lange, verschmutzte Sessions. Nach fünf gescheiterten Versuchen ist die Unterhaltung voller falscher Theorien, und das Modell baut weiter darauf auf.

Jeder der folgenden Schritte zielt auf eines dieser Probleme.

Schritt 1: den Bug zuerst reproduzieren

Bevor der Agent Code anfasst, braucht er einen Befehl, der den Bug zeigt. Das kann ein fehlschlagender Test sein, ein curl-Aufruf, ein Skript oder eine Seite im Browser. Entscheidend ist, dass jeder, auch der Agent, ihn ausführen und den Fehler sehen kann.

Wenn du schon einen hast, setz ihn an den Anfang des Prompts:

Das schlägt fehl:

  pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Erwartete Summe 90, erhalten 81. Ändere noch keinen Code.
Führe den Test aus, bestätige, dass du denselben Fehler siehst, und sag mir, was du siehst.

Wenn du keine Reproduktion hast, mach sie zur ersten Aufgabe:

Nutzer melden, dass zweimaliges Speichern eines Entwurfs zwei Entwürfe erzeugt.
Schreib einen fehlschlagenden Test, der das reproduziert. Behebe nichts.
Hör auf, sobald der Test aus dem richtigen Grund fehlschlägt.

„Aus dem richtigen Grund“ ist wichtig. Ein Test, der wegen eines Tippfehlers im Test fehlschlägt, beweist nichts. Lass dir vom Agenten die Fehlerausgabe zeigen und erklären, warum sie zur Fehlermeldung passt. Bei sporadischen Bugs lässt du ihn die Reproduktion in einer Schleife ausführen (zum Beispiel 50-mal) und berichten, wie oft sie fehlschlägt, damit du später erkennst, ob ein Fix wirklich geholfen hat.

Schritt 2: dem Agenten alle Beweise geben

Agenten sind gut darin, lange, unübersichtliche Ausgaben zu lesen. Kürze sie nicht für sie. Gib ihnen:

• den vollständigen Stacktrace, nicht nur die Meldung;
• den exakten Befehl und seine vollständige Ausgabe;
• relevante Logs rund um den Zeitpunkt des Fehlers;
• was sich zuletzt geändert hat: ein Dependency-Update, ein Deploy, ein gemergter Branch;
• Details zur Umgebung, falls sie eine Rolle spielen könnten: Betriebssystem, Runtime-Version, Feature-Flags.

Du musst nicht alles in den Chat einfügen. Speichere es in einer Datei und verweise den Agenten darauf, oder leite es direkt hinein. Mit dem Print-Modus von Claude Code:

pnpm test 2>&1 | tail -n 200 > /tmp/test-output.txt
cat /tmp/test-output.txt | claude -p "Explain the root cause of this failure. Don't edit files."

In einer interaktiven Session führt ! sowohl in Claude Code als auch in Codex einen Shell-Befehl aus und legt seine Ausgabe in die Unterhaltung, zum Beispiel !pnpm test src/billing. Bei riesigen Logs bittest du den Agenten, per grep nach der Request-ID oder dem Fehlercode zu suchen, statt die ganze Datei zu lesen; das spart viel vom Kontextfenster.

Schritt 3: mit git bisect eingrenzen

Wenn etwas früher funktioniert hat und jetzt nicht mehr, brauchst du keine Theorie. git bisect findet den ersten schlechten Commit per Binärsuche und kann vollautomatisch laufen, was es zu einer perfekten Aufgabe für einen Agenten macht.

Schreib zuerst ein kleines Skript, das mit 0 endet, wenn der Code gut ist, und mit einem anderen Wert, wenn er schlecht ist:

#!/bin/sh
# check.sh
pnpm install --frozen-lockfile >/dev/null 2>&1 || exit 125
pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Dann lässt du git die Arbeit machen:

git bisect start
git bisect bad HEAD
git bisect good v2.3.0
git bisect run ./check.sh
git bisect reset

Die Exit-Codes sind der Vertrag, so wie die offizielle git bisect-Dokumentation sie festlegt: 0 bedeutet gut, jeder Code von 1 bis 127 außer 125 bedeutet schlecht, 125 bedeutet „dieser Commit lässt sich nicht testen, überspringen“, und alles darüber bricht den Bisect ab. Deshalb endet der Installationsschritt oben mit 125: Ein Commit, der sich nicht einmal installieren lässt, soll übersprungen und nicht als schlecht gezählt werden.

Ein Prompt, der das Ganze einem Agenten übergibt:

Der Rabatt-Test für Rechnungen besteht auf dem Tag v2.3.0 und schlägt auf main fehl.
Schreib ein Check-Skript für git bisect run (exit 125, wenn der Commit
nicht gebaut werden kann), führe den Bisect aus, dann git bisect reset.
Nenne den ersten schlechten Commit und erkläre, welche Zeile in seinem Diff
den Fehler verursacht. Behebe noch nichts.

Sorg vorher für einen sauberen Working Tree, oder mach es in einem separaten Git-Worktree, damit die Checkouts des Bisects nicht mit deiner eigenen Arbeit kollidieren. Wenn es die Testdatei in alten Commits noch nicht gab, kopiere sie an einen Pfad außerhalb des Repos und lass das Skript diese Kopie ausführen.

Schritt 4: Logging einbauen und wieder entfernen

Wenn der Stacktrace den Zustand nicht erklärt, der zum Fehler geführt hat, muss der Agent Werte zur Laufzeit sehen. Bitte um gezieltes, temporäres Logging:

Füge temporäre Logs hinzu, die die Warenkorb-Artikel, die Rabattliste und
die laufende Summe bei jedem Schritt von applyDiscounts() ausgeben. Stell jeder Zeile
[DEBUG-1234] voran, damit wir sie später finden und entfernen können. Führe den
fehlschlagenden Test aus und zeig mir die Log-Zeilen.

Das Präfix ist der Trick. Sobald der Bug verstanden ist, räumt eine einzige Anweisung auf:

git grep -n "DEBUG-1234"

Agenten kommen auch gut mit Debuggern zurecht, wenn diese skriptbar sind: node --inspect mit einem Breakpoint ist für einen Terminal-Agenten umständlich, aber eine kurze python -m pdb-Session, eine zusätzliche Assertion oder ein einmaliges Skript, das die Funktion mit der fehlschlagenden Eingabe aufruft, liefert meist schneller dieselbe Antwort.

Schritt 5: erst die Ursache, dann der Fix

Das ist die wichtigste Regel. Lass dir vom Agenten den Bug erklären, bevor er einen Fix schreibt, und lies die Erklärung:

Bevor du Code änderst, erkläre die Ursache:
1. Welcher Zustand ist falsch, und wo wird er zum ersten Mal falsch?
2. Warum erzeugt der Code diesen Zustand?
3. Warum haben die bestehenden Tests das nicht erkannt?
Schlag dann den kleinsten Fix vor und warte auf mein OK.

Eine gute Antwort zeigt auf eine bestimmte Zeile und eine bestimmte Bedingung („der Rabatt wird sowohl in addItem als auch in checkout angewendet, seit Commit a1b2c3 den Aufruf verschoben hat“). Eine schwache Antwort ist vage („es könnte ein Problem damit geben, wie Rabatte behandelt werden“) oder springt direkt zu einem defensiven Patch. Bekommst du die schwache Sorte, hat der Agent die Ursache noch nicht gefunden; schick ihn zurück zu Schritt 3 oder 4.

Der Plan-Modus von Claude Code ist hier nützlich, weil der Agent lesen und schreibgeschützte Befehle ausführen kann, aber keine Dateien bearbeitet, bis du zustimmst. Starte ihn mit claude --permission-mode plan oder drück Shift+Tab, um dorthin zu wechseln. Claude Code Plan-Modus behandelt ihn im Detail. In Codex erfüllt /plan einen ähnlichen Zweck.

Schritt 6: fixen und mit einem Regressionstest absichern

Jetzt lässt du den Agenten den Fix umsetzen, mit Vorgaben:

Setz den Fix um. Regeln:
- Bestehende Tests nicht bearbeiten oder überspringen.
- Den Fehler nicht abfangen und verschlucken.
- Füge einen nach dem Bug benannten Regressionstest hinzu, der ohne
  den Fix fehlschlägt und mit ihm besteht. Beweise beides: Nimm den Fix zurück, führe den
  Test aus, stell den Fix wieder her, führe ihn erneut aus.
- Führe am Ende die komplette Testsuite aus.

Der Teil „beweise beides“ macht den Test vertrauenswürdig. Ein Regressionstest, der auch vor dem Fix bestanden hätte, ist Dekoration. Mehr dazu, wie du von einem Agenten brauchbare Tests bekommst, findest du in Unit-Tests mit KI schreiben.

Prüf dann den Diff selbst und achte auf die üblichen Symptom-Fixes:

Manchmal ist eines davon der richtige Fix. Die entscheidende Frage ist, ob der Agent erklärt hat, warum.

Browser-Bugs: gib dem Agenten einen Browser

UI-Bugs lassen sich schwer in Text beschreiben: ein Button, der nichts tut, ein Layout, das nach einem Klick zerfällt, ein Fehler, der nur in der Konsole auftaucht. Mit Playwright MCP kann der Agent die Seite öffnen und selbst nachsehen. Füge es zu Claude Code hinzu:

claude mcp add playwright npx @playwright/mcp@latest

oder zu Codex in ~/.codex/config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Tools wie browser_navigate, browser_click, browser_snapshot, browser_console_messages und browser_network_requests lassen den Agenten den Bug Schritt für Schritt reproduzieren, die Konsolenfehler lesen und sehen, welcher API-Aufruf fehlgeschlagen ist. Ein Debugging-Prompt:

Starte den Dev-Server. Öffne http://localhost:5173/settings, ändere den
Anzeigenamen und klick auf Save. Berichte Konsolenfehler und den Netzwerk-
Request für das Speichern, mit Status und Response-Body. Noch nichts fixen.

Sobald die Ursache klar ist, bitte den Agenten, die Schritte in einen Playwright-Test umzuwandeln, damit der Bug behoben bleibt. Browser-Tests mit KI-Agenten geht tiefer auf die Einrichtung ein.

Bugs, die nur in CI auftreten

Wenn Tests lokal bestehen, aber in CI fehlschlagen, liegt der Unterschied meist in der Umgebung: Zeitzone, Locale, Parallelisierung, fehlende Umgebungsvariablen, eine andere Node- oder Python-Version oder die Testreihenfolge. Gib dem Agenten das CI-Log und die Workflow-Datei und bitte ihn, die Unterschiede zwischen CI und deinem Rechner aufzulisten, bevor er rät. Die Suite in zufälliger Reihenfolge oder mit der Zeitzone der CI (TZ=UTC pnpm test) auszuführen, reproduziert den Fehler oft lokal. Wenn CI-Fehler eine regelmäßige Pflichtübung sind, zeigt CI-Fehler automatisch mit KI beheben, wie du die Schleife automatisierst.

Wann du den Agenten stoppen solltest

Ein Agent probiert weiter, lange nachdem er hätte aufhören sollen. Zieh die Reißleine, wenn:

• zwei oder drei Fixes gescheitert sind. Jeder neue Versuch baut auf derselben falschen Theorie auf.
• sich der Diff ausbreitet. Er hat in invoice.ts angefangen und bearbeitet jetzt Konfiguration, unbeteiligte Module oder Lock-Dateien.
• er die Tests anfasst. Eine Assertion an die falsche Ausgabe anzupassen, ist nie ein Bugfix.
• er den Bug nicht reproduzieren kann, ihn aber trotzdem fixt.
• sich die Erklärung von Runde zu Runde ohne neue Beweise ändert.

Was du stattdessen tust:

1. Stopp die Runde (Esc in Claude Code und Codex).
2. Mach seine Änderungen rückgängig. Committe, bevor du mit dem Debuggen anfängst, damit dich git restore . oder git stash zurückbringt; Änderungen von Claude Code rückgängig machen zeigt die Möglichkeiten.
3. Schreib auf, was du gelernt hast: welche Theorien falsch waren und warum.
4. Starte eine frische Session mit der Reproduktion, den Fakten und den ausgeschlossenen Theorien. Ein sauberer Kontext mit drei guten Fakten schlägt einen langen mit zehn schlechten Vermutungen.

Manchmal ist der richtige Schritt, eine engere Frage zu stellen: „Ist cart.items schon falsch, wenn checkout() aufgerufen wird?“ lässt sich leichter beantworten als „behebe den Checkout-Bug“.

Debuggen mit AgentVera

AgentVera ist eine Desktop-App für macOS, Windows und Linux, die Claude Code, Codex, Gemini CLI und andere CLI-Agenten in echten Terminals nebeneinander ausführt. Mehrere ihrer Werkzeuge passen zum obigen Ablauf:

• An Agent senden: Markiere einen Fehler im Terminal-Dock, in der Browser-Konsole oder in Docker-Logs und schick ihn mit ⌘⇧L an einen Agenten, oder klick auf das Fix-Badge bei einem erkannten Fehler. Lange Logs werden auf 12.000 Zeichen begrenzt und behalten ihr Ende, wo meist der Stacktrace steht.
• Agent-Browser: ein Chrome mit separatem Profil, den Agenten über Playwright MCP steuern, mit live übertragenen Tabs, sodass du zusehen kannst, wie der Agent den Bug reproduziert.
• Checkpoints: Jede Runde wird als Snapshot in einer versteckten Git-Ref gesichert, sodass du sehen kannst, was ein gescheiterter Versuch geändert hat, und diese Runde rückgängig machen kannst, ohne deine Branches oder deinen Stash anzufassen.
• Zwei Theorien parallel: Starte im Git-Panel zwei Agenten in getrennten Worktrees, gib jedem eine andere Hypothese und behalte den Fix, der standhält.
• Verify: In Pro und Team werden Kriterien wie „der Regressionstest schlägt ohne den Fix fehl und besteht mit ihm“ von einem separaten, schreibgeschützten Prüfer kontrolliert, wenn die Runde des Agenten endet.

Sobald der Bug behoben ist, schreib auf, was du gelernt hast, und zwar dort, wo die nächste Person es findet; Dokumentation mit KI schreiben deckt diese Seite ab.

Fazit

Debuggen mit einem KI-Agenten funktioniert, wenn du es wie Debuggen mit einem scharfsinnigen Kollegen behandelst: Starte mit einer Reproduktion, teile alle Beweise, grenze die Suche mit git bisect ein, baue Logging ein, um echte Werte zu sehen, und bestehe auf der Ursache, bevor gefixt wird. Beende jeden Bug mit einem Regressionstest, den du hast fehlschlagen und bestehen sehen. Und wenn der Agent zu raten beginnt, stopp ihn, mach alles rückgängig und fang mit dem Gelernten frisch an.