KI-Dokumentation richtig machen: Warum der Weg wichtiger ist als das Ziel

In einer späten Nacht-Sitzung mit Claude Code tippte ich eine unvollständige Frage in gebrochenem Englisch: "Are we using full Netflix level doc uodsyed as ws go here?" Gemeint war: Soll die Dokumentation so detailliert wie bei Netflix entstehen – mit allen Entscheidungen und Alternativen – oder nur oberflächlich die Änderungen festhalten? Der KI-Assistent verstand die Absicht und leitete eine neue Dokumentationsstrategie ein, die ich heute als "paper-trail" bezeichne.

Diese Methode nutzt zwei Dateien und einen klaren Prozess, um nicht nur den Code, sondern den gesamten Denkprozess festzuhalten. Warum das wichtig ist? Weil KI-Systeme keine Intuition haben – sie brauchen Kontext, um in Zukunft sinnvolle Vorschläge zu machen. Gleichzeitig verschwinden Entscheidungen und verworfene Ansätze schnell aus dem menschlichen Gedächtnis. Ein strukturierter Dokumentationsansatz schließt diese Lücke.

Warum die Denkweise der KI verloren geht

Die meisten Dokumentationen beschreiben nur den Endzustand eines Systems:

• README-Dateien erklären, was eine Anwendung leistet.
• CHANGELOG-Einträge listen veröffentlichte Versionen auf.
• Commit-Nachrichten dokumentieren, welche Dateien geändert wurden.

Doch was dabei oft fehlt, sind die entscheidenden Zwischenschritte:

• Welche drei Alternativen wurden vor der finalen Lösung verworfen?
• Welche Rückmeldung eines Teammitglieds führte zur Überarbeitung eines Entwurfs?
• Welche Tests bestätigten die Wirksamkeit einer Lösung?
• Welche nächtliche Fehlentscheidung erklärt einen komplizierten Workaround?
• Welche Abhängigkeit wurde erst erkannt, nachdem etwas schiefging?

Als Menschen behalten wir dieses Wissen oft nur für kurze Zeit im Kopf. Bei KI-gestützter Entwicklung verschärft sich das Problem: Der Assistent erinnert sich nicht an verworfene Optionen. Sechs Monate später könnte er eine bereits abgelehnte Lösung vorschlagen – ohne Kontext, warum sie damals verworfen wurde.

Zwei Dateien, eine klare Struktur

Die Lösung besteht aus zwei zentralen Dateien, die parallel gepflegt werden:

• `CHANGES.md` im Projektverzeichnis: Eine chronologische Liste der Änderungen, sortiert nach Datum (neueste Einträge oben). Jeder Eintrag dokumentiert:
• Was geändert wurde
• Warum die Änderung notwendig war
• Welche Entscheidungen getroffen wurden
• Welche Alternativen verworfen wurden
• Wie die Lösung verifiziert wurde
• Offene Aufgaben oder Abhängigkeiten

• `docs/narrative/-.md` für größere Zusammenhänge: Hier werden umfangreiche Änderungen wie Migrationen, Systemumstellungen oder Vorfälle dokumentiert. Jede Datei folgt einem einheitlichen Aufbau:
• Ausgangssituation
• Auslöser des Problems
• Entscheidungsprozess
• Verworfene Ansätze
• Umsetzungsschritte
• Verifizierungsergebnisse
• Offene Punkte

Während CHANGES.md als Index dient, erzählt docs/narrative die Geschichte hinter dem Code. Beide Dateien sind als einfache Markdown-Dateien angelegt und werden versioniert. Sie sind so strukturiert, dass sie sowohl von Entwicklern als auch von KI-Tools durchsucht werden können.

Ein reales Beispiel aus der Praxis

Ein konkretes Beispiel aus einem kürzlichen Projekt zeigt, wie CHANGES.md aussieht. Angenommen, ein Musik-Synchronisationsfeature in einer iOS-App war nach einem Backend-Umbau verschwunden. Die Einträge in der Datei könnten so aussehen:

2026-05-16: Musik-Sync-Zeile in iOS-Einstellungen wiederhergestellt
Nach dem Backend-Konsolidierungsprojekt vom 2026-05-04 fehlte in den iOS-Einstellungen die Zeile, die das Musik-Sync-Feature für Nutzer sichtbar machte. Die Sync-Pipeline im Backend funktionierte weiterhin; nur die UI-Komponente war bei der Aufräumaktion entfernt worden.

