Euer KI-Problem ist ein Dokumentationsproblem

Euer Entwicklungsteam arbeitet mit KI-Agenten. Die Subscriptions werden bezahlt, einige Devs nutzen sie aktiv, andere stecken noch bei Chat-Completion fest. Und trotzdem bleibt der Produktivitätsgewinn aus, den die Tool-Hersteller versprechen.

Es liegt nicht am Modell. Es liegt nicht am Tool: Der fehlende Hebel ist der Kontext, und den liefern die wenigsten Teams systematisch.

Der fehlende Kontext ist kein neues Problem. Er wird mit KI-Agenten nur sichtbarer. Was Agents heute schon leisten können — und wo die Grenzen liegen — habe ich in KI in der Softwareentwicklung beschrieben.

Was das eigentlich kostet

Wenn ein Agent ohne strukturierten Kontext einfach loslegt, erkundet er das Repository: Build-Skripte, Konventionen, Architekturentscheidungen. Er rät. Er halluziniert. Und wenn sein Output nicht passt, wird er korrigiert — und fängt wieder von vorne an.

Das ist keine Einmaligkeit. Jeder Task beginnt mit dieser Entdeckungsphase, und jede Iteration kostet Tokens, Zeit und Frust. Ein Team, das KI-Agenten nutzt ohne dokumentierten Kontext, zahlt diesen Preis bei jeder einzelnen Aufgabe.

Im betriebswirtschaftlichen Sinne bedeutet das: Ihr bezahlt Tool-Subscriptions, die keine Produktivität liefern. Die Kosten für Agenten-Lizenzen summieren sich — und wenn jeder Task mit Raten, Korrekturen und Neustarts beginnt, statt produktiv zu sein, verbrennt ihr Geld für etwas, das eigentlich helfen sollte.

Ich habe das Muster in 5 Anzeichen, dass euer Team KI-Tools falsch einsetzt beschrieben. Was dort als Verhaltensmuster der Entwickler auftaucht, hat oft genau diese eine Ursache: fehlender Kontext.

Quelle: Lulla et al., “On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents”, arXiv:2601.20404 (Januar 2026)

Vier Probleme, die Teams bei ihrer Dokumentation haben

In der Praxis scheitert guter KI-Kontext selten an einem einzelnen Problem. Üblich sind mehrere Schichten, die zusammenwirken.

1. Doku existiert nicht oder auf dem falschen Abstraktionslevel

Das häufigste Problem ist banal: Es gibt keine systematische Dokumentation. Oder sie existiert, aber auf einem Abstraktionslevel, das für KI-Agenten keine Relevanz hat.

Eine detaillierte Beschreibung, wie ein bestimmter Algorithmus in Kotlin implementiert ist, hilft einem Agenten nicht weiter. Der Agent kann den Code selbst lesen. Was ihm fehlt, ist das „Warum": Warum wurde dieser Ansatz gewählt? Welche Alternativen wurden verworfen? Welche Constraints gelten?

2. Doku liegt an einem Ort, den der Agent nicht erreichen kann

Word-Dateien auf einer Freigabe, Confluence-Seiten hinter Login, Visio-Diagramme auf dem lokalen Bildschirm. Das ist alles unsichtbar für KI-Agenten. Sie können weder Word-Metadaten parsen noch durch einen Browser navigieren.

Die einfachste Lösung: Dokumentation ins Repository. Direkt neben dem Code. In einem textbasierten Format, das ein Agent lesen kann. Markdown oder AsciiDoc. Wenn bestehende Formate wie Word unersetzlich sind, kann ein MCP-Server als Zwischenlayer die Inhalte extrahieren. Das ist jedoch ein Mehraufwand, der entsteht, wenn ihr die Dokumentation nicht vom Tool her, sondern von den Grundformen her denkt.

3. Alles rein → Kontext wird unbrauchbar

„Ich packe einfach alles in die AGENTS.md!" – das war auch mein erster Instinkt, als ich verstanden habe, wie wichtig Kontext ist. Jede Architekturentscheidung, jedes Diagramm, jede Regel aus dem arc42-Kapitel. Rein damit.

Anthropic warnt davor klar: „Bloated CLAUDE.md files cause Claude to ignore your actual instructions." Die Logik dahinter ist simpel: Je mehr Information ein Modell verarbeiten muss, desto schwieriger wird es, die relevanten Anweisungen von den Ablenkungen zu unterscheiden. Die Chroma-Studie (2025)¹ hat das empirisch bestätigt. Sie hat 18 LLMs getestet und gezeigt, dass die Performance mit steigender Kontextlänge kontinuierlich sinkt — nicht sprunghaft, sondern schleichend. Je mehr Information im Kontext, desto unzuverlässiger wird die Recall-Performance. Distraktoren verstärken den Effekt.

