KI-Systeme dokumentieren: Dokumentation als laufende Praxis statt Pflichtübung

Wenn bei klassischer Software der entscheidende Entwickler geht, bleibt immerhin der Code. Er ist nicht immer schön, aber er ist vollständig: Was das System tut, steht darin. Bei KI-Systemen gilt das nicht mehr. Der Code ist oft erstaunlich schlank, ein paar Aufrufe, etwas Datenaufbereitung, ein Stück Auswertung. Das eigentliche Verhalten steckt woanders: im Prompt, in der Modellwahl, in Schwellenwerten, in der Auswahl der Kontextquellen und im Wissen darüber, welche Fälle das System zuverlässig beherrscht und welche nicht.

Genau dieses Wissen ist selten aufgeschrieben. Es lebt im Kopf der Person, die das System eingestellt hat, und in verstreuten Chat-Verläufen. Solange diese Person erreichbar ist, fällt das nicht auf. Kritisch wird es beim Personalwechsel, beim Dienstleisterwechsel oder schlicht sechs Monate später, wenn niemand mehr weiß, warum der Prompt eine merkwürdig spezifische Anweisung enthält und ob man sie entfernen darf.

KI-Systeme dokumentieren heißt deshalb etwas anderes als Code kommentieren. Es heißt, das Verhalten und seine Begründung festzuhalten, und zwar laufend im Arbeitsfluss, nicht als Pflichtübung am Projektende.

Was bei KI-Systemen dokumentiert gehört

Vier Bereiche tragen den Großteil des Wissens, das im Ernstfall gebraucht wird:

• Prompt-Stände mit Begründung: nicht nur der aktuelle Prompt, sondern seine Geschichte. Welche Formulierung wurde wann geändert, welches Problem sollte die Änderung lösen, und hat sie es gelöst. Ohne diese Begründungen wird jeder Prompt zur heiligen Kuh: Niemand traut sich, eine Zeile zu löschen, weil niemand weiß, welchen Fehler sie einmal verhindert hat.
• Bekannte Schwächen und Grenzfälle: die Fälle, in denen das System danebenliegt, zögert oder Auskünfte verweigert, obwohl es antworten sollte. Diese Liste ist wertvoller als jede Architekturskizze, denn sie beantwortet die Frage, die im Betrieb tatsächlich gestellt wird: Ist das ein bekanntes Verhalten oder ein neues Problem.
• Entscheidungslog: die großen Weichenstellungen des Projekts. Warum dieses Modell, warum diese Datenquelle, warum diese Schwelle. Drei Sätze pro Entscheidung genügen: Ausgangslage, betrachtete Optionen, Wahl mit Grund.
• Betriebshandgriffe: die Handvoll Abläufe, die im Störfall zählen. Wie startet man das System neu, wie prüft man, ob die Wissensquelle aktuell ist, wie schaltet man das Feature notfalls ab, wo laufen Kosten und Nutzung auf.

Auffällig ist, was in dieser Liste fehlt: seitenlange Architekturbeschreibungen und generierte API-Referenzen. Beides ist bei Bedarf schnell rekonstruierbar. Die vier genannten Bereiche sind es nicht, denn sie dokumentieren Entscheidungen und Erfahrungen, keine Strukturen.

Dokumentation in den Arbeitsfluss integrieren

Der übliche Weg, Dokumentation am Projektende nachzuziehen, scheitert bei KI-Systemen doppelt. Erstens ist das Begründungswissen dann längst verblasst: Warum eine Prompt-Zeile vor vier Monaten eingefügt wurde, weiß auch der Autor nicht mehr genau. Zweitens ist ein KI-System nie fertig; Prompts und Quellen ändern sich im Betrieb weiter, und eine nachgezogene Doku beginnt sofort wieder zu veralten.

Tragfähig wird Dokumentation erst, wenn sie an die Tätigkeiten gekoppelt ist, bei denen das Wissen entsteht:

• Prompt-Änderungen werden wie Code-Änderungen behandelt: versioniert, mit einer Zeile Begründung pro Änderung. Wer Prompts in der Versionsverwaltung führt, bekommt die Historie geschenkt und muss nur noch das Warum ergänzen.
• Grenzfälle werden dort notiert, wo sie auffallen. Ein einziges, leicht erreichbares Sammelbecken genügt, etwa eine Seite im Team-Wiki oder eine Liste im Projektordner. Entscheidend ist, dass der Eintrag weniger als eine Minute kostet, sonst unterbleibt er.
• Das Entscheidungslog wird an bestehende Termine gekoppelt: Fällt in einer Abstimmung eine Weichenstellung, wandern die drei Sätze dazu noch im Termin in das Log, nicht danach.

Die beste Regel für all das ist eine Aufwandsobergrenze: Wenn das Festhalten einer Änderung mehr als fünf Minuten kostet, ist nicht das Team zu faul, sondern der Prozess falsch aufgesetzt.

Woran man erkennt, dass eine Doku trägt

Ob eine Dokumentation trägt, zeigt sich nicht beim Schreiben, sondern beim Lesen unter Druck. Dafür gibt es einen einfachen Test: Eine Person, die das System nicht gebaut hat, bekommt eine typische Störung geschildert und nur die Doku als Hilfsmittel. Drei Fragen entscheiden über das Ergebnis:

• Findet sie in wenigen Minuten heraus, ob das gemeldete Verhalten bekannt ist oder neu.
• Kann sie das System gefahrlos neu starten oder abschalten, ohne jemanden anzurufen.
• Versteht sie, warum der Prompt so aussieht, wie er aussieht, bevor sie ihn ändert.

Wer diesen Test halbjährlich durchführt, etwa mit einem neuen Teammitglied, bekommt eine ehrliche Rückmeldung über den Zustand der Dokumentation. Lücken, die dabei auffallen, sind präziser als jede allgemeine Doku-Richtlinie: Sie zeigen genau, welches Wissen noch in Köpfen steckt statt auf Papier.

Fazit

Bei KI-Systemen liegt das entscheidende Wissen nicht im Code, sondern in Prompts, Konfigurationen, bekannten Grenzfällen und den Gründen hinter Entscheidungen. Wer dieses Wissen sichern will, braucht keine dicke Systemdokumentation, sondern vier gepflegte Bestände: Prompt-Historie mit Begründung, Grenzfallliste, Entscheidungslog und Betriebshandgriffe. Getragen wird das Ganze nicht von Disziplin, sondern von Integration: Dokumentiert wird im Moment der Änderung, mit minimalem Aufwand, an einem bekannten Ort. Und geprüft wird nicht die Vollständigkeit, sondern die einzige Eigenschaft, die zählt: ob eine unbeteiligte Person mit der Doku allein im Ernstfall handlungsfähig ist.