KI-Halluzinationen in Legacy-Code verhindern: So klappt’s in 3 Schritten

Mit KI lassen sich Software-Projekte schneller vorantreiben – zumindest in der Theorie. Doch wer sie auf bestehendem Code einsetzt, stößt schnell an Grenzen. Die Software von heute ist komplex: Legacy-Systeme mit verschachtelten Abhängigkeiten, spezifischen Fachbegriffen und implizitem Wissen. Genau hier scheitern KI-Tools, die auf statische Trainingsdaten setzen. Ein Fintech-Unternehmen machte diese Erfahrung am eigenen Leib und entwickelte ein System, um KI-Halluzinationen systematisch zu unterbinden.

Warum KI in Legacy-Code oft falsche Entscheidungen trifft

Das Problem trat erstmals bei einer scheinbar einfachen Aufgabe zutage: die Erstellung einer neuen Kontakt-Tabelle. Die KI generierte zwar eine funktionale Lösung mit Feldern für Vorname, Nachname und E-Mail. Doch statt die bestehenden Daten aus der Nutzer-Tabelle zu nutzen, wurden diese einfach dupliziert. Das Ergebnis? Redundante Datenbankfelder, erhöhte Fehleranfälligkeit und ein Schema, das gegen gängige Normalisierungsregeln verstößt.

Die Ursache war kein technischer Defekt, sondern ein Mangel an Kontext. Die KI kannte die Struktur des Projekts nicht – und traf daher Entscheidungen basierend auf allgemeinen Programmiermustern, nicht auf den spezifischen Anforderungen des Fintech-Systems. Solche Fehler sind besonders tückisch, weil sie oft erst im Produktivbetrieb auffallen. Die Konsequenz: Manuelles Nachbessern wird zur Notwendigkeit, und das Vertrauen in KI-Tools schwindet.

Drei Schritte zu zuverlässiger KI-Unterstützung

Statt die KI zu beschuldigen, änderte das Team seine Herangehensweise. Der Fokus lag nicht mehr darauf, die KI zu verbessern, sondern die Umgebung so zu gestalten, dass sie fundierte Entscheidungen treffen kann. Drei zentrale Maßnahmen erwiesen sich als entscheidend:

1. Entscheidungsdokumentation als Leitfaden für die KI

Das Team führte ein System aus Architektur-Entscheidungsprotokollen (ADRs) ein. Jedes Protokoll dokumentiert nicht nur technische Fakten, sondern auch die Gründe hinter Entscheidungen. Ein Beispiel ist ADR-001, das regelt, wie neue Tabellen angelegt werden:

# ADR-001: Tabellenerstellung in bestehenden Datenbanken

**Kontext:** Neue Tabellen werden häufig ohne Berücksichtigung bestehender Strukturen erstellt, was zu Datenredundanzen führt.

**Entscheidung:** Vor der Erstellung einer neuen Tabelle muss geprüft werden, ob relevante Felder bereits in bestehenden Tabellen existieren. Falls ja, ist eine Fremdschlüssel-Beziehung zu bevorzugen. Neue Spalten, die thematisch zu bestehenden Tabellen passen, sind dort zu integrieren.

**Konsequenzen:** Vermeidung von Daten-Duplikaten und Konsistenz der Datenbankstruktur.

**Ausnahme:** Nur wenn sich eine neue Tabelle logisch nicht in bestehende Strukturen einordnen lässt, darf sie eigenständig erstellt werden.

Diese Regeln werden zentral in einem Verzeichnis docs/adrs/ abgelegt. Jedes neue Teammitglied – ob Mensch oder KI – erhält damit sofortigen Einblick in die Design-Prinzipien des Projekts. Die KI kann nun bei Aufgaben wie der Tabellenerstellung gezielt auf diese Vorgaben zugreifen und vermeidet so grundlegende Fehler.

2. Kontextdateien für fachliche Klarheit

Neben technischen Regeln benötigte das Team auch eine klare Erklärung der fachlichen Begriffe. In vielen Legacy-Projekten haben sich über Jahre spezifische Konzepte etabliert, die für Außenstehende – oder KI-Systeme – nicht sofort verständlich sind. Das Team erstellte daher zwei zentrale Dokumente:

• `context.md`: Enthält eine Glossar-ähnliche Auflistung aller projektspezifischen Begriffe. Beispiele:
• Was bedeutet der Begriff „Konto“ im Fintech-Kontext?
• Wie unterscheidet sich ein „Benutzer“ von einem „Kunden“?
• Welche Daten gehören in die „Transaktionshistorie“ und welche in die „Nutzerverwaltung“?

