Skip to main content
Zurück zum Blog
Allgemein
16. März 2026

Shadow Tech Debt — die unsichtbare Schuld der KI-Agenten

Johannes Schneider

Ein Name für das, was wir schon länger ahnen

JetBrains hat im März 2026 endlich einen Namen für ein Problem gefunden, das uns seit Monaten beschäftigt: Shadow Tech Debt. Nik Tkachev, Head of Product bei JetBrains, meint damit Code, den KI-Agenten generieren — der für sich genommen funktioniert, aber die Architektur des Gesamtprojekts schleichend zerlegt.

Wir mussten beim Lesen ein bisschen nicken. Wir setzen KI-Agenten seit neun Monaten produktiv ein, in einem Kotlin/TypeScript-Monorepo mit über 600 Modulen. Das Problem kennen wir. Sehr gut sogar.

Was ist Shadow Tech Debt eigentlich?

Normale technische Schulden kennt jeder: Man nimmt eine Abkürzung, weil der Termin drückt. Schiebt ein Refactoring auf. Weiß, dass da was im Argen liegt — hat es ja selbst verbockt. Immerhin kann man es priorisieren und irgendwann(tm) aufräumen.

Shadow Tech Debt ist dagegen fieser. Denn sie ist unsichtbar. Der Code kompiliert, die Tests sind grün, das Review geht durch. Alles sieht gut aus. Aber drei Monate später merkst du, dass die Codebase sich anders anfühlt. Irgendwie inkonsistent. Und dann schaust du genauer hin:

  • Die Architektur trennt sauber zwischen Query, Transformation und Command — Daten laden, transformieren, Ergebnis persistieren. Keine Seiteneffekte in der Transformation, gut testbar, leicht nachvollziehbar. Der Agent hat das nicht verstanden und Seiteneffekte quer durch die Berechnung gestreut. Funktioniert, aber die Testbarkeit ist im Eimer.
  • Das Projekt arbeitet konsequent mit immutablen Datenstrukturen. Neue Version? Neues Objekt. Der Agent hat stattdessen mutable State eingeführt — var statt val, Listen die in-place modifiziert werden. Funktioniert auch. Bis zum ersten Concurrency-Bug.
  • Typsichere IDs via Value Classes sind Standard im Projekt. Der Agent hat String genommen. Kompiliert, Tests grün — aber jetzt kann man versehentlich eine Kunden-ID in ein Projekt-Feld stecken, und der Compiler sagt keinen Ton.
  • Die Business-Logik gehört in *Support-Klassen, HTTP-Routing in *Routing-Klassen. Der Agent hat die Geschäftslogik direkt in die Route geschrieben. Geht, klar. Aber jetzt ist die Logik nicht mehr unabhängig testbar.

Jedes einzelne Puzzleteil passt. Aber das Gesamtbild? Wird langsam matschig.

Warum entsteht Shadow Tech Debt?

Der Agent hat keine Ahnung von eurem Projekt

Ein KI-Agent sieht Dateien, Imports, Funktionssignaturen. Was er nicht sieht: Warum eine bestimmte Struktur gewählt wurde. Weshalb Klassen bei uns bestimmte Suffixe tragen (*Support für Business-Logik, *Access für Datenzugriff, *Routing für HTTP). Aus welchem Grund IDs als Value Classes modelliert sind und nicht als Strings. Oder warum wir not() statt ! schreiben.

All diese Sachen stehen halt nirgends in einer README. Stattdessen leben sie in den Köpfen des Teams — als Tribal Knowledge, in alten Code-Review-Kommentaren, in Gesprächen am Whiteboard. Der Agent hat das alles nicht. Also schreibt er Code, der technisch korrekt, aber irgendwie fremd ist. Wie ein Gastmusiker, der die Noten trifft, aber den Sound der Band nicht kapiert.

Jede Session startet bei null

Jede Interaktion mit dem Agenten beginnt ohne Kontext. Kein Gedächtnis, keine Projektgeschichte, keine Vorstellung davon, wo die Codebase hin soll. Er optimiert für jetzt — nicht für die Codebase in sechs Monaten.

Das skaliert nicht

Bei einem einzelnen Script — geschenkt. Sobald Agenten jedoch ganze Features bauen, Pull Requests erstellen und in CI/CD-Pipelines direkt committen? Dann multipliziert sich das Problem. Tkachev sagt es ziemlich direkt: „Let’s be honest: Complex codebases aren’t yet ready for pure agentic coding.“

Ja. Das trifft es.

Shadow Tech Debt in Zahlen

Die METR-Studie von 2025 hat eine Zahl produziert, die erstmal wehtut: Erfahrene Entwickler waren auf ihren eigenen, komplexen Codebases 19% langsamer mit KI-Tools. Und — das ist der gute Teil — sie glaubten trotzdem, schneller zu sein.

Das passt perfekt zum Shadow-Tech-Debt-Bild. Denn gefühlt geht’s schneller. Der Code ist ja da. Aber dann muss man ihn korrigieren, anpassen, in die bestehende Architektur einpassen. Oder — und das ist der gefährliche Fall — man macht’s einfach nicht, und die Inkonsistenzen stapeln sich leise auf.

Shadow Tech Debt bekämpfen: Was wir gelernt haben (auf die harte Tour)

Wir nutzen Claude Code als KI-Agent in der täglichen Entwicklung. Dabei ist die zentrale Erkenntnis nach neun Monaten: Der Agent ist genau so gut wie die Leitplanken, die man ihm gibt. Ohne Leitplanken produziert er genau das, was Tkachev beschreibt. Mit Leitplanken wird’s brauchbar.

Blueprints: Das Projekt komplett beschreiben — bevor eine Zeile Code entsteht

Die CLAUDE.md im Repo erklärt dem Agenten die Basics: Konventionen, Naming-Regeln, Sprachkonstrukte. Allerdings ist das nur die unterste Ebene. Für neue Projekte gehen wir deutlich weiter.

Wir arbeiten mit einem Blueprint-Konzept — einer mehrstufigen Projektspezifikation, die komplett in Markdown-Dateien lebt und dem Agenten als vollständiger Kontext dient:

  1. Use Cases — Was soll das System können? Konkrete Nutzerszenarien, keine abstrakten Requirements.
  2. Domain Model — Welche Entitäten gibt es? Wie hängen sie zusammen? Welche Zustände durchlaufen sie?
  3. Specs — Technische Spezifikationen für jede Systemkomponente, abgeleitet aus den Use Cases.
  4. UX — Wie sieht die Oberfläche aus? Welche Interaktionen gibt es?
  5. Plan — Modulstruktur, Pattern-Zuordnung, Architekturentscheidungen.
  6. Tasks — Einzelne Implementierungsschritte, geordnet nach Abhängigkeiten.

Jede Stufe baut auf der vorherigen auf. Der Agent leitet die Specs aus den Use Cases ab, den Plan aus den Specs, die Tasks aus dem Plan. Das ganze Projekt wird durchdacht, bevor die erste Zeile Code geschrieben wird.

Der Unterschied zu „schreib mir mal ein Feature“: Der Agent kennt nicht nur die aktuelle Aufgabe, sondern das gesamte Zielbild. So weiß er, wie die Presence-Komponente mit dem Meeting-System zusammenspielen soll. Gleichzeitig kennt er die Value Classes, die projektübergreifend verwendet werden. Kurz: Er hat den Systemkontext, nicht nur den Dateikontext.

Ohne Blueprint: Spring-Boot-artige Controller statt Ktor-Routing, falsche Patterns, inkonsistente Struktur. Mit Blueprint: Der Agent folgt unseren Konventionen, weil er sie kennt.

Patterns zum Abgucken

Ergänzend zum Blueprint gibt es eine Pattern-Bibliothek mit 15 dokumentierten Mustern: MongoDB-Entities, Draft/Confirmed-Zustandsmanagement, REST-Responses mit Sealed Interfaces, typsichere Filterung. Jedes Pattern hat lebenden Code als Referenz — keine abstrakten Beschreibungen, sondern „so sieht das bei uns aus“.

Der Agent kopiert dann nicht irgendein Pattern aus seinem Trainingskorpus — sondern unser Pattern.

Workflows statt „mach mal“

Wir prompten nicht frei. Wir haben 18 definierte Skills — quasi automatisierte Workflows mit klaren Ein- und Ausgaben:

  • /plan — Technische Planung mit Architektur-Analyse
  • /work — Implementierung mit Quality Gates (Build, Tests, Code-Style)
  • /review — Strukturiertes Code Review mit Checklisten
  • /polish — Stil- und Qualitätsprüfung vor dem Merge

Jeder Skill erzwingt Qualitäts-Gates. Der Agent kann nichts in den Main-Branch bringen, ohne dass Detekt, ESLint und Prettier drübergelaufen sind. Kein Shortcut möglich.

Geht trotzdem schief. Manchmal.

Ehrlich gesagt: Auch mit allen Leitplanken passieren Fehler. Beispielsweise greift der Agent mal zu einem deprecated Pattern. Oder er dupliziert Logik, die schon in einer Utility-Klasse steckt. Benennt Dinge anders als der Rest der Codebase.

Der Punkt ist: Mit den richtigen Prozessen findet man das vor dem Merge. Ohne Prozesse findet man’s drei Monate später. Oder nie.

Was wirklich gegen Shadow Tech Debt hilft

Shadow Tech Debt ist kein Tool-Problem. Bessere Modelle allein lösen das nämlich nicht. Vielmehr ist es ein Prozess-Problem:

  1. Architektur-Kontext raus aus den Köpfen, rein in Dateien. Was das Team weiß, muss der Agent auch wissen. Aufschreiben.
  2. Patterns dokumentieren — mit lebendem Code. Keine abstrakten Beschreibungen, sondern „so sieht das bei uns aus, mach’s genauso“.
  3. Automatisierte Quality Gates. Linter, Static Analysis, Style Checks. Alles, was Konventionen maschinell prüft, fängt Shadow Tech Debt ab.
  4. Definierte Workflows statt freie Prompts. Ein Agent mit Struktur produziert konsistentere Ergebnisse als einer, den man einfach drauflos schreiben lässt.
  5. Review bleibt Pflicht. KI-Code braucht die gleiche Review-Sorgfalt wie menschlicher Code. Eher mehr, weil die subtilen Inkonsistenzen schwerer zu erkennen sind.

Fazit: Shadow Tech Debt ist vermeidbar

KI-Agenten sind großartige Werkzeuge. Ernsthaft. Sie beschleunigen repetitive Aufgaben, reduzieren Boilerplate und automatisieren Workflows, die vorher nervig und fehleranfällig waren. Aber ohne Leitplanken produzieren sie technische Schulden, die man nicht sieht, die sich aufstapeln und die am Ende teurer werden als die eingesparte Zeit.

Shadow Tech Debt ist real. Die Frage ist nicht ob man KI-Agenten einsetzt — sondern ob man es mit oder ohne Leitplanken tut. Wie wir das bei Neckar IT konkret angehen, beschreiben wir in unserer AI-Strategie. Und ehrlich gesagt: Ohne Leitplanken kann man es auch gleich lassen.

Quellen: