Dokumentation mit KI schreiben: von README bis Changelog

Um Dokumentation mit KI zu schreiben, lässt du einen Coding-Agenten den Code lesen und die Befehle ausführen, die er dokumentiert, gibst jedem Dokument eine klare Zielgruppe und prüfst jede Funktion, jedes Flag und jedes Beispiel, das er erwähnt, gegen das Repository. Agenten wie Claude Code und Codex sind gut in den mühsamen Teilen der Dokumentation: aus einer Codebasis ein README machen, Docstrings ergänzen, ein Release aus der Git-Historie zusammenfassen. Ihre Schwachstelle ist ihre Selbstsicherheit: Sie beschreiben eine Option, die plausibel klingt, aber nie implementiert wurde.

Diese Anleitung zeigt, was du mit einem Agenten dokumentieren kannst, welche Prompts für welche Art von Doku funktionieren, wie du Changelogs aus git log erzeugst, wie du Doku synchron hältst, wo AGENTS.md hingehört und wie du KI-geschriebene Doku auf erfundene APIs prüfst.

Agent statt Chatfenster

Den größten Qualitätssprung bringt die Frage, wo das Modell schreibt. Wenn du eine Datei in ein Chatfenster einfügst und um Doku bittest, hat das Modell eine Datei und keine Möglichkeit, irgendetwas zu prüfen. Ein Coding-Agent, der in deinem Repository läuft, kann:

• die Dateien öffnen, die der Code aufruft, nicht nur die eine, die du eingefügt hast;
• --help, die Testsuite oder das Beispiel ausführen, das er gerade geschrieben hat;
• jede Stelle suchen, an der eine Funktion verwendet wird;
• die bestehende Doku lesen und ihren Stil übernehmen.

Jeder Prompt unten setzt voraus, dass der Agent im Repository läuft. Falls du noch keinen eingerichtet hast, helfen dir Claude Code nutzen und Codex CLI nutzen dabei.

Zuerst die Zielgruppe festlegen

„Schreib Doku für dieses Projekt“ ergibt eine generische Seite. Jede Art von Dokument hat einen anderen Leser und eine andere maßgebliche Quelle:

Schreib Leser und Quelle in den Prompt. Das verändert das Ergebnis stärker als jede Stilvorgabe.

README

Ein gutes README beantwortet schnell vier Fragen: Was ist das, wie installiere ich es, wie nutze ich es und wie trage ich bei. Bitte den Agenten, beim Schreiben zu prüfen:

Schreib README.md für dieses Repository. Zielgruppe: ein Entwickler, der es
zum ersten Mal sieht. Abschnitte: was es tut (2–3 Sätze), Voraussetzungen,
Installation, Schnellstart, Konfiguration, Tests ausführen, Projektstruktur.

Regeln:
- Nimm die Befehle aus den package.json-Skripten und dem CI-Workflow; führe jeden
  Installations- und Schnellstart-Befehl aus und korrigiere das README, wenn einer fehlschlägt.
- Liste nur Umgebungsvariablen auf, die im Code tatsächlich gelesen werden;
  nenne zu jeder die Datei.
- Keine Badges, keine Werbesprache, keine Features, die nicht im Code stehen.

„Führe jeden Befehl aus“ macht aus einem plausiblen README ein korrektes. Wenn der Agent etwas nicht ausführen kann (weil Zugangsdaten nötig sind, zum Beispiel), bitte ihn, diesen Schritt als ungeprüft zu markieren, damit du ihn von Hand checkst.

API-Referenz

Bei Bibliotheken und Services erzeugst du so viel Referenzmaterial wie möglich aus dem Quellcode und setzt den Agenten für die Teile ein, die Generatoren nicht schreiben können: Übersichten, Beispiele und Erklärungen für kniffliges Verhalten.

Bei einer HTTP-API bittest du den Agenten, die Referenz direkt aus den Routendefinitionen aufzubauen:

Dokumentiere jeden HTTP-Endpunkt in src/routes. Für jeden: Methode, Pfad,
Auth-Anforderung, Request-Body und Query-Parameter mit Typen,
Form der Antwort, Fehler-Statuscodes. Lies den Handler und das
Validierungsschema; leite nichts aus Namen ab. Füge pro Endpunkt ein
curl-Beispiel hinzu und führe es gegen den lokalen Dev-Server aus.

Wenn das Projekt schon OpenAPI nutzt, lass den Agenten die Spec-Datei aktualisieren, statt eine separate Markdown-Referenz zu schreiben, und lass deine bestehenden Tools sie rendern. Eine einzige maßgebliche Quelle lässt sich leichter ehrlich halten als zwei.

Docstrings und JSDoc

Agenten ergänzen Docstrings in einem ganzen Modul schnell, und genau hier beschreiben sie am häufigsten, was eine Funktion tun sollte, statt was sie tut. Bitte um Verhalten, das im Funktionsrumpf sichtbar ist:

Füge JSDoc zu jeder exportierten Funktion in src/billing/ hinzu. Für jede:
einzeilige Zusammenfassung, @param mit Typ und Bedeutung, @returns und @throws
für jeden Fehler, den die Funktion tatsächlich werfen kann (lies den Rumpf und
die Funktionen, die sie aufruft). Füge ein @example nur hinzu, wenn du es ausführst.
Ändere keinen Code.

Zwei günstige Prüfungen machen Docstrings vertrauenswürdig:

• TypeScript in JS-Projekten: Mit // @ts-check am Anfang einer Datei oder checkJs in der tsconfig.json prüft TypeScript die JSDoc-Typen, sodass ein falscher @param-Typ als Fehler auftaucht.
• Python: Beispiele im Doctest-Format (>>>-Zeilen) lassen sich mit python -m doctest module.py -v ausführen, sodass ein Beispiel, das vom Code abweicht, fehlschlägt.

Eine nützliche Faustregel: Ein Docstring sollte sagen, warum und wofür, und nicht die Signatur wiederholen. „Gibt den Nutzer zurück“ bei getUser(id): User ist Rauschen; „Gibt null für soft-gelöschte Nutzer zurück; Aufrufer müssen das behandeln“ ist es wert. Sag das dem Agenten.

Architekturnotizen

Bei Architektur-Doku sparen Agenten die meiste Zeit, weil der schwierige Teil darin besteht, viel Code zu lesen und zusammenzufassen. Hier verstecken sich aber auch Halluzinationen am besten, denn niemand prüft ein Diagramm Zeile für Zeile. Grenze den Agenten ein:

Schreib docs/architecture.md für Engineers, die neu in der Codebasis sind.
Behandle: die Hauptmodule und wofür jedes zuständig ist, wie ein Request von
der HTTP-Schicht zur Datenbank fließt, Hintergrund-Jobs und externe Services.
Nenne zu jeder Aussage die Datei (und Funktion), aus der sie stammt.
Füge ein Mermaid-Diagramm des Request-Flusses hinzu.
Markiere alles, bei dem du unsicher bist, mit "TODO: verify".

Die Quellenangaben sind der Kern: Mit ihnen kann ein Reviewer Aussagen in Sekunden stichprobenartig prüfen, und sie zeigen, welche Teile veralten, wenn sich diese Dateien ändern. Halte fest, warum Entscheidungen getroffen wurden, nicht nur, was existiert; ein kurzes Entscheidungslog (im ADR-Stil: Kontext, Entscheidung, Konsequenzen) altert besser als eine Beschreibung des aktuellen Codes. Eine Codebase-Map für KI-Agenten behandelt das verwandte Problem, Agenten eine Übersicht zu geben, in der sie navigieren können.

Changelogs aus git log

Release Notes sind eine perfekte Agenten-Aufgabe: Das Rohmaterial liegt in Git, und die Arbeit besteht darin, für Nutzer zu filtern und umzuschreiben. Starte mit dem Bereich seit dem letzten Tag:

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Dann der Prompt:

Schreib den CHANGELOG.md-Eintrag für das nächste Release aus
git log v1.4.0..HEAD --no-merges. Zielgruppe: Nutzer, die aktualisieren.
Verwende die Keep-a-Changelog-Überschriften (Added, Changed, Deprecated,
Removed, Fixed, Security). Lass Refactorings, Tests, CI und Routinearbeiten weg.
Formuliere jeden Eintrag aus Nutzersicht, setze Breaking Changes mit
Upgrade-Schritten an den Anfang und behalte den kurzen Hash neben jedem Eintrag.

Wenn dein Team Conventional Commits schreibt (feat:, fix:, feat!: für Breaking Changes), erwähne das; der Agent kann dann zuverlässig nach Typ sortieren. Sind die Commit-Messages knapp, lass den Agenten bei den wichtigen Einträgen den Diff (git show <hash>) oder den verlinkten Pull Request lesen. Der Hash neben jeder Zeile macht das Review schnell: Du prüfst einen Eintrag, indem du seinen Commit öffnest.

Doku synchron halten

Doku veraltet, weil sie in einem separaten Schritt aktualisiert wird, den niemand einplant. Die Lösung: Mach die Doku zum Teil der Änderung.

1. Gleiche Änderung, gleicher Agent. Füge deinen Agentenregeln eine Zeile hinzu: „Wenn du Verhalten, Flags, Umgebungsvariablen oder öffentliche APIs änderst, aktualisiere die zugehörige Doku im selben Commit.“

2. Verlange am Ende jeder Aufgabe einen Doku-Check:

   Liste jede Doku, jeden README-Abschnitt, jeden Docstring und jedes Beispiel auf,
   das den Code erwähnt, den du geändert hast. Aktualisiere die, die jetzt falsch sind.

3. Prüfe einen Branch vor dem Mergen: Gib dem Agenten den Diff (git diff main...HEAD) und den Doku-Ordner und frag, welche Aussagen in der Doku durch den Diff falsch werden.

4. Führe Beispiele als Tests aus. Doctests, ein Skript, das README-Snippets ausführt, oder typgeprüftes JSDoc machen aus veralteter Doku fehlschlagende Builds.

5. Erzeuge, was sich erzeugen lässt. CLI-Hilfetexte, OpenAPI-Specs und Typreferenzen, die aus dem Quellcode generiert werden, können nicht abdriften.

AGENTS.md ist nicht deine Dokumentation

AGENTS.md (gelesen von Codex und vielen anderen Agenten) und CLAUDE.md (gelesen von Claude Code) sind Anweisungsdateien für Coding-Agenten. Sie werden in jede Session geladen und sollten deshalb kurz sein: Build- und Testbefehle, Konventionen, Ordner, die tabu sind. /init in Claude Code oder Codex erzeugt eine erste Version.

Deine Doku für Menschen hat eine andere Aufgabe und darf so lang sein, wie sie sein muss. Beides zu vermischen verursacht zwei Probleme: Eine lange AGENTS.md verschwendet bei jeder Aufgabe Kontext des Agenten, und ein README voller Agentenregeln verwirrt Menschen. Halte beides getrennt und verlinke gegenseitig:

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

CLAUDE.md und AGENTS.md erklärt, was in diese Dateien gehört und wie du einen Satz Regeln über mehrere Agenten hinweg teilst.

KI-geschriebene Doku auf halluzinierte APIs prüfen

Der schädlichste Doku-Fehler ist eine API, die es nicht gibt: eine Konfigurationsoption, ein CLI-Flag oder eine Methode, die das Modell erfunden hat, weil ähnliche Projekte so etwas haben. Leser vertrauen der Doku und verlieren deshalb Zeit, bevor sie vermuten, dass die Doku falsch ist. Prüfe gezielt darauf:

• Jeden Namen suchen. Bitte den Agenten (oder einen zweiten Agenten), jede Funktion, Option, jedes Flag, jede Umgebungsvariable und jeden Endpunkt aus der neuen Doku herauszuziehen und im Code nach jedem zu suchen. Was nicht gefunden wird, fliegt raus.

  Zieh jeden Bezeichner, jedes CLI-Flag, jeden Config-Key und jede Umgebungsvariable aus
  docs/api.md heraus. Zeig zu jedem, wo er im Code definiert ist, mit
  file:line, oder schreib NOT FOUND. Bearbeite nichts.

• Jedes Beispiel ausführen. Codeblöcke, die nie ausgeführt wurden, sind Vermutungen.

• Standardwerte und Limits prüfen. Zahlen (Timeouts, Größen, Retries) sind oft erfunden; jede sollte sich auf eine Konstante im Code zurückführen lassen.

• Auf „unterstützt auch“ achten. Zeilen wie „unterstützt auch YAML-Konfiguration“ oder „lässt sich mit Redis nutzen“ sind klassische Füller. Frag nach dem Code, der das tut.

• Einen zweiten Reviewer einsetzen. Ein separater Agent, der die Doku gegen den Code prüft, hängt weniger daran als der, der sie geschrieben hat. KI-Code-Review zeigt, wie du das einrichtest.

Dokumentation mit AgentVera

AgentVera ist eine Desktop-App für macOS, Windows und Linux, die Claude Code, Codex, Gemini CLI und andere CLI-Agenten nebeneinander ausführt. Einige ihrer Werkzeuge helfen bei der Doku:

• Schreiber und Prüfer nebeneinander: Lass im selben Workspace einen Agenten die Doku schreiben und einen zweiten sie gegen den Code prüfen, oder gib der Doku-Arbeit einen eigenen Worktree.
• Specs-Tab: listet die Markdown-Dateien des Repos auf, neueste zuerst, sortiert in Specs, Pläne und Dokumente, einschließlich nicht committeter Dateien, die Agenten in anderen Worktrees geschrieben haben. Markdown öffnet sich in der Vorschau.
• Brain: liest dein README, ARCHITECTURE, CHANGELOG, ADRs, Commits und PRs, listet Entscheidungen mit ihren Gründen auf und markiert die, deren Code-Begriffe im Code nicht mehr vorkommen, ein nützliches Signal für veraltete Doku.
• Projekttour: ein schreibgeschützter Claude-Code-Lauf, der Stack, Module und wichtige Dateien eines Repositorys zusammenfasst, ein guter erster Entwurf für Architekturnotizen.
• Code-Review: Prüfe die Doku-Änderungen eines Agenten mit dem Claude-Modell deiner Wahl, mit Befunden, die auf Datei und Zeile verlinken.
• Git-Panel: Durchsuche die Historie, aus der du Changelogs baust, und lass Claude Haiku Commit-Messages im Stil deines Repos schreiben, was den nächsten Changelog leichter macht.

Fazit

KI macht Dokumentation billig zu schreiben, und damit wird Genauigkeit zur eigentlichen Arbeit. Lass den Agenten im Repository laufen, sag ihm, wer der Leser ist und wo die Wahrheit steht, lass ihn Befehle und Beispiele ausführen und baue Changelogs aus git log mit erhaltenen Hashes. Aktualisiere die Doku in derselben Änderung wie den Code, halte AGENTS.md für Agenten und die Doku für Menschen getrennt und suche jeden dokumentierten Namen im Code, bevor du veröffentlichst. Wenn eine Doku stattdessen einen Bug aufdeckt, macht Code mit KI debuggen dort weiter.