Qualität & Belege
Dokumentation, die selbst zur Überprüfung auffordert
Veraltete Dokumentation ist selten offensichtlich kaputt. Meist liest sie sich weiterhin flüssig, benutzt vertraute Begriffe und erklärt eine Architektur, die einmal gestimmt hat. Gerade das macht sie bei Übergaben gefährlich. Neue Teammitglieder und externe Partner können nicht erkennen, welche Sätze noch auf dem aktuellen System beruhen. Die interessante technische Aufgabe ist deshalb nicht nur, mehr Text zu erzeugen. Sie besteht darin, die nächste notwendige Überprüfung rechtzeitig sichtbar zu machen.
Die Erklärung braucht eine Verbindung zur Quelle
In meinem Open-Source-Projekt Tabula werden Repository-Anleitungen mit Quelldateien verknüpft. Das Werkzeug hält deren Hashes fest und weist auf Abschnitte hin, die nach Änderungen überprüft werden sollten. Es läuft offline, ohne Modell oder Konto, und führt den Projektcode nicht aus. Tabula ist ein frühes Projekt; vorbereitete lokale Pakete sind dabei nicht mit einer bereits erfolgten offiziellen Veröffentlichung gleichzusetzen.
Der interessante Punkt ist nicht, dass ein Hash die Bedeutung eines Programms versteht. Er versteht sie gerade nicht. Er kann lediglich anzeigen, dass sich eine verknüpfte Grundlage verändert hat. Damit entsteht ein konkreter Anlass für ein Review. Die Entscheidung, ob ein Absatz noch stimmt, bleibt bei einer Person, die den Zusammenhang beurteilen und ihre Verantwortung dafür übernehmen kann.
Frisch ist nicht automatisch richtig
Eine unveränderte Datei kann schon bei der ersten Beschreibung falsch verstanden worden sein. Umgekehrt kann eine harmlose Änderung an Kommentaren einen neuen Hash erzeugen, ohne die Erklärung zu entwerten. Deshalb wäre ein großes grünes „aktuell“ als pauschales Gütesiegel irreführend. Der technische Status muss sagen, was geprüft wurde: die Verbindung zu unveränderten Dateien, nicht die Wahrheit jedes Satzes.
Für die Leitung eines Teams ist diese begrenzte Aussage dennoch wertvoll. Sie erlaubt eine gezieltere Verteilung von Aufmerksamkeit. Statt sämtliche Unterlagen gleich dringend zu behandeln, können Verantwortliche dort beginnen, wo sich dokumentierte Grundlagen bewegt haben. Daraus folgt keine belegte Einsparungsquote. Es folgt ein klarerer Arbeitsauftrag: Prüfen Sie diese Erklärung, weil sich ihre referenzierte Grundlage geändert hat.
Struktur hilft beim Suchen, nicht beim Überspringen des Denkens
Mein Open-Source-Projekt ast-index-nix erstellt einen lokalen Strukturindex für Quellcode. Es erfasst unter anderem Definitionen, Aufrufstellen und Importe und macht diese Informationen für Menschen und Coding-Agenten zugänglich. So lässt sich untersuchen, welche Teile eines Systems von einer Änderung betroffen sein könnten. Der Index bietet dafür mehr Orientierung als eine bloße Sammlung ähnlich klingender Textstellen.
Auch hier ist die Grenze wichtig: Statische Auflösung hat je nach Programmiersprache Einschränkungen. Der Index kann unbekannte, veraltete oder unvollständige Evidenz melden. Eine nicht gefundene Abhängigkeit beweist daher nicht, dass keine existiert. Bei einer kritischen Entscheidung sollte das Team erklären können, welche Bereiche erfasst wurden und wo dynamisches Verhalten oder andere Einschränkungen zusätzliche Untersuchung nötig machen.
Auch Entscheidungen haben ein Ablaufdatum
In meinem Open-Source-Projekt ichnora geht es um lokales, projektbezogenes Gedächtnis für Coding-Agenten. Entscheidungen, Zwischenstände und Behauptungen können mit Herkunft und unterstützenden Belegen gespeichert werden. Abhängigkeiten lassen sich auf veraltete Grundlagen prüfen. Die Suche arbeitet ohne Modellaufrufe. Das Ziel ist nicht, frühere Aussagen automatisch zur dauerhaften Wahrheit zu erklären, sondern ihren Kontext wieder auffindbar zu machen.
Wenn eine frühere Entscheidung auf einer inzwischen geänderten Voraussetzung beruht, ist das Erinnern allein nicht genug. Das System muss die Unsicherheit zeigen können. Historische Aussagen können weiterhin erklären, warum ein Team damals so gehandelt hat, ohne heute eine gültige Handlungsanweisung zu sein. Diese Trennung schützt vor einer besonders überzeugenden Form veralteter Dokumentation: einer gut belegten Antwort auf eine Frage, deren Voraussetzungen nicht mehr gelten.
Ein Review braucht einen Besitzer
Aus diesen Werkzeugen entsteht kein selbstpflegendes Wissenssystem. Ein Hinweis auf veränderte Grundlagen braucht eine zuständige Person und eine Entscheidung: Text korrigieren, Zusammenhang bestätigen oder die alte Aussage bewusst als historisch kennzeichnen. Ohne diesen Schritt sammelt ein Team lediglich Hinweise an. Die Automatisierung hat dann zwar eine Abweichung entdeckt, aber noch keine Verantwortung organisiert.
Für eine Beschaffung würde ich deshalb nicht nur nach Suchqualität oder erzeugten Dokumentseiten fragen. Interessanter ist, ob das System die Grenzen seines Wissens zeigen kann und ob ein Review nachvollziehbar abgeschlossen wird. Eine ehrliche Anzeige „unvollständig“ hilft bei einer Entscheidung mehr als scheinbare Gewissheit. Gute Dokumentation verspricht nicht, niemals falsch zu liegen. Sie erleichtert es, den nächsten notwendigen Zweifel zu erkennen.
Fragen an Ihr Team oder Ihren Anbieter
- Welche Erklärungen hängen von einer geänderten Datei oder einer überholten Entscheidung ab?
- Bedeutet „aktuell“ nur unveränderte Bytes, oder hat jemand die inhaltliche Richtigkeit überprüft?
- Wie zeigt das Werkzeug unbekannte, veraltete und unvollständige Informationen an?
- Welche Grenzen hat die Erkennung von Abhängigkeiten in den tatsächlich verwendeten Programmiersprachen?
- Bleiben Herkunft und frühere Voraussetzungen einer gespeicherten Entscheidung auch später nachvollziehbar?
- Wer übernimmt einen Review-Hinweis, und wie wird dessen fachlicher Abschluss dokumentiert?