Nach der KI-Codegenerierung: Warum Dokumentenreviews zur neuen Engstelle werden

Die Ära der KI-gestützten Softwareentwicklung hat einen überraschenden Engpass offenbart: Während Codegenerierung und -prüfung zunehmend automatisiert werden, verschiebt sich die größte Herausforderung auf die Bewertung der begleitenden Dokumentation.

Früher dauerte es Tage oder Wochen, bis ein Entwicklersteam die Anforderungen in einer Spezifikation festhielt, Feedback einarbeitete und schließlich den Code implementierte. Heute erstellen KI-Agenten in Sekunden Entwürfe für Design-Dokumente, API-Dokumentationen, Runbooks und README-Dateien. Doch was auf den ersten Blick wie eine enorme Effizienzsteigerung wirkt, entpuppt sich bei genauerer Betrachtung als neues Hindernis.

Vom Code zur Dokumentation: Wo die KI Grenzen zeigt

Vor einem Jahr war der typische Entwicklungsprozess klar strukturiert: Ein Entwickler verfasste eine Spezifikation, sammelte Feedback, überarbeitete den Entwurf und implementierte schließlich den Code – begleitet von Code-Reviews. Heute übernehmen KI-Agenten einen Großteil dieser Aufgaben. Doch während die Codegenerierung und -prüfung zunehmend automatisiert werden, bleibt die Überprüfung der automatisch erstellten Dokumente eine rein menschliche Aufgabe.

Die Ironie: Die Geschwindigkeit der Dokumentenerstellung hat sich dramatisch erhöht, während die Bewertung dieser Texte noch immer manuell erfolgt. Ein menschlicher Prüfer muss nun Tausende von Zeilen generierten Markdown-Contents durchgehen und entscheiden, was korrekturbedürftig ist. Zwar können LLMs bei der Dokumentenprüfung unterstützen, doch der menschliche Urteilsvermögen bleibt unverzichtbar – insbesondere bei komplexen technischen Inhalten.

Diese Asymmetrie führt zu einem neuen Engpass: Projekte, die mit KI-Agenten arbeiten, sammeln in gemeinsamen Ordnern eine wachsende Zahl von Dokumenten, die auf menschliche Prüfung warten. Wird parallel an mehreren KI-gesteuerten Workflows gearbeitet – etwa an einer Spezifikation, einem Implementierungsplan und einer Teststrategie –, wird die Dokumentenprüfung schnell zum Flaschenhals.

Warum natürliche Sprache als Feedback oft scheitert

Ein häufiger Lösungsansatz besteht darin, dem KI-Agenten das Feedback in natürlicher Sprache zu geben, etwa:

„Die Fehlerbehandlung in Abschnitt 3.2 ist zu vage – bitte konkretisieren, was bei einem Timeout passiert.“

Auf den ersten Blick erscheint dies sinnvoll: Der Agent liest die Rückmeldung, sucht nach relevanten Stellen und nimmt Änderungen vor. Doch diese Methode birgt mehrere Probleme:

• Unklarheit der Position: Abschnitt 3.2 könnte drei Absätze zur Fehlerbehandlung enthalten. Welcher Absatz gemeint ist, bleibt offen. Der Agent muss raten – und liegt nicht selten falsch.

• Verlust des Kontexts: Der Prüfer betrachtet das Dokument in seiner gerenderten Form – mit Diagrammen, Tabellen, Codeblöcken und Syntax-Highlighting. Diese visuelle Struktur geht verloren, sobald das Feedback in rein textlicher Form vorliegt.

• Vage Rückkopplungsschleifen: Der Agent wendet eine Änderung an, doch der Prüfer kann nicht sicher sein, ob die richtige Stelle korrigiert wurde. Ohne klare Verknüpfung zwischen Feedback und Änderung beginnt ein erneuter Zyklus des Ratens.

Das grundlegende Problem: Natürliche Sprache als Feedback verliert die räumliche Struktur, die der Prüfer im Sinn hatte. Der Prüfer weiß zwar, auf welchen Textabschnitt er sich bezieht – doch diese räumliche Information geht verloren, sobald das Feedback in Prosa formuliert wird.

Strukturiertes Feedback: Die Lösung für präzise KI-gestützte Dokumentenprüfung

Was wäre, wenn das Feedback des Prüfers nicht als Text, sondern als maschinenlesbares Format vorliegt – mit präzisen Verweisen auf die jeweilige Stelle im Quelldokument?

