Technische Dokumentation in einem SaaS-Unternehmen veraltet schneller als der Code. Ein bei der Einführung von v2 geschriebenes Runbook beschreibt Prozeduren, die bei v4 bereits anders sind. Das Onboarding-Wiki vom Mai erwähnt Endpunkte, deren Parameter sich im Juli geändert haben. Neue Ingenieure verbringen ihre ersten Tage damit, zu prüfen, ob das Gelesene noch der Wahrheit entspricht.
Wir bei Cashcrown untersuchen, wie ein auf RAG basierender Assistent die Lücke zwischen Code und Dokumentation verkleinern kann, ohne die Rolle des Menschen als letzte Instanz der Überprüfung zu eliminieren. Dieser Artikel beschreibt das Muster des Entwurfs aus Code, das Problem des Dokumentationsdrifts und die Grenze, die kein Automat überschreiten sollte.
Entwurf aus Code: RAG über Quellen, nicht aus dem Modellgedächtnis
#Der klassische Ansatz zur automatischen Generierung von Dokumentation basiert darauf, das Sprachmodell mit Anweisungen wie „beschreibe diesen Endpunkt“ zu instruieren. Das Modell antwortet auf Basis des allgemeinen Wissens, das in seinen Gewichten kodiert ist. Das Ergebnis ist grammatikalisch korrekt, aber faktisch völlig unsicher, da das Modell eure API möglicherweise nie gesehen hat.
Das Muster, das wir untersuchen, ist umgekehrt: Der Assistent erhält eine Frage oder eine Entwurfsaufgabe, der Retrieval extrahiert relevante Fragmente aus indexiertem Code und bestehender Dokumentation, und der LLM formuliert den Dokumentenentwurf ausschließlich auf deren Basis. Jeder Satz ist mit einem konkreten Quellfragment verknüpft.
Praktische Implikationen für die Indexierung:
| Quelltyp | Was wir indexieren | Pflichtmetadaten |
|---|---|---|
| Quellcode (TS, Python, Go) | Funktionen, Klassen, Methoden (AST-Chunking) | file_path, symbol_name, start_line, last_commit_sha |
| OpenAPI / Swagger-Spezifikation | Ein Endpunkt pro Chunk | method, path, version, operationId |
| Bestehende Runbooks / Wiki | Abschnitte nach H2/H3-Überschriften | page_url, section_title, last_modified |
| Changelog | Einträge pro Version | version, date, author |
Ein Guardrail in der Generierungsschicht blockiert eines: Wenn der Retrieval kein Fragment mit einer Ähnlichkeit über dem Schwellenwert (orientierend 0,65 für semantische Suche) zurückgibt, entwirft der Assistent nichts. Stattdessen antwortet er direkt: „Keine Abdeckung in der indexierten Quellversion gefunden“. Die Beschreibung eines Parameters, der nicht in der OpenAPI vorhanden ist, landet nicht im Entwurf.
Mehr zu Indexierungsstrategien für Code beschreibt der Artikel über RAG für Code und technische Dokumentation.
Dokumentationsdrift: Warum Synchronisation ein größeres Problem ist als das Entwerfen
#Die Erstellung der ersten Version der Dokumentation ist ein lösbares Problem. Ihre Aktualität nach sechs Monaten intensiver Entwicklung zu erhalten, ist ein Problem, das die meisten Teams durch... Nicht-Aktualisieren der Dokumente „lösen“.
Drift hat einen konkreten Mechanismus: Ein Endpunkt ändert einen Parameter im Code Review, niemand aktualisiert das Wiki. Einen Monat später verliert ein neuer Programmierer zwei Stunden mit dem Debuggen eines Fehlers, der in der aktuellen Dokumentation wie eine Konfiguration ausgesehen hätte. Das Ausmaß des Drifts wächst linear mit der Anzahl der Microservices und umgekehrt proportional zur Disziplin der Aktualisierung.
Drei Schichten, die wir in unserem Ansatz zu diesem Problem anwenden:
Inkrementelle Reindexierung nach Commit. Ein Webhook aus GitLab oder GitHub (Hook post-receive) löst die Reindexierung geänderter Dateien aus. git diff --name-only HEAD~1 HEAD liefert die Liste. Der Assistent weiß, dass diese Datei nach dem letzten Entwurf geändert wurde und kann den zugehörigen Dokumentationsabschnitt als überprüfungsbedürftig markieren.
Frische-Metadaten in jeder Antwort. Jeder Chunk im Index speichert last_commit_sha und das Indexierungsdatum. Der Assistent gibt sie im Zitat an: „Quelle: src/payments/refund.py, Zeile 43, Commit b2f1a09, indexiert vor 3 Stunden“. Der Programmierer sieht, ob er der Antwort vertrauen kann, bevor er sie anwendet.
TTL für Dokumente ohne Webhook. Runbooks in Confluence oder Notion senden keine Ereignisse nach der Bearbeitung. Wir setzen eine TTL für die Reindexierung: 24 Stunden für sich aktiv ändernde Dokumentation, 7-14 Tage für stabile Architekturspezifikationen. Nach Ablauf der TTL fügt der Assistent eine Warnung vor möglicher Veraltung hinzu.
Der Mensch entscheidet über den TTL-Schwellenwert für jede Dokumentationskategorie. Das ist keine technische Konfiguration; es ist eine Risikoentscheidung, die der Ingenieur oder Tech Lead trifft, der für den jeweiligen Bereich verantwortlich ist.
Erkennung veralteter Abschnitte: Guardrails als Signal, nicht als Urteil
#Der Assistent entscheidet nicht eigenständig, dass ein Dokumentationsabschnitt veraltet ist und überschreibt ihn. Das wäre mit dem Prinzip human-oversight unvereinbar. Die Erkennung von Drift funktioniert anders: Der Assistent markiert, der Mensch bewertet.
Konkretes Muster zur Drifterkennung:
Bei jeder Anfrage zu einem Dokumentationsabschnitt vergleicht der Assistent das Datum der letzten Änderung der Wiki-Seite mit dem Datum des letzten Commits in der zugehörigen Codedatei. Wenn der Commit um mehr als einen definierten Schwellenwert (z. B. 48 Stunden) neuer ist, fügt der Assistent der Antwort eine Anmerkung hinzu: „Quellcode geändert 3 Tage nach der letzten Aktualisierung dieses Dokumentationsabschnitts. Empfehle Überprüfung vor Anwendung.“
Für einen fortgeschritteneren Ansatz kann ein Agent einen zyklischen Bericht generieren: eine Liste von Dokumentationsabschnitten, deren zugehörige Codedateien sich seit der letzten Überprüfung geändert haben, sortiert nach Anzahl der Änderungen. Der Tech Lead prüft die Liste jeden Sprint und delegiert Aktualisierungen an konkrete Personen.
Was die harte Grenze ist: Der Assistent veröffentlicht niemals eine Änderung in der Dokumentation ohne Freigabe durch einen Menschen. Er schlägt Bearbeitungen vor, entwirft Änderungen zur Überprüfung und zeigt den Diff zwischen dem, was im Wiki steht, und dem, was sich aus dem aktuellen Code ergibt. Die Entscheidung über die Annahme des Entwurfs liegt beim Verantwortlichen für die Dokumentation.
Eine detaillierte Erläuterung des Arbeitsmusters des Assistenten bei langen Dokumenten beschreibt der Artikel über Zusammenfassen langer Dokumente.
Quellenangabe: Operative Anforderung, keine Option
#Halluzination in technischer Dokumentation hat höhere Kosten als in den meisten anderen Anwendungen. Die Beschreibung eines Parameters, der nicht in der API existiert, führt den Programmierer zu einem Integrationsfehler. Ein Runbook mit einer fiktiven Anweisung sorgt dafür, dass eine Operation mitten in der Nacht in einem Incident endet.
Daher muss jeder von einem Assistenten generierte Dokumentationsabschnitt eine Zitatspur haben: Woher stammt er, welcher Commit, wann wurde er indexiert. Das interne Format, das wir verwenden:
[Entwurf aus Quelle: src/payments/refund.ts, Zeile 67-89, Commit a3f9c12, indexiert 2026-06-18 08:41]
Diese Spur erscheint im Dokumentationsprüfungstool, nicht im veröffentlichten Artikel. Der Reviewer sieht, woher jeder Satz stammt, und kann mit einem Klick zur Quelldatei im Repository wechseln. Falls sich der Code seitdem geändert hat, sieht er das vor der Freigabe.
Guardrails, die structured output blockieren, sollten die Anwesenheit von Zitaten in jedem Entwurf erzwingen. Wenn das Modell versucht, eine Parameterbeschreibung ohne zugehöriges Fragment aus dem Retrieval zu generieren, wird die Generierung abgelehnt. Ein leerer Entwurf ist besser als ein Entwurf mit einem erfundenen Parameter.
Das Muster eines unternehmensinternen, auf RAG basierenden Assistenten beschreibt der Artikel Unternehmens-GPT auf Wissensbasis.
Die Rolle des Menschen: Wo die Grenze hart ist
#Bei jeder Einführung eines Assistenten zur Erstellung von Dokumentation wiederholen wir dasselbe Gespräch mit dem Team: Was der Assistent tut und was dem Ingenieur obliegt.
Der Assistent entwirft auf Basis des Codes. Der Ingenieur bewertet, ob der Entwurf die architektonische Intention wiedergibt und nicht nur die Mechanik des Codes. Diese beiden Dinge sind unterschiedlich.
Der Assistent markiert Abschnitte, deren zugehöriger Code sich geändert hat. Der Ingenieur bewertet, ob die Codeänderung tatsächlich die Semantik des dokumentierten Verhaltens beeinflusst. Oft tut sie das nicht; das Refactoring eines Variablennamens ändert nicht die API.
Der Assistent generiert das Grundgerüst eines Runbooks aus den Prozeduren im Code. Der Ingenieur ergänzt es um operatives Wissen, das nicht im Code steht: Was als Erstes um 3 Uhr nachts zu prüfen ist, wann der DBA zu rufen ist, welche Fehler NICHT ohne Rücksprache behoben werden dürfen. Dieses Wissen lebt in den Köpfen der Menschen, nicht in den Quelldateien.
Die Grenze, die kein Automat überschreitet: Die Entscheidung über die Veröffentlichung. Kein Entwurf gelangt ohne Freigabe durch die für den jeweiligen Bereich verantwortliche Person in die offizielle Dokumentation. Das ist eine operative Anforderung, nicht nur eine ethische. Gute Praxis zur Vorbereitung von Daten für KI beschreibt der Artikel Wie man Unternehmensdaten für AI vorbereitet.
FAQ
#Kann der Assistent das Wiki nach jedem Commit eigenständig aktualisieren?
#Er sollte es nicht, zumindest nicht ohne Review-Phase. Der Assistent kann automatisch einen Entwurf der Änderung generieren und einen Pull Request für die Dokumentation mit dem zugehörigen Code-Commit erstellen. Die Annahme dieses Entwurfs erfordert jedoch die Freigabe durch den für den jeweiligen Bereich verantwortlichen Ingenieur. Das automatische Überschreiben des Wikis ohne Review birgt ein reales Risiko: Ein internes Refactoring, das das öffentliche Verhalten nicht ändert, kann irreführende Dokumentationsänderungen erzeugen.
Wie geht man mit Dokumentation um, wenn derselbe Endpunkt an mehreren Stellen beschrieben ist?
#Das ist eines der häufigsten Probleme bei RAG über technische Dokumentation. Der Retrieval gibt mehrere Fragmente zurück, und das Modell könnte versuchen, sie zu kombinieren, was zu widersprüchlichen Beschreibungen führen kann. Das Muster, das wir empfehlen: Führe vor der Einführung des Assistenten ein Audit der Wissensbasis durch und markiere eine einzige Quelle der Wahrheit für jeden Endpunkt. Duplikate werden als veraltet markiert und verweisen auf die kanonische Quelle. Der Assistent indexiert nur die kanonische Quelle.
Wie misst man die Qualität der generierten Dokumentation?
#Zwei Kennzahlen, die operativ sinnvoll sind: Der Anteil der Entwürfe, die ohne Änderungen vom Reviewer akzeptiert werden (Ziel: über 50 Prozent nach dem ersten Kalibrierungsmonat) und die Zeit, die ein Ingenieur für die Prüfung eines Entwurfs benötigt (Ziel: unter 15 Minuten für einen typischen Abschnitt). Eine niedrige Akzeptanzrate signalisiert ein Problem mit der Qualität des Index oder des System-Prompts. Eine lange Prüfzeit signalisiert zu große Entwürfe oder zu wenig konkrete Quellenangaben.
Was tun, wenn der Assistent die Beschreibung eines Parameters generiert, der nicht in der OpenAPI vorhanden ist?
#Das ist ein Signal, dass der Zitier-Guardrail nicht korrekt funktioniert. Ein richtig konfigurierter Assistent sollte keine Beschreibung ohne Abdeckung im Index generieren. Falls das passiert, prüfe zwei Stellen: Ob der Guardrail die Anwesenheit eines Zitats in jedem Entwurf prüft und ob der Ähnlichkeitsschwellenwert des Retrievals nicht zu niedrig ist (zu schwache Übereinstimmungen werden zugelassen). Die Beschreibung eines Parameters, der nicht in der Quelle existiert, ist ein Symptom für fehlende Guardrails, nicht für Schwächen des Modells.
Kann KI die Onboarding-Dokumentation für neue Programmierer automatisieren?
#Sie kann Grundgerüste für Onboarding-Dokumente aus Code und bestehenden Prozeduren entwerfen. In der Praxis erfordert Onboarding Wissen, das in keiner Datei steht: ungeschriebene Teamkonventionen, historische Architekturentscheidungen, Stellen, die fragil sind und nur „alten“ Teammitgliedern bekannt sind. Der Assistent verkürzt die Zeit für die Erstellung des Dokuments um einige Dutzend Prozent, aber die endgültige Version erfordert immer den Beitrag eines Ingenieurs mit Erfahrung im jeweiligen Bereich.