Die große Doku-Restrukturierung

Das falsche Gehege

Im letzten Post habe ich beschrieben, dass mein vergesslicher Partner ein artgerechtes Zuhause braucht: auffindbare Regeln, kompaktes Wissen, ein Einstieg, der auch ohne Vorgeschichte gelingt. Meine Doku lag von Anfang an im Repo – sinnvollerweise, denn so entsteht sie zusammen mit dem Code und wird mit ihm versioniert. Nur war sie trotzdem für die falsche Leserschaft gebaut: für Menschen.

Ich hatte sie angelegt, wie ich es noch von der Diplomarbeit kenne. Ein großes, hierarchisches Fachkonzept – 2.500 Zeilen allerfeinster Konzepte – und daneben dasselbe noch einmal als technisches Konzept. Beide schön durchnummeriert:

# 1. Fundament
## 1.1 Setting
## 1.2 Manifest
...

Für einen Menschen ist das völlig in Ordnung. Man liest sich einmal ein und blättert beim nächsten Mal gezielt zu „1.2”.

Zwei Fehler, die erst mit dem Agenten wehtun

Zwei Entscheidungen, die jahrelang niemanden gestört haben, wurden mit einem KI-Partner plötzlich teuer.

Die Nummerierung. Das ist erst einmal gar kein agentisches Problem, sondern ein ganz allgemeines: Eine steife Kapitelnummerierung mit Querverweisen auf genau diese Nummern macht es mühsam, ein Dokument zu erweitern – jeder Einschub verschiebt die Nummern, jeder Verweis muss nachgezogen werden. Als ordentlicher Entwickler fasst man seine Doku nach dem Schreiben aber ohnehin selten an, also fiel das nie auf. Mit einem Agenten, der ständig Dokumentation schreibt und umbaut, wird aus der Lappalie ein Dauerärgernis.

Die Größe. Wenige, große Dokumente, die denselben Kontext – verteilt über viele Kapitel – immer wieder aus verschiedenen Blickwinkeln beschreiben, machen es dem Agenten unnötig schwer. Er blättert nicht, er lädt – und hat nur zwei schlechte Optionen: alles laden (Kontext zu 90 % voll Ballast) oder sich ein paar Greps zusammenbauen und hoffen, das Richtige zu erwischen.

Die Lösung: eine Doku wie ein Wiki – aber im Repo

Die Lösung war schlicht: domänenspezifisch aufteilen, kleine Dateien, Kapitelnummern raus. Verweise zeigen seither auf Anker-Links, die mit ihrer Überschrift wandern, statt auf Nummern, die bei jeder Umsortierung brechen. Im Ergebnis liest sich die Doku heute wie ein Wiki – viele kleine, klar benannte Seiten statt zweier Monolithe.

Kurz habe ich überlegt, dann auch gleich ein echtes Wiki zu nehmen. Aber die Doku gehört ins Repo, aus zwei Gründen: Erstens entsteht sie so gemeinsam mit dem Code und wird mit ihm versioniert – der Stand der Doku passt immer zum Stand des Codes. Zweitens hat ein Agent im Dateisystem viel stärkere und schnellere Suchwerkzeuge als in einem Wiki: grep, glob, Datei lesen – millisekundenschnell, ohne Umweg über eine API.

So sieht das heute aus:

doc/
  audience/          # Zuschauerberechnung
    fachkonzept.md   #   fachlich
    backend.md       #   technisch, Backend
    frontend.md      #   technisch, Frontend
  supply/            # Filmverleiher & Werbeagentur
  profile/           # Profil und Ermüdung
  channel/           # Sender-Wirtschaft
  ...
  fk/                # globales Fachkonzept
  tk/                # globales technisches Konzept
  crosscutting/      # Workflow-Leitfäden

Jedes Feature ein Ordner, darin eine fachliche Datei und je eine für Backend und Frontend. Und ganz viel Verlinkung: Doku verweist auf Doku, Doku auf Code – und der Code zurück auf die Doku, über eine package-info.java je Domäne. Egal, von welcher Seite mein Partner ein Feature betritt, er findet die andere Hälfte.

Ein Tradeoff: deutsche Doku, englischer Code