Und es wird noch schlechter, wenn man den Kontext nicht kuratiert, sondern generiert. Eine ETH-Studie (Gloaguen et al., Februar 2026)² kam zu einem ernüchternden Ergebnis: LLM-generierte Context-Files verschlechtern die Performance um drei Prozentpunkte, und Context-Files erhöhen die Inferenz-Kosten um über 20 %, selbst wenn sie marginal helfen.

4. Doku und Code wandern auseinander

Wenn Architekturdiagramme in Visio liegen, ADRs im Kopf des Lead-Architekten und Build-Konventionen in einer Word-Datei, die niemand aktualisiert, dann divergieren Doku und Code sofort. Ein Agent, der die Doku liest, orientiert sich an einer veralteten Realität. Ein Mensch, der sie konsultiert, tut es ebensowenig.

Textbasierte Diagramme in PlantUML oder Mermaid lösen dieses Problem, weil sie direkt im Repository liegen, versioniert sind und sich durch einen Diff in Pull-Requests diskutieren lassen. Ein Agent kann sie lesen, und er kann sie aktualisieren. Visio-Dateien sind für ihn unsichtbar.

Wie Architekturdokumentation in der Praxis funktioniert — und warum sie oft genau an dieser Stelle scheitert — habe ich in Endlich eine gute Architekturdokumentation beschrieben.

Was produktiver KI-Kontext praktisch heißt

Wenn man die vier Fehler vermieden hat, stellt sich die Frage: Woran erkennt man, dass der KI-Kontext gut ist? Nicht an der Länge. Nicht an der Vollständigkeit. An drei Kriterien, die ihr morgen auf eure eigene Dokumentation anwenden könnt.

Entscheidbar ist der Kontext, wenn jeder Absatz eine Entscheidung oder Regel enthält, die ein Agent treffen kann. „Was" ist kein Kontext. „Wie" und „warum nicht" sind es. Ein Agent braucht keine Auflistung von API-Endpoints — er braucht die Regel, warum die API so designed wurde und wann man sie bricht. Ein Agent braucht keine Liste aller Konfigurationsparameter — er braucht die Entscheidung, warum der Standardwert in 95 % der Fälle reicht und wann ihr ihn überschreibt.

Beherrschbar ist der Kontext, wenn er in einem sinnvollen Context Window bleibt. Wenn ein Agent 40k Token fürs Onboarding braucht, bevor er die erste Aufgabe startet, ist das kein Feature — das ist Rechensteuer. Die drei Prozentpunkte Performance-Einbruch, die die ETH-Studie gemessen hat, sind nicht das einzige Argument. Das ökonomische ist gewichtiger: 40k zusätzliche Token pro Task sind 40k Token, die nicht für die eigentliche Aufgabe zur Verfügung stehen.

Entfernbar ist der Kontext, wenn ihr genau wisst, was nicht reingehört. Der beste KI-Kontext ist der, den man kürzen kann ohne dass etwas Wichtiges verloren geht. Wenn ihr das nicht beurteilen könnt, ist der Kontext zu unstrukturiert. Kuratieren statt kopieren — das ist die Haltung, die den Unterschied macht.

In einem früheren Essay Surprising Documentation habe ich darüber geschrieben, was Dokumentation wirklich braucht — und warum die meisten Teams am falschen Ende anfangen. Der Kern derselben Erkenntnis: Weniger ist mehr, wenn das Wenige das Richtige ist.

Ein Fall aus der Praxis

Bei meinem Projekt einfache-erechnung.de hatte ich das Problem, dass der Algorithmus zur Datenextraktion aus PDF-Rechnungen verbessert werden sollte. Die Aufgabe scheint technisch trivial, ist aber komplex: Rechnungen sehen nie gleich aus, Informationen sind unterschiedlich platziert, und das Regelwerk enthält Edge Cases.

Ich hatte einen ADR dazu geschrieben, der klarlegt, wie mit Diskrepanzen umzugehen ist: Wenn die Summe der Positionen (Line Items) nicht mit dem Gesamtbetrag auf der Rechnung übereinstimmt.

Ein Agent, der diesen ADR nicht gelesen hatte, hat einfach den Gesamtbetrag neu berechnet und dabei den originalen Betrag überschrieben. Das führt zu fehlerhaften XML-Dateien, weil der auf der Rechnung ausgewiesene Betrag rechtlich relevant ist.

