Lerne Claude Code für Dokumentationsdrift kennen, um READMEs, API‑Docs und Runbooks mit dem Code abzugleichen — durch Diffs und Markierung von Widersprüchen.
Dokumentationsdrift ist das schrittweise Auseinanderlaufen dessen, was deine Docs sagen, und dem, was der Code tatsächlich tut. Es beginnt mit kleinen Abweichungen und wird dann zur „das hat letzten Monat doch noch funktioniert“-Verwirrung.
In einem echten Team sieht Drift so aus: Das README sagt, ein Service starte mit einem einzigen Befehl, aber inzwischen ist eine neue Umgebungsvariable erforderlich. Die API‑Dokumentation zeigt einen Endpoint mit einem Feld, das umbenannt wurde. Ein Runbook sagt dem On‑Call, „worker‑a“ neu zu starten, aber der Prozess ist inzwischen auf zwei Services aufgeteilt.
Drift entsteht auch bei guten Absichten, weil Software schneller ändert als Dokumentationsgewohnheiten. Leute liefern Fixes unter Druck aus, kopieren alte Beispiele oder gehen davon aus, dass jemand anders die Docs später aktualisiert. Drift wächst außerdem, wenn es zu viele vermeintliche „Quellen der Wahrheit“ gibt: README‑Dateien, API‑Referenzen, interne Wikis, Tickets und Wissen, das nur im Team existiert.
Die Kosten sind konkret:
Schönere Formulierungen beheben Drift nicht, wenn die Fakten falsch sind. Hilfreich ist, Docs so zu behandeln, dass man sie verifizieren kann: vergleiche sie mit dem aktuellen Code, den Konfigurationen und realen Outputs und mache Widersprüche deutlich, wenn die Docs ein Verhalten versprechen, das der Code nicht mehr liefert.
Drift taucht meist in Dokumenten auf, die Leute als „Schnellreferenz“ nutzen. Sie werden einmal aktualisiert, und dann läuft der Code weiter. Fang mit diesen drei an, weil sie konkrete Versprechen enthalten, die man überprüfen kann.
READMEs driften, wenn sich alltägliche Befehle ändern. Ein neuer Flag wird hinzugefügt, ein alter entfernt oder eine Umgebungsvariable umbenannt, aber im Setup‑Abschnitt steht noch die alte Realität. Neue Teammitglieder kopieren Anweisungen, stoßen auf Fehler und denken, das Projekt sei kaputt.
Die schlimmste Version ist „fast richtig“. Eine fehlende Umgebungsvariable kann mehr Zeit kosten als ein völlig veraltetes README, weil Leute kleine Variationen immer wieder ausprobieren statt das Dokument in Frage zu stellen.
API‑Docs driften, wenn sich Request‑ oder Response‑Felder ändern. Selbst kleine Verschiebungen (umbenannte Keys, andere Defaults, neue Pflichtheader) können Clients brechen. Oft ist die Endpunktliste noch korrekt, während die Beispiele falsch sind — genau das, was Nutzer kopieren.
Typische Signale:
Runbooks driften, wenn sich Deployment‑, Rollback‑ oder Betriebsabläufe ändern. Ein veralteter Befehl, ein falscher Service‑Name oder eine fehlende Voraussetzung kann eine Routine‑Behebung in Downtime verwandeln.
Sie können auch „genau, aber unvollständig“ sein: Die Schritte funktionieren noch, aber sie überspringen eine neue Migration, einen Cache‑Clear oder das Umschalten eines Feature‑Flags. Dann folgen Antwortende dem Runbook perfekt und sind trotzdem überrascht.
Claude Code für Dokumentationsdrift funktioniert am besten, wenn du Docs wie Code behandelst: schlage einen kleinen, überprüfbaren Patch vor und erkläre, warum. Statt zu bitten, „das README zu aktualisieren“, fordere es auf, einen Diff gegen konkrete Dateien zu generieren. Reviewer sehen klar Vorher/Nachher und erkennen unbeabsichtigte Änderungen schneller.
Eine gute Drift‑Prüfung liefert zwei Dinge:
Wenn du promptest, verlange Beweise aus dem Repo: Dateipfade und Details wie Routen, Config‑Werte oder Tests, die das aktuelle Verhalten belegen.
Hier ein Prompt‑Muster, das auf dem Boden bleibt:
Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.
Wenn Claude sagt „die API nutzt /v2“, soll das durch den Router, das OpenAPI‑Spec oder einen Integrationstest belegt werden. Kann es keinen Beleg finden, muss es das sagen.
Drift beginnt meist mit einer Codeänderung, die mehrere Docs still beeinflusst. Lass Claude zuerst den Impact scopen: Was hat sich geändert, wo hat es sich geändert, welche Docs sind wahrscheinlich betroffen und welche Nutzeraktionen sind betroffen.
Beispiel: Du benennst eine Umgebungsvariable von API_KEY zu SERVICE_TOKEN. Ein nützlicher Bericht findet jede Stelle, an der der alte Name auftaucht (README‑Setup, API‑Beispiele, Runbook‑Secrets‑Abschnitt) und erzeugt einen engen Diff, der nur diese Zeilen und Beispielbefehle aktualisiert, die sonst fehlschlagen würden.
Wenn du ein Modell auf „alle Docs“ ohne Regeln loslässt, bekommst du oft umgeschriebene Texte, die trotzdem falsche Fakten enthalten. Ein einfacher Workflow hält Änderungen klein, wiederholbar und leicht zu prüfen.
Fang mit einem Doc‑Set an: dem README, der API‑Referenz oder einem Runbook, das tatsächlich genutzt wird. Ein Bereich durchgängig zu reparieren lehrt dich, welchen Signalen du trauen kannst, bevor du skalierst.
Schreibe in klaren Worten auf, wo Fakten für dieses Doc‑Set herkommen sollten.
Wenn du diese Quellen benannt hast, werden Prompts präziser: „Vergleiche das README mit der aktuellen CLI‑Ausgabe und den Config‑Defaults, dann generiere einen Patch."
Stimme ein Ausgabeformat ab, bevor jemand die erste Prüfung laufen lässt. Gemischte Formate erschweren das Erkennen von Änderungen und Gründen.
Eine einfache Regel:
Eine praktische Gewohnheit: Füge jeder Doc‑PR eine kleine Notiz wie „Source of truth checked: routes + tests“ hinzu, damit Reviewer wissen, womit verglichen wurde. Das wandelt Doc‑Updates von „sieht gut aus“ zu „gegen etwas Echtes verifiziert“.
Behandle jede Codeänderung als kleine Dokumentationsuntersuchung. Ziel ist, Widersprüche früh zu finden und einen minimalen Patch zu liefern, dem Reviewer vertrauen können.
Wähle zuerst die genauen Dateien und eine klare Drift‑Frage. Zum Beispiel: „Haben wir Umgebungsvariablen, CLI‑Flags, HTTP‑Routen oder Fehlercodes geändert, die die Docs noch erwähnen?“ Je spezifischer, desto weniger neigt das Modell dazu, ganze Abschnitte umzuschreiben.
Lass Claude Code zuerst harte Fakten aus dem Code extrahieren. Bitte um eine Liste konkreter Items: Befehle, die Nutzer ausführen, Endpoints und Methoden, Request‑ und Response‑Felder, Config‑Keys, erforderliche Umgebungsvariablen und operationale Schritte, die durch Skripte oder Konfigurationen referenziert werden. Wenn etwas nicht im Code zu finden ist, soll es „not found“ melden statt zu raten.
Fordere dann eine einfache Vergleichstabelle an: Doc‑Aussage, was der Code zeigt und ein Status (match, mismatch, missing, unclear). Das hält die Diskussion sachlich.
Danach: einen Unified‑Diff mit minimalen Änderungen. Sag ihm, nur die Zeilen zu ändern, die nötig sind, den Stil des Dokuments beizubehalten und keine Versprechen hinzuzufügen, die nicht durch Code belegt sind.
Beende mit einer kurzen Reviewer‑Zusammenfassung: Was wurde geändert, warum wurde es geändert und worauf besonders zu prüfen ist (z. B. eine umbenannte Umgebungsvariable oder ein neuer Pflicht‑Header).
API‑Docs driften, wenn sich der Code still ändert: eine Route wird umbenannt, ein Feld wird Pflicht oder das Fehlerformat ändert sich. Das resultiert in kaputten Client‑Integrationen und verlorener Debugging‑Zeit.
Mit Claude Code ist die Aufgabe, aus dem Repo zu beweisen, was die API tut, und dann auf Abweichungen in den Docs hinzuweisen. Bitte das Modell, ein Inventar aus Routing und Handlern zu extrahieren (Pfade, Methoden, Request‑ und Response‑Modelle) und das mit dem API‑Referenztext zu vergleichen.
Konzentriere dich auf das, was Leute tatsächlich kopieren: curl‑Befehle, Header, Beispiel‑Payloads, Statuscodes und Feldnamen. In einem Prompt lass es prüfen:
Wenn ein Mismatch gefunden wird, akzeptiere nur Diffs, die Belege aus dem Code zitieren (exakte Routen‑Definition, Handler‑Verhalten oder Schema). So bleiben Patches klein und überprüfbar.
Beispiel: Der Code liefert jetzt 201 für POST /widgets und fordert ein Pflichtfeld name. Die Docs zeigen noch 200 und lassen name weg. Eine gute Ausgabe benennt beide Widersprüche und aktualisiert nur Statuscode und Beispiel‑JSON dieses Endpoints, der Rest bleibt unberührt.
Runbooks scheitern am teuersten: Sie wirken vollständig, passen aber nicht mehr zur aktuellen Systemrealität. Eine kleine Änderung wie ein umbenannter Env‑Var oder ein neuer Deploy‑Befehl kann ein Incident‑Response stark verzögern.
Behandle Runbooks wie Code: fordere einen Diff gegen das aktuelle Repo und verlange Widerspruchs‑Callouts. Vergleiche sie mit dem, was das System aktuell nutzt: Skripte, Config‑Defaults und dein aktuelles Tooling.
Fokussiere dich auf die Fehlerpunkte, die bei Incidents am meisten Chaos verursachen:
Füge außerdem schnelle Prechecks und erwartete Outputs hinzu, damit Antwortende sofort sehen, ob sie auf dem richtigen Weg sind. „Verify it works“ reicht nicht; nenne das genaue Signal (eine Statuszeile, ein Version‑String oder eine Health‑Check‑Antwort).
Wenn du Apps auf Plattformen wie Koder.ai (koder.ai) baust und deployst, ist das noch wichtiger, weil Snapshots und Rollback nur nützlich sind, wenn das Runbook die richtige Aktion nennt und den aktuellen Recovery‑Pfad widerspiegelt.
Der schnellste Weg, Dokumentationsdrift zu erzeugen, ist, Docs als „schöne Prosa“ zu behandeln statt als eine Sammlung von Behauptungen, die mit dem Code übereinstimmen müssen.
Ein häufiger Fehler ist, zuerst um eine Umschreibung zu bitten. Wenn du die Widerspruchsprüfung auslässt, erhältst du möglicherweise glattere Texte, die immer noch falsches Verhalten beschreiben. Starte immer mit der Frage: Was behaupten die Docs, was zeigt der Code, und wo widersprechen sie sich?
Ein anderer Fehler ist, das Modell raten zu lassen. Wenn ein Verhalten nicht im Code, in Tests oder in Konfigurationen sichtbar ist, behandle es als unbekannt. „Wahrscheinlich“ ist die Quelle für erfundene README‑Versprechen und für Runbooks, die zur Fiktion werden.
Diese Probleme tauchen oft bei Alltagsupdates auf:
Ein Handler ändert das Verhalten von 401 zu 403 für abgelaufene Tokens, und der Headername wechselt von X‑Token zu Authorization. Wenn du nur den Auth‑Abschnitt umschreibst, übersiehst du vielleicht, dass das API‑Beispiel noch den alten Header zeigt und das Runbook On‑Call nach 401‑Spikes suchen lässt.
Wenn du Diffs erzeugst, füge eine kurze Entscheidungszeile hinzu wie: „Auth‑Fehler liefern nun 403, um ungültige vs. fehlende Anmeldeinformationen zu unterscheiden.“ Das verhindert, dass die nächste Person die Docs „versehentlich“ zurück auf das alte Verhalten ändert.
Behandle jedes Doc‑Update wie ein kleines Audit. Ziel: weniger Überraschungen, wenn jemand die Anweisungen nächste Woche ausführt.
Bevor du merge, scanne README, API‑Docs und Runbooks nach konkreten Aussagen und verifiziere sie einzeln:
Wenn du zwei oder mehr unbekannte Aussagen in demselben Doc findest, halte den Merge an. Entweder füge Belege hinzu (Dateipfade und Funktionsnamen) oder kürze das Dokument auf das, was sicher ist.
Ein kleines Team ändert Auth: Statt einen API‑Key in X‑API‑Key zu senden, schicken Clients jetzt einen kurzlebigen Token in Authorization: Bearer <token>. Der Code wird ausgeliefert, Tests grün, und das Team macht weiter.
Zwei Tage später folgt ein neuer Entwickler dem README. Es steht noch „set X‑API‑Key in deiner Umgebung“ und zeigt ein curl‑Beispiel mit dem alten Header. Er bekommt lokal nichts zum Laufen und denkt, der Service sei down.
Unterdessen sind die API‑Docs auch veraltet. Sie beschreiben den alten Header und zeigen weiterhin ein Antwortfeld user_id, obwohl die API jetzt userId zurückgibt. An der Ausdrucksweise ist nichts falsch, aber sie widerspricht dem Code, sodass Leser das Falsche kopieren.
Dann passiert ein Incident. On‑Call folgt dem Runbook‑Schritt „rotate the API key and restart workers“. Das hilft nicht, weil das tatsächliche Problem Token‑Verifikation nach einer Konfigurationsänderung ist. Das Runbook schickt sie 20 Minuten in die falsche Richtung.
Hier ist Claude Code für Dokumentationsdrift nützlich, wenn es Diffs und Widerspruchs‑Callouts produziert, nicht eine komplette Umschreibung. Du kannst es bitten, die Auth‑Middleware und Route‑Handler gegen README‑Snippets, API‑Beispiele und Runbook‑Schritte zu vergleichen und minimale Patches vorzuschlagen:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
Wichtig ist, dass es die Abweichungen kennzeichnet, die genauen Stellen nennt und nur das ändert, was das Repo als veraltet belegt.
Dokumentation bleibt dann akkurat, wenn das Prüfen langweilig und wiederholbar ist. Wähle eine Kadenz passend zum Risiko deiner Änderungen. Bei schnell sich änderndem Code: bei jedem PR. Für stabile Services reicht oft ein wöchentlicher Sweep plus ein Pre‑Release‑Check.
Behandle Doc‑Drift wie einen Testfehler, nicht als Schreibaufgabe. Nutze Claude Code, um einen kleinen Diff und eine kurze Liste von Widersprüchen zu erzeugen, und korrigiere dann nur das Nötigste, damit die Docs wieder stimmen.
Eine leichte Routine:
Mach diese Diff‑Zusammenfassungen später leicht auffindbar. Ein kurzer Hinweis wie „Docs updated to match new /v2 endpoint, removed deprecated header, updated example response“ hilft, wenn Monate später jemand fragt, warum ein Doc geändert wurde.
Wende „Snapshots and rollback“-Denken auch auf Docs an. Wenn eine Anweisung unsicher ist, ändere sie an einer Stelle, verifiziere kurz und kopiere die bestätigte Version anschließend an andere Orte.
Wenn du schnell entwickelst, kann es helfen, die App und eine erste Version ihrer Docs zusammen in Koder.ai (koder.ai) zu generieren und dann den Quellcode zu exportieren und Änderungen wie gewohnt im Repo‑Workflow überprüfbar zu halten. Das Ziel ist nicht perfekte Prosa, sondern dass das, was Menschen tun (Befehle, Endpoints, Schritte), mit dem übereinstimmt, was der Code tatsächlich macht.
Documentation drift bedeutet, dass deine Dokumentation nach und nach nicht mehr dem entspricht, was der Code tatsächlich tut. Meistens fängt es mit kleinen Änderungen an (ein umbenanntes Env-Var, ein neu erforderliches Feld, ein anderer Statuscode), die nie in README, API‑Beispielen oder Runbooks nachgezogen werden.
Weil Code unter Zeitdruck geändert wird, während Dokumentation nicht die gleiche Durchsetzung erfährt.
Häufige Ursachen:
Beginne mit den Dokumenten, die Leute tatsächlich ausführen, nicht mit denen, die „schön zu haben“ sind. Praktische Reihenfolge:
Diese zuerst zu fixen entfernt die kostenintensivsten Fehler.
Weil geschliffene Formulierungen trotzdem falsch sein können. Drift betrifft meist inkorrekte Aussagen.
Besser ist es, Docs als überprüfbare Aussagen zu behandeln: „Führe diesen Befehl aus“, „rufe diesen Endpoint auf“, „setze diese Variable“ — und diese Aussagen gegen das aktuelle Repo, Konfigurationen und reale Outputs zu prüfen.
Fordere zwei Ausgaben an:
Außerdem: Wenn es keinen Beleg im Repo findet, muss es „not found“ sagen statt zu raten.
Weil Reviewer Diffs schnell prüfen können. Ein Diff zeigt genau, was sich geändert hat, und verhindert „hilfreiche“ Umschreibungen, die neue Versprechen einführen.
Guter Default: möglichst eine Datei pro Diff, und jede Änderung bekommt einen Einzeiler mit dem Grund, der an Repo‑Beweise gebunden ist.
Erzwinge Quellenbelege.
Praktische Regeln:
Prüfe die Teile, die Leute kopieren:
Wenn die Endpunktliste stimmt, aber Beispiele falsch sind, scheitern Nutzer trotzdem — deshalb sind Beispiele hohe Priorität.
Runbooks driften, wenn sich die operative Realität ändert.
Wichtige Prüfungen:
Wenn Responder ihren Fortschritt nicht verifizieren können, verlieren sie Zeit in Incidents.
Nutze eine einfache „Source of truth“-Regel pro Dokumenttyp:
Dann in den Workflow einbauen: Führe Drift‑Checks an betroffenen Docs pro PR aus und halte Änderungen klein und reviewbar.