Wie ich verhindert habe, dass die KI in unserer Codebasis halluziniert

KI-Coding-Tools scheitern an echten Produktionsprojekten. Bei neuem Code funktionieren sie gut. Bei altem Code mit Historie bricht alles zusammen.

Unser Fintech-Projekt hat eine dreijährige Historie. Es umfasst zwei React-Frontends, ein Admin-Panel und ein FastAPI-Backend. Die Datenbank ist komplex, mit vielen Tabellen und aufwendigen Joins.

Wir haben versucht, KI zu nutzen, um schneller voranzukommen. Es ist gescheitert.

Ich bat die KI, eine contacts-Tabelle zu erstellen. Sie erstellte neue Spalten für Namen und E-Mails. Sie erkannte nicht, dass wir diese bereits in unserer users-Tabelle hatten. Sie duplizierte Daten, anstatt einen Fremdschlüssel zu verwenden.

Die KI war nicht dumm. Sie hatte keinen Kontext. Sie traf eine Entscheidung auf Basis unvollständiger Informationen.

Ich hörte auf zu fragen, wie ich besseren Code bekomme. Ich fing an zu fragen, welchen Kontext die KI benötigt, um gute Entscheidungen zu treffen.

Wir haben einen strukturierten Workflow aufgebaut. Eine KI ist nur so gut wie der Kontext, den man ihr liefert. Wir haben diesen Kontext explizit gemacht.

Hier ist unser Setup:

  • ADR-Verzeichnis: Wir haben einen Ordner für Architecture Decision Records erstellt. Diese Dateien erklären, warum wir bestimmte Entscheidungen treffen. Eine Datei weist die KI an, bestehende Tabellen zu prüfen, bevor neue erstellt werden. Sie verbietet die Duplizierung von Benutzerdaten.
  • context.md: Diese Datei erklärt unsere spezifischen Fachbegriffe. Sie sagt der KI, wie unsere eindeutigen Begriffe miteinander zusammenhängen.
  • plot.md: Diese Datei bietet eine Übersichtskarte des Projekts und zeigt, wie die einzelnen Teile zusammenhängen.
  • Verpflichtende Tests: Jede neue API-Route erfordert Testfälle.

Das hat alles verändert. Einmal änderte die KI eine gemeinsam genutzte Utility-Funktion. Die Änderung brachte acht andere Teile des Systems zum Absturz. Die Test-Suite hat es sofort erkannt. Die KI sah den Fehler und korrigierte ihr eigenes Versagen, indem sie eine Version erstellte, die sowohl die alten als auch die neuen Anforderungen erfüllte.

Ohne Tests wäre dieser Bug in die Produktion gelangt.

Behandeln Sie die KI wie einen neuen Entwickler. Man wirft einem neuen Mitarbeiter nicht vor, die Codebasis nicht zu kennen. Man stellt Dokumentation und Onboarding bereit. Das haben wir auch für die KI getan.

Unsere Struktur:

  • docs/context.md: Projektbegriffe und Zusammenhänge.
  • docs/plot.md: Übersichtskarte der Codebasis.
  • docs/adr/: Spezifische Regeln wie Tabellenerstellung und API-Struktur.

Drei Regeln für Ihr Team:

  • Seien Sie in ADRs spezifisch. Verwenden Sie klare Anweisungen anstelle von vagen Ratschlägen.
  • Machen Sie