Refactoring mit KI: Mein eigener KI-Workflow für Legacy-Code im Detail

Beim Refactoring von Legacy-Code geht es nie nur darum, Code zu verändern. Zuerst muss man verstehen, was das System heute macht. Man muss die Regeln, die Sonderfälle und die versteckten Entscheidungen kennen, die bereits im Projekt stecken.

KI kann bei dieser Arbeit sehr helfen – aber nur, wenn man sie gut anleitet. Wer eine KI zu früh bittet, Code neu zu schreiben, riskiert, dass wichtige Details übersehen werden. Mein Workflow ist anders. Ich nutze KI zuerst, um den Code zu verstehen, dann zum Planen und erst danach für die Umsetzung.

In diesem Beitrag zeige ich einen einfachen Workflow, den ich beim Refactoring von Legacy-Code mit KI verwende. Es geht darum, die KI mit Dokumentation einzuarbeiten, mögliche Lösungen zu untersuchen, agentenbasiertes Programmieren mit einem klaren Ziel einzusetzen und die Dokumentation nach der Arbeit aktuell zu halten.

Schritt 1: Die KI mit Dokumentation einarbeiten

Bevor das Refactoring beginnt, lasse ich mir von der KI helfen, den aktuellen Stand des Codes zu dokumentieren. In diesem Schritt erwähne ich weder Refactoring noch Neuschreiben oder Verbessern. Das einzige Ziel ist, den bestehenden Zustand zu verstehen.

Das ist wichtig, weil eine KI Kontext braucht. Wenn sie das aktuelle System nicht versteht, kann sie Änderungen vorschlagen, die gut aussehen, aber echtes Verhalten kaputtmachen.

Normalerweise erstelle ich einen neuen Ordner namens ai-docs. Darin lege ich Dokumentation für die konkrete Funktion oder den Bereich an, den ich bearbeiten möchte.

Wenn ich zum Beispiel den Zahlungsablauf überarbeiten möchte, erstelle ich:

ai-docs/payment-flow.md

Danach bitte ich die KI, die zugehörigen Dateien zu untersuchen und den aktuellen Stand zu dokumentieren. Das Dokument soll erklären, was die Funktion macht, welche Dateien beteiligt sind, wie Daten durch das System fließen und welche Sonderfälle bereits existieren.

Das Dokument soll die Software so beschreiben, wie sie heute ist. Ein Plan für das Refactoring gehört an dieser Stelle noch nicht hinein.

Schritt 2: Die Möglichkeiten verstehen

Sobald die Dokumentation fertig ist, verwende ich sie als Grundlage für ein Gespräch mit der KI.

Auch in diesem Schritt bearbeite ich noch keinen Code. Das Ziel ist, die Möglichkeiten zu verstehen. Ich stelle Fragen wie:

Welche Teile dieser Funktion sind riskant zu verändern?
Welche Sonderfälle sollte ich absichern?
Was wäre der einfachste Ansatz für das Refactoring?
Was soll sich aus Sicht der Nutzerinnen und Nutzer nicht verändern?
Welche Tests oder manuellen Prüfungen würden mir Sicherheit geben?

In diesem Schritt geht es um Planung. Ich erkläre der KI mein Ziel und bitte sie um einen möglichen Weg. Danach hinterfrage ich den Plan. Ich frage nach einfacheren Optionen, kleineren Schritten und möglichen Problemen.

Bei kleinen Refactorings reicht manchmal eine Planungsrunde. Bei größeren Änderungen überarbeite ich den Plan mehrmals. Je wichtiger die Funktion ist, desto mehr Zeit nehme ich mir dafür.

Ein guter Plan ist so klar, dass sich der nächste Schritt fast schon mechanisch anfühlt.

Schritt 3: Mit einem klaren Ziel umsetzen

Jetzt ist es Zeit, den Code zu bearbeiten.

Zu diesem Zeitpunkt kennt die KI bereits die Dokumentation des aktuellen Zustands und den Refactoring-Plan. Dadurch wird agentenbasiertes Programmieren viel nützlicher. Statt einfach „Überarbeite diesen Code“ zu sagen, gebe ich der KI ein klares Ziel und einen klaren Weg vor.

Zum Beispiel:

Überarbeite den Zahlungsablauf auf Basis von ai-docs/payment-flow.md.
Folge dem Plan, den wir vereinbart haben.
Das Verhalten nach außen muss gleich bleiben.
Nimm kleine, gezielte Änderungen vor.
Führe nach jedem wichtigen Schritt die zugehörigen Prüfungen aus.

So bleibt die Arbeit kontrolliert. Die KI muss nicht bei null anfangen und raten. Sie kennt das aktuelle Verhalten, das Ziel und den Weg.

Mit diesem Vorgehen ist die Umsetzung meistens deutlich schneller. Die schwierige Denkarbeit ist bereits erledigt, bevor sich der Code verändert.

Schritt 4: Die Dokumentation aktualisieren

Nach dem Refactoring aktualisiere ich die Dokumentation in ai-docs.

Diesen Schritt lässt man leicht aus, aber er ist wichtig. Die Dokumentation soll den neuen Stand des Projekts oder der Funktion beschreiben. Die alte Legacy-Version darf nicht die wichtigste Informationsquelle bleiben.

Veraltete Dokumentation kann die KI später verwirren. Wenn das Dokument weiterhin die alte Struktur beschreibt, kann die nächste KI-Sitzung falsche Informationen verwenden und unpassende Änderungen vorschlagen.

Deshalb halte ich die Dokumentation sauber. Sie soll erklären, wie der Code jetzt – nach dem Refactoring – funktioniert.

Abschließende Gedanken

Für mich funktioniert Refactoring mit KI am besten, wenn ich die KI wie ein Teammitglied behandle, das zuerst eingearbeitet werden muss.

Zuerst gebe ich ihr Kontext. Dann untersuche ich die Möglichkeiten. Danach lasse ich sie bei der Umsetzung helfen. Zum Schluss aktualisiere ich die Dokumentation, damit die nächste Arbeitsrunde mit dem richtigen Stand beginnt.

Dieser Workflow ist am Anfang langsamer, spart aber später Zeit. Er reduziert Spekulationen, schützt wichtiges Verhalten und macht es leichter, Legacy-Code Schritt für Schritt zu verbessern.