Bleibt eine Reibung, die ich bewusst in Kauf nehme. Ich denke deutsch, das ganze Fachkonzept ist deutsch, und auch die Fachbegriffe habe ich deutsch im Kopf – also soll die Doku deutsch bleiben. Andererseits kriege ich Augenkrebs, wenn im englischen Quellcode überall deutsche Begriffe stehen.

Die Brücke ist eine einzige Datei: namensmapping.md. Sie legt für jeden deutschen Fachbegriff genau eine englische Code-Benennung fest – „Werbevertrag” → advertisingContract, „Sendeplatz” → BroadcastSlot. Neue Übersetzungen entstehen nicht ad hoc beim Generieren des Codes, sondern zuerst hier. So bleibt die Doku deutsch, der Code englisch, und niemand erfindet drei Namen für dieselbe Sache.

Was hat’s gebracht?

Der ganze Doku-Umbau war kein schleichender Prozess, sondern eine Hauruck-Aktion, bei der ich wirklich nur Doku und keine Funktion geändert habe. Das hat mir erlaubt, das Ergebnis zu messen, indem ich den Agenten dieselbe Aufgabe einmal vor und einmal direkt nach dem Umbau lösen ließ.

Die Messmethode, kurz:

Gleiche Prompts, beide Stände. Jede Aufgabe lief fünfmal pro Stand, in verschränkter Reihenfolge – damit kein Stand von einem warmen Cache profitiert.
Frischer Kopf pro Lauf. Jeder Lauf war eine eigene, gedächtnislose Session (headless claude -p), nur mit Lese-Werkzeugen und ohne Subagenten. Gemessen wird die Repo-Navigation, nicht die Tagesform.
Gemessen: Dauer, Token-Verbrauch (cache-neutral gezählt) und Arbeitsschritte.
Qualität blind bewertet. Ein zweiter, unabhängiger Agent benotete die Antworten gegen die echten Doku-Fakten – er sah nur den Text, nicht, aus welchem Stand er stammte.

Und das kam heraus (jeweils nachher gegenüber vorher):

Kategorie	Aufgabe	Tokens	Qualität	Effekt
Trivial (Grep)	„Welche Klasse berechnet die Quote?”	± 0	gleich	kein Effekt
Fokussiert	„Wie funktioniert der Filmverleiher?”	+16 %	Fehler 4/5 → 0/5	treffsicherer
Fokussiert	„Wie funktioniert die Zuschauerberechnung?”	−29 %	gleich	schneller (−49 % Zeit)
Fokussiert	„Profil auf Zielgruppe umstellen?”	−44 %	gleich	halb so viele Schritte
Global	„Frontend-App neu konzipieren”	−7 bis −16 % (schwankend)	gleich	leicht schneller (~1 Schritt, −28 % Zeit)

Das Muster ist erstaunlich klar. Bei der trivialen Aufgabe bringt der Umbau nichts – die löst der Agent per Code-Grep, die Doku liegt gar nicht auf dem Weg. Bei den fokussierten Domänenfragen ist der Gewinn groß: mal die halbe Zeit und ein Drittel weniger Tokens bei gleicher Qualität, mal die Fehlerquote von vier aus fünf Antworten auf null. Und bei der global-galaktischen Aufgabe („konzipier mal das ganze Frontend”) bleibt ein kleiner, aber wackliger Vorteil: die Dauer sinkt spürbar und der Agent braucht etwa einen Arbeitsschritt weniger, aber die Tokenersparnis schwankt von Lauf zu Lauf stark. Hier muss er ohnehin fast alles einlesen – da bringt es wenig, dass er einzelne Teile schneller findet.

Nicht nur für den Agenten

Die Restrukturierung war kein Kompromiss zugunsten des Agenten. Ich selbst finde die Doku heute ebenfalls besser: leichter zu erweitern, leichter wiederzufinden und weniger abhängig davon, dass man ihre ursprüngliche Reihenfolge kennt.

Dokumentation kann auf verschiedene Arten gut sein. Sie kann ein großes, sorgfältig aufgebautes Buch sein – oder ein Netz aus kleinen, klar verbundenen Seiten. Für Menschen funktionieren beide Formen. Der Agent profitiert aber deutlich davon, wenn er nicht erst das ganze Buch lesen muss, um das richtige Kapitel zu finden.

Menschen lesen Dokumentation von oben nach unten. Agenten suchen sich ihren Weg. Gute Dokumentation lässt beides zu.