• `plot.md`: Bietet eine hochrangige Übersicht über das gesamte System. Welche Komponenten gibt es? Wie interagieren sie miteinander? Welche externen Dienste werden genutzt?

Beide Dokumente beginnen mit einem klaren Hinweis: „Diese Regeln sind verbindlich. Die Dokumentation im Ordner `docs/` ist die einzige autoritative Quelle für das Verständnis des Projekts.“

3. Automatisierte Tests als Sicherheitsnetz

Die dritte Säule des Systems sind automatisierte Tests – und zwar für jeden neu erstellten Endpunkt. Das Team verpflichtete sich zu einer einfachen Regel: Keine neue API-Route ohne Testfälle. Diese Tests dienen nicht nur der Qualitätssicherung, sondern auch als Feedback-Mechanismus für die KI.

Ein konkretes Beispiel zeigt, warum das so wichtig ist: Die KI modifizierte eine gemeinsam genutzte Hilfsfunktion, die in zwölf verschiedenen API-Routen verwendet wurde. Die Änderung war lokal sinnvoll, führte aber in acht Routen zu Fehlern. Der Testlauf erkannte das Problem sofort und meldete es an die KI. Diese analysierte die Fehler, identifizierte die Ursache in der Hilfsfunktion und erstellte eine neue Version, die sowohl die alte als auch die neue Funktionalität abdeckte. Die KI behob ihren eigenen Fehler – ohne menschliches Eingreifen.

Ohne diese Tests wäre der Fehler unbemerkt in die Produktion gelangt. Mit dem Testsystem wird die KI jedoch zu einem selbstkorrigierenden System.

Auswirkungen auf das Entwicklungsteam

Die Skepsis im Team war anfangs groß. Viele Entwickler hatten bereits schlechte Erfahrungen mit KI-Tools gemacht, die unzuverlässige oder sogar gefährliche Code-Vorschläge lieferten. Doch nach der Einführung des neuen Systems änderte sich die Wahrnehmung. Drei Teammitglieder baten darum, das System auch in ihren eigenen Projekten zu adaptieren.

Der entscheidende Unterschied lag nicht darin, die KI zu vertrauen, sondern ihr klare Rahmenbedingungen zu geben. So wie neue Mitarbeiter zunächst in die Codebasis eingeführt werden müssen, benötigt auch KI strukturierte Onboarding-Dokumente. Die Verantwortung für Fehler liegt dann nicht bei der KI, sondern bei der fehlenden oder unklaren Dokumentation.

So können Sie es selbst umsetzen

Die Implementierung dieses Systems ist mit wenig Aufwand möglich, erfordert aber Disziplin. Folgende Schritte sind essenziell:

• Erstellen Sie ein Verzeichnis `docs/adrs/` und fügen Sie die ersten Architektur-Entscheidungen hinzu. Nutzen Sie dabei konkrete Beispiele aus Ihrem Projekt.
• Dokumentieren Sie fachliche Begriffe in einer context.md-Datei. Halten Sie die Sprache einfach und vermeiden Sie Abkürzungen ohne Erklärung.
• Erstellen Sie ein `plot.md`, das die wichtigsten Komponenten Ihres Systems skizziert. Visualisierungen wie Flussdiagramme oder UML-Diagramme können hier hilfreich sein.
• Verpflichten Sie Ihr Team zu 100% Testabdeckung für neue API-Routen. Nutzen Sie bestehende Frameworks wie Jest, Pytest oder JUnit.
• Reagieren Sie auf jeden KI-Fehler mit einer neuen ADR. Jeder Fehler ist eine Chance, die Dokumentation zu verbessern und zukünftige Probleme zu vermeiden.

Fazit: KI als verlässlicher Partner statt unberechenbarer Helfer

Dieses System macht KI nicht fehlerfrei – aber es macht sie berechenbar. Die KI trifft weiterhin Fehler, doch diese sind nun kleiner, leichter zu erkennen und lassen sich systematisch beheben. Der größte Vorteil liegt jedoch darin, dass das Team schneller arbeiten kann, ohne ständig manuelle Korrekturen vornehmen zu müssen.

Das Ziel war nie eine KI, die alles richtig macht. Es war eine KI, die konsistent agiert und dem Team ermöglicht, sich auf die wirklich wichtigen Aufgaben zu konzentrieren: Innovation und Weiterentwicklung der Software. Mit der richtigen Struktur wird KI zu einem Werkzeug, das nicht nur Geschwindigkeit, sondern auch Qualität in die Entwicklung bringt.