Genau hier setzt MDXG Redline an. Das Tool ermöglicht es, strukturierte Kommentare in gerenderten Markdown-Dokumenten zu hinterlassen und diese als JSON-Datei zu exportieren. Ein Beispiel für ein solches Feedback-JSON:

{
  "document": "api-spec.md",
  "docHash": "a1b2c3d4e5f6a7b8",
  "exportedAt": "2026-06-15T10:30:00.000Z",
  "comments": [
    {
      "id": "f3a1c8b2",
      "quote": "Der Dienst wiederholt den Aufruf bis zu dreimal",
      "comment": "Geben Sie die Rückfallstrategie an – handelt es sich um exponentielles Backoff oder feste Intervalle? Dies ist entscheidend für die Konfiguration von Timeouts auf Empfängerseite.",
      "headingPath": ["## 3. Fehlerbehandlung", "### 3.2 Wiederholungsrichtlinie"],
      "sourceLine": 142,
      "created": "2026-06-15T10:28:11.000Z"
    }
  ]
}

Jeder Kommentar enthält:

• `quote` – den exakt ausgewählten Textabschnitt (für menschliche Referenz).

• `comment` – die eigentliche Rückmeldung des Prüfers.

• `headingPath` – die hierarchische Überschriftenstruktur, von der obersten bis zur untersten Ebene. Der Agent kann so die Dokumentstruktur nachvollziehen.

• `sourceLine` – die Zeilennummer im Quelldokument, sodass der Agent direkt zur relevanten Stelle springen kann.

Zusätzlich enthält die JSON-Datei interne Felder wie blockId, startOffset und endOffset, die für den erneuten Import und die Verknüpfung mit der nächsten Überarbeitungsrunde genutzt werden.

Der Review-Prozess in der Praxis

MDXG Redline ist auf einen iterativen Review-Prozess zwischen Agent und Mensch ausgelegt:

1. Der Agent nutzt die CLI, um aus der Markdown-Datei eine `--review.html`-Datei zu generieren – eine eigenständige HTML-Datei mit Syntax-Highlighting, Diagrammen und mathematischen Formeln.

1. Die CLI öffnet automatisch den Standardbrowser des Prüfers.

1. Der Prüfer liest das gerenderte Dokument, markiert Textabschnitte und hinterlässt Inline-Kommentare. Mit einem Klick wird die `--feedback.json` im selben Ordner gespeichert.

1. Der Agent überwacht den Ordner im Hintergrund, übernimmt die JSON-Datei automatisch und wendet die Änderungen an.

Jede Überarbeitungsrunde erhält einen eindeutigen Hash im Dateinamen, sodass verschiedene Versionen des Dokuments und deren Feedback-JSONs nicht kollidieren.

Für Nutzer von Claude Code und Codex steht ein `md-review`-Skill zur Verfügung, der den gesamten Prozess automatisiert – von der HTML-Generierung über das Warten auf Feedback bis zur Anwendung der Änderungen:

# Skill installieren
gh skill install oubakiou/mdxg-redline md-review --agent claude-code --scope project

# Agent auffordern:
"Bitte führe einen Review für spec.md durch"

# Oder direkt über einen Slash-Befehl:
/md-review README.md

Der Skill ist eine vereinfachende Abstraktion. Da das Feedback-JSON als reine Textdatei vorliegt, funktioniert der Prozess mit jedem KI-Agenten – ob in einer benutzerdefinierten LangChain-Pipeline oder einem einfachen Shell-Skript, das auf neue JSON-Dateien wartet.

Fazit: Strukturiertes Feedback als Schlüssel zur Skalierung von KI-Dokumentation

Die Dokumentation bleibt ein kritischer Bestandteil der Softwareentwicklung – auch in Zeiten der KI-gestützten Codegenerierung. Während KI-Agenten immer schneller und präziser Code schreiben, wird die manuelle Prüfung der begleitenden Texte zur neuen Engstelle.

Tools wie MDXG Redline zeigen einen vielversprechenden Weg auf: Durch die Umwandlung von menschlichem Feedback in strukturierte, maschinenlesbare Formate lässt sich die Dokumentenprüfung präziser, schneller und weniger fehleranfällig gestalten. Die Zukunft der Softwareentwicklung könnte darin liegen, nicht nur Code, sondern auch Dokumentation im gleichen Maße zu automatisieren – und dabei die menschliche Expertise gezielt dort einzusetzen, wo sie am meisten zählt.