Wiederhergestellt durch 6 Zeilen Code in `App/Views/SettingsView.swift`, die die Zeile unter "Datenquellen" hinzufügten. Die TestFlight-Version 47 enthält die Wiederherstellung. Verifiziert durch einen frischen Sync auf einem Testgerät mit der Lieferungs-UUID `8b4f2a9c-7d15-4e83-9bcd-12fa8e5c61d4`, die erfolgreich im Backend landete.

Entscheidung: Die Zeile wurde in der ursprünglichen Form wiederhergestellt, statt das gesamte Einstellungsmenü umzustrukturieren – da die Konsolidierungsbegründung auf diese Zeile nicht zutraf.

Verworfen: Eine Verlagerung des Musik-Features in einen separaten "Medien"–Abschnitt. Der Aufwand für eine solche Umstrukturierung stand in keinem Verhältnis zum Nutzen.

Offen: Integration des neuen Qwen-Commits `a3f2c8e91` für die Audio-Pfad-Optimierung in der nächsten Woche.

Commit: `e74b2c1`

Diese Einträge enthalten nicht nur den Code, der die Änderung umsetzt, sondern auch die Entscheidungsgrundlagen und verworfenen Alternativen. So kann später nachvollzogen werden, warum bestimmte Lösungen gewählt – oder verworfen – wurden. Die zugehörige narrative Datei würde den gesamten Kontext vertiefen: vom Auslöser (ein Test zeigte fehlende Daten) über die Analyse der ursprünglichen Code-Änderung bis hin zur endgültigen Lösung.

So richtet man das System ein

Das paper-trail-System ist als Open-Source-Projekt unter github.com/niclydon/paper-trail verfügbar und lässt sich in wenigen Schritten integrieren:

• Die Datei DOCUMENTARY_STYLE_DOCUMENTATION.md aus dem Repository in das Wurzelverzeichnis eines Projekts kopieren (z. B. ~/projects/).
• In der zentralen CLAUDE.md des Projekts den Eintrag @DOCUMENTARY_STYLE_DOCUMENTATION.md hinzufügen.
• Die projektspezifische Vorlage aus templates/per-project-boilerplate.md in jedes Projekt kopieren.
• Eine leere CHANGES.md im Projektverzeichnis anlegen.
• Für die erste größere Änderung oder einen Vorfall eine narrative Datei im Ordner docs/narrative/ nach dem bereitgestellten Skelett erstellen.

Sobald das System konfiguriert ist, beginnt Claude Code automatisch, Einträge in CHANGES.md zu erstellen, sobald im Projekt gearbeitet wird. Es gibt auch eine abgespeckte Variante namens -LITE, die etwa 75 % weniger Aufwand erfordert, aber die gleiche Disziplin beibehält.

Was das System kostet – und was es bringt

Die Nutzung von paper-trail verursacht messbare, aber überschaubare Kosten:

• In Claude Code erscheint der Befehl /narrative-docs-update im Status-Check etwa bei 9 % des wöchentlichen Budgets eines Pro-Plans. Diese Kosten entstehen nur, wenn bewusst narrative Dokumentationen erstellt oder aktualisiert werden.
• Die eigentliche Dokumentationsarbeit geschieht inline während der regulären Arbeitssitzungen und lässt sich kaum von der Code-Entwicklung trennen.

Der größte Nutzen entsteht jedoch in der Zukunft:

• Für Entwickler: Klare Entscheidungsdokumentation reduziert Debugging-Zeit und vermeidet doppelte Arbeit.
• Für KI-Assistenten: Mit historischem Kontext können sie bessere Vorschläge machen und Fehler aus der Vergangenheit vermeiden.
• Für Teams: Neumitglieder oder externe Dienstleister verstehen schneller, warum bestimmte Lösungen gewählt wurden – ohne stundenlange Code-Reviews oder Nachfragen.

Der Schlüssel liegt nicht in der perfekten Dokumentation, sondern in der konsequenten Anwendung. Sobald das System etabliert ist, wird es zur natürlichen Erweiterung des Entwicklungsprozesses – und verhindert, dass wertvolles Wissen in Code-Zeilen oder dem menschlichen Gedächtnis verschwindet.

In einer Welt, in der KI immer mehr Code schreibt, wird die Fähigkeit, den Denkprozess festzuhalten, zum entscheidenden Wettbewerbsvorteil. paper-trail ist ein einfacher, aber mächtiger Ansatz, um diese Lücke zu schließen.