Ein zweiter Agent, der den ADR gelesen hatte, erkannte das Problem sofort selbstständig und warf einen Fehler, statt eigenmächtig zu korrigieren. Kein menschliches Eingreifen nötig. Der Agent konnte die Entscheidung allein treffen. Der Kontext war da.

Eine AGENTS.md zu schreiben ist der einfache Teil. Den Kontext so zu kuratieren, dass er wirklich hilft — nicht zu viel, nicht zu wenig, immer aktuell und relevant für die Entscheidungen, die das Team treffen muss — das ist die eigentliche Herausforderung. Und genau da liegt der Punkt, an dem Erfahrung zählt: Wer Architekturdokumentation aus der Praxis kennt, erkennt sofort, was für den Agenten relevant ist und was nur Lärm im Kontext-Fenster erzeugt.

Wann das nicht passt

Gute Dokumentation ist kein Allheilmittel. Wenn eure Software konzeptionell falsch geschnitten ist, wenn die Domänenmodellierung nicht stimmt und die Service-Grenzen falsch gesetzt sind, hilft bessere Dokumentation einem KI-Agenten wenig. Ein Agent, der auf einem konzeptionell kaputten Fundament arbeitet, produziert nur schneller Unsinn an der falschen Stelle.

Auch wenn das Team grundlegende Entwicklungspraktiken nicht beherrscht — keine Tests, kein Review, keine saubere Versionskontrolle — ist KI nicht der richtige erste Schritt. Dann muss zuerst das Fundament stehen.

Was ihr morgen anfangen könnt

Ihr müsst nicht auf einmal eure gesamte Architekturdoku neu aufsetzen. Drei Schritte, die den größten Hebel haben:

1. Erstellt eine AGENTS.md im Repository-Root. Sie sollte keine bloße Liste von Regeln sein, sondern eine Übersicht über das Projekt und die Fachlichkeit. Und sie sollte Hinweise enthalten, wo welche Entscheidungen nachzulesen sind — und wann man sie zu Rate ziehen sollte. Ein Agent, der weiß, wo er die relevanten Informationen findet, ist einem besser als einer, der alles auf einer Seite vermutet.

2. Erstellt euer nächstes Architekturdiagramm in einem textbasierten Format. PlantUML oder Mermaid. Direkt im Repository. Nicht in Visio, nicht in Confluence. Der Agent kann es lesen, ihr könnt es in Pull-Requests diskutieren.

3. Schreibt den nächsten ADR. Nicht für die Aktenschränke. Für die nächsten vier Wochen, wenn euer Team und der nächste Agent Entscheidungen treffen müssen, die im bestehenden Kontext konsistent bleiben sollen. Ein ADR mit Status, Kontext, Entscheidung und Konsequenzen.

Der erste Schritt ist schnell erledigt. Der zweite und dritte nicht. Kontext kuratieren zu lernen — also zu erkennen, welche Architekturregeln für ein Team wirklich relevant sind und welche nur Rauschen im Kontext-Fenster erzeugen — das braucht Erfahrung. Und den Kontext aktuell zu halten, während das System wächst und sich verändert, ist eine organisatorische Aufgabe, keine technische. Das ist der Punkt, an dem viele Teams scheitern: nicht beim Schreiben, sondern beim Pflegen.

Wenn das Fundament steht, wird Dokumentation ein echter Hebel. Wie dieser Ansatz in einem echten Team wirkt, wenn die ersten Schritte gesetzt sind, beschreibe ich in Agentic Coding im Team .

Der Punkt, an dem KI wirklich produktiv wird

Auf der JavaLand habe ich bei meinem Vortrag „Kontext ist alles" im März 2026 rund 50 Entwickler gefragt, auf welcher Stufe der KI-Adoption sie sich befinden. Bei Stufe 1 gingen alle Hände hoch. Bei Stufe 3, also schon einem erkennbaren Einsatz über gelegentliche Chat-Completion hinaus, waren es nur noch vier oder fünf Hände.

Das ist kein Problem der Werkzeuge. Es ist ein Problem der Vorbereitung. Unternehmen, die ihren Entwicklern jetzt ermöglichen, KI-Agenten systematisch und mit gutem Kontext einzusetzen, werden in zwei Jahren schneller liefern. Nicht weil sie bessere Entwickler haben, sondern weil ihre vorhandenen Entwickler mit deutlich besseren Werkzeugen arbeiten.

Ihr braucht kein neues Tool. Ihr braucht ein neues Verständnis dafür, was eure Dokumentation heute schon leistet und was sie noch leisten kann.