Warum KI-Code-Schulden unsichtbar sind – und wie Architektur sie stoppt

Künstliche Intelligenz hat längst Einzug in die Softwareentwicklung gehalten. Doch während sie Code generiert, entstehen neue Formen technischer Schulden – unsichtbar, systemisch und schwer zu beheben. Diese Schulden sind keine klassischen Codefehler, sondern strukturelle Musterbrüche, die sich mit jeder neuen KI-Sitzung wiederholen.

Was KI-Schulden von traditionellen unterscheidet

Technische Schulden entstehen in der Softwareentwicklung seit Jahrzehnten. Doch die durch KI verursachten Schulden folgen anderen Regeln:

• Verursacher: Traditionelle Schulden entstehen durch bewusste Entscheidungen von Entwicklern. KI-Schulden entstehen unbewusst, während die KI Code generiert.

• Sichtbarkeit: Klassische Schulden zeigen sich im Git-Verlauf. KI-Schulden bleiben unsichtbar, da sie über Sitzungen hinweg nicht dokumentiert werden.

• Skalierung: Traditionelle Schulden betreffen meist ein Team oder ein Projekt. KI-Schulden wirken systemisch und betreffen die gesamte Codebasis.

Die zentrale Erkenntnis: Je mehr ein Team KI für die Entwicklung nutzt, desto schneller und unmerklicher häufen sich diese Schulden an. Und bisher gibt es keine Tools, die sie sichtbar machen.

Fünf Warnsignale für KI-Schulden in Ihrem Team

Ein kurzer Selbsttest hilft, den aktuellen Stand einzuschätzen:

• Doppelte Implementierungen: KI baut eine Funktion neu, obwohl eine ähnliche bereits existiert.

• Inkonsistente Muster: Der generierte Code folgt Mustern, die nicht zum restlichen Codebase passen.

• Unsichtbare Abhängigkeiten: KI nutzt keine bestehenden Implementierungen, die nur wenige Zeilen entfernt liegen.

• Wiederholte Fehler: Jede neue KI-Sitzung wiederholt dieselben Fehler, die bereits korrigiert wurden.

• Neuinterpretation: KI behandelt eine vertraute Codebasis, als wäre sie unbekannt.

Treffen drei oder mehr Punkte zu, besteht akuter Handlungsbedarf. Besonders in größeren Teams mit hohem KI-Einsatz summieren sich diese Schulden schnell.

Ein reales Beispiel: Die stateService-Katastrophe

Als Maintainer des Open-Source-Projekts toolBoxClient – einer KI-Agenten-Laufzeitumgebung mit über 270 Sternen – erlebte ich diese Probleme am eigenen Leib. Die Aufgabe: eine neue stateService-Komponente hinzufügen.

Im Verzeichnis server/services/ befanden sich bereits zahlreiche Services, die alle einem einheitlichen HTTP-Muster folgten:

server/services/
├── fingerPrintService.js
├── memoryService.js
├── providerModelService.js
├── proxyService.js
├── taskService.js
├── toolServiceManager.js
├── walletService.js
└── webSocketService.js

Jeder Service folgte dem gleichen HTTP-basierten Architekturstil. Doch die KI ignorierte diese Struktur vollständig. Stattdessen generierte sie folgenden Code (Commit 68487cc, 19. März 2026):

class StateClient {
  constructor(agentName) {
    // ❌ WebSocket statt HTTP – komplett inkonsistent
    this.ws = new WebSocket(...)
    this._data = {}
    this.state = this._createProxy()
  }

  _createProxy() {
    // ❌ Proxy-basiertes Broadcast-Muster – einzigartig im Codebase
    return new Proxy(this._data, { ... })
  }
}

Die KI hatte nicht nur eine parallele Architektur geschaffen, sondern auch ein Muster eingeführt, das in keinerlei Beziehung zum bestehenden Code stand. Das Problem war kein Bug im Code, sondern ein Musterbruch – die KI hatte die bestehende Architektur einfach nicht erkannt.

Der erste Lösungsversuch: Projektgedächtnis

Mein erster Ansatz war naheliegend: Ich fügte einen Hinweis zum Projektgedächtnis hinzu:

„Nutze bestehende HTTP-Services. Vermeide WebSocket-Implementierungen.“

Prompt angepasst, KI neu gestartet – und tatsächlich generierte sie korrekten Code (Commit bbdf82c, 21. März 2026):

feat: stateService Phase A+B — HTTP CRUD + SSE Broadcast
Phase A: /api/state/* Endpunkte (Lesen, Schreiben, Session-CRUD, Sprachpräferenz)
Phase B: SSE-Abonnement-Endpunkt mit Themenfilterung + EventBus-Broadcast
74/74 Tests bestanden. Keine Breaking Changes – nur additive Ergänzungen.

Der WebSocket-Code war verschwunden. Stattdessen entstand eine saubere HTTP-basierte Lösung mit Server-Sent Events (SSE), die perfekt in die bestehende Architektur passte.

Doch meine Euphorie währte nur kurz. Mir wurde klar:

Dieser Erfolg funktionierte nur, weil ich ihn manuell korrigiert hatte.

Die nächste KI-Sitzung würde von vorne beginnen – ohne Erinnerung an die vorherige Korrektur. Jeder neue Kontext war ein leeres Blatt Papier. Das Problem war nicht gelöst, sondern nur verschoben worden.

Warum Projektgedächtnis nicht skaliert

Der Ansatz, KI durch manuelle Hinweise zu steuern, scheitert aus mehreren Gründen:

• Manuelle Pflege: Jede Korrektur muss erneut eingegeben werden, da KI keine langfristige Erinnerung hat.

• Skalierungsproblem: Mit wachsender Codebasis wird die Pflege immer aufwendiger.

• Fehleranfälligkeit: Menschliche Eingaben sind fehleranfällig und inkonsistent.

• Keine Systemlösung: Es handelt sich um eine temporäre Lösung, keine strukturelle Änderung.

Die eigentliche Herausforderung liegt nicht in der KI selbst, sondern in der Architektur der Codebasis. KI braucht keine größeren Kontextfenster – sie braucht eine persistente, strukturelle Repräsentation des Projekts, die über Sitzungen hinweg verfügbar ist.

Die Lösung: Projektgraph als struktureller Anker

Aus dieser Erkenntnis entstand das Projekt aming-claw – ein Tool, das eine maschinell lesbare Graph-Repräsentation der Codebasis erstellt und diese an jede KI-Sitzung übergibt.

Wie es funktioniert:

• Code-Scanning: Das Tool analysiert die gesamte Codebasis und erstellt einen Graphen aller Entitäten (Dateien, Module, Funktionen) und deren Beziehungen.

• MCP-Server: Ein dedizierter Server stellt diesen Graphen als API bereit, die jede KI abfragen kann.

• Vor dem Schreiben: Bevor die KI neuen Code generiert, liest sie den aktuellen Graphen und passt ihr Verhalten entsprechend an.

• Persistenz: Der Graph bleibt über Sitzungen hinweg erhalten und wird bei jedem Commit aktualisiert.

Doch der erste Implementierungsversuch scheiterte schnell. Der Grund:

Der Graph wurde zur zweiten Wahrheit.

Ich hatte beschlossen, dass nicht nur die KI, sondern auch Entwickler den Graphen direkt bearbeiten könnten. Innerhalb weniger Wochen driftete der Graph von der tatsächlichen Codebasis ab. Es entstanden zwei Quellen der Wahrheit:

• Die eigentliche Codebasis als primäre Quelle
• Der bearbeitbare Graph als sekundäre Quelle

Das Ergebnis war dasselbe Problem – nur auf einer höheren Ebene.

Die finale Erkenntnis: Der Graph ist ein Commit-Projektion

Nach mehreren gescheiterten Versuchen kristallisierte sich die Lösung heraus:

Der Graph ist keine eigenständige Datenstruktur. Er ist eine Projektion des Commits.

Konkrete Umsetzung bedeutet:

• Automatische Generierung: Der Graph wird bei jedem Commit automatisch aus dem aktuellen Stand der Codebasis generiert.

• Unveränderlichkeit: Der Graph wird nicht bearbeitet, sondern immer neu aus dem Code generiert.

• Integration in den Workflow: Vor jedem KI-generierten Commit wird der Graph gegen die Codebasis geprüft. Bei Abweichungen erhält der Entwickler eine Warnung.

Technische Umsetzung:

1. Commit-Hook: Ein Git-Hook prüft vor jedem Commit, ob der Graph noch der aktuellen Codebasis entspricht.

1. Graph-Snapshot: Bei jedem Commit wird ein Snapshot des Graphen erstellt und im Repository gespeichert.

1. KI-Integration: KI-Tools lesen den Graphen aus dem Repository und nutzen ihn als Kontext für Codegenerierung.

1. Warnungen bei Abweichung: Wenn sich die Codebasis seit dem letzten Commit geändert hat, warnt das System den Entwickler: „Graph veraltet. Bitte Commit durchführen oder manuell aktualisieren.“

Diese Architektur stellt sicher, dass die KI immer mit dem aktuellen Stand der Codebasis arbeitet – ohne manuelle Eingriffe oder zweite Wahrheiten.

Ausblick: Strukturierte KI-Entwicklung als Standard

Die unsichtbaren Schulden, die durch KI in der Softwareentwicklung entstehen, sind ein wachsendes Problem. Doch sie sind lösbar – nicht durch größere Kontextfenster oder bessere Prompts, sondern durch strukturelle Änderungen an der Codebasis selbst.

Tools wie aming-claw zeigen einen Weg auf, wie KI und Architektur harmonieren können. Der Schlüssel liegt in der Integration von maschinell lesbaren Projektionen der Codebasis in den Entwicklungsprozess.

In Zukunft werden solche Ansätze vermutlich Standard werden. Denn eines ist klar: KI wird die Softwareentwicklung revolutionieren – aber nur, wenn wir die richtigen strukturellen Rahmenbedingungen schaffen.