Claude Code gegen Dokumentationsdrift: Dokumentation mit dem Code in Einklang halten

Was Dokumentationsdrift ist (und warum sie immer wieder passiert)

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:

• Onboarding scheitert (Neue verlieren Tage mit Setup‑Problemen).
• Deploys schlagen fehl (Schritte passen nicht zur aktuellen Konfiguration).
• Support‑Aufwand steigt (Nutzer folgen veralteten Anweisungen).
• Incidents ziehen sich hin (Runbooks schicken die Antwortenden in die falsche Richtung).

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.

Wo Drift auftritt: README, API‑Docs und Runbooks

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.

README: der erste Ort, an dem Nutzer Schmerzen spüren

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: falsche Shapes und irreführende Beispiele

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:

• Beispiel‑Payloads enthalten Felder, die der Server nicht mehr akzeptiert.
• Antwortmuster zeigen alte Fehlerformate oder Statuscodes.
• Parametertabellen nennen Felder optional, die jetzt Pflicht sind.
• Auth‑Notes erwähnen Header oder Scopes, die nicht mehr funktionieren.
• Pagination-, Sortier‑ oder Filterregeln stimmen nicht mit der Realität überein.

Runbooks: leiser Drift, der laute Incidents verursacht

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.

Wie man Claude Code nutzt: Diffs und Widerspruchs‑Callouts

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:

1. Einen minimalen Diff
2. Einen Widerspruchsbericht, der klar und spezifisch ist: „Doc sagt X, Repo zeigt Y."

Fordere Belege, keine Meinungen

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.

Umfang vor dem Editieren abstecken

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.

Richte vor dem Prompten einen einfachen Workflow ein

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.

Entscheide, was als Quelle der Wahrheit zählt

Schreibe in klaren Worten auf, wo Fakten für dieses Doc‑Set herkommen sollten.

• Für ein README: CLI‑Help‑Output und eine funktionierende Beispiel‑App.
• Für API‑Docs: Router‑Definitionen plus Integrationstests.
• Für Runbooks: Deploy‑Config und die Alerts, die das Verfahren auslösen.

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."

Wähle ein Format, das Reviewer schnell validieren können

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:

• Für jede Doc‑Änderung ein Diff verlangen, plus einen einzeiligen Grund.
• Erlaube eine kurze Widerspruchsliste nur, wenn das Tool keine sichere Formulierung vorschlagen kann.
• Halte Diffs möglichst auf eine Datei pro Änderung begrenzt.
• Behandle fehlschlagende Beispiele (Befehle, Requests, Code‑Snippets) als höherwertig als allgemeine Formulierungen.

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“.

Schritt für Schritt: Docs bei jeder Änderung mit dem Code abgleichen

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: praktisch prüfen von Endpoints und Beispielen

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:

• Auth‑Anforderungen (Header, Token‑Typ, öffentliche Endpoints)
• Pagination‑Parameter und Defaults
• Fehler‑Statuscodes und JSON‑Format
• Versionierungsverhalten (v1 vs v2)
• Ob Beispiele zu aktuellen Validierungsregeln passen

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: Ausfälle vermeiden, die durch veraltete Abläufe entstehen

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:

• Stimmen die gelisteten Befehle mit aktuellen Skripten und Flags überein?\n- Stimmen die „Default“‑Konfigwerte mit dem überein, was die App ausliefert?\n- Werden benötigte Env‑Vars und Secrets im Code und in der Deploy‑Config referenziert?\n- Stimmen Deploy‑ und Rollback‑Schritte mit eurem Release‑Tooling und den Namenskonventionen überein?\n- Stimmen „known good“‑Werte (Ports, Regionen, Timeouts) noch mit der Realität überein?

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.

Häufige Fehler, die Drift verschlimmern

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.

Fehler, die heimlich die Ausrichtung zerstören

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:

• Einen Abschnitt updaten, aber Beispiele, Fehlermeldungen und Edgecases unverändert lassen
• Ein Konzept an einer Stelle umbenennen (README), aber nicht in API‑Docs, Config‑Keys oder Runbooks
• Endpunktbeschreibungen aktualisieren, aber Request‑/Response‑Beispiele vergessen
• Verhalten ändern, aber Defaults oder Hinweise zu Limits nicht anpassen
• Doc‑Edits mergen, ohne einen kurzen „Warum wurde das geändert?“‑Hinweis im Diff‑Summary zu hinterlassen

Ein kleines Beispiel

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.

Schnelle Checkliste vor dem Merge von Doc‑Updates

Behandle jedes Doc‑Update wie ein kleines Audit. Ziel: weniger Überraschungen, wenn jemand die Anweisungen nächste Woche ausführt.

Fünf Checks, die die meisten Driftfälle erwischen

Bevor du merge, scanne README, API‑Docs und Runbooks nach konkreten Aussagen und verifiziere sie einzeln:

• Markiere jede Aussage, die einen Befehl, Endpoint, Config‑Key, Env‑Var, Port oder ein Beispielpayload enthält.
• Notiere für jede Aussage die exakte Datei, die sie belegt (Source, Config, Schema, Migration, Test oder CLI‑Help). Wenn du keinen Beleg findest, markiere es als unknown statt zu raten.
• Fordere nur dort einen minimalen Diff an, wo Beweis existiert. Ist eine Aussage unbekannt, sollte die Änderung zu einer Frage oder einem TODO werden, nicht zu einer sicheren Behauptung.
• Sanity‑Check für Beispiele: Stimmen die Inputs noch mit dem überein, was der Code akzeptiert (Parameter‑Namen, Pflichtfelder, Header, Default‑Werte)? Lange Beispiele sind Drift‑Magnete.
• Bei Runbooks: Bestätige, dass die Schritte wahrscheinliche Fehler, sicheres Rollback und wie die Wiederherstellung verifiziert wird, abdecken.

Eine Stop‑Regel

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.

Beispiel‑Szenario: eine Feature‑Änderung, drei drehende Docs

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.

Nächste Schritte: Drift‑Checks zur Routine machen

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:

• Pro PR: Führe einen Drift‑Check auf den Dateien aus, die die Änderung betreffen (README, API‑Docs, Runbooks).
• Speichere die Diff‑Zusammenfassung in der PR‑Beschreibung oder in den Review‑Notizen, damit Reviewer sehen, was sich warum geändert hat.
• Bevorzuge kleine, leicht revertierbare Änderungen statt großer Umschreibungen.
• Vor Releases: überprüfe alles, was Nutzer kopieren werden (curl‑Beispiele, Env‑Vars, Deployment‑Schritte).
• Wöchentlich: nehme ein oder zwei ältere Runbooks und bestätige, dass sie noch zu aktuellen Befehlen und Dashboards passen.

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.