26 dec 2025·7 min
Claude Code voor documentatiedrift: houd docs in lijn
Leer Claude Code voor documentatiedrift om READMEs, API-docs en runbooks in lijn te houden met de code door diffs te genereren en tegenstrijdigheden te signaleren.
Leer Claude Code voor documentatiedrift om READMEs, API-docs en runbooks in lijn te houden met de code door diffs te genereren en tegenstrijdigheden te signaleren.
Documentatiedrift is de langzame scheiding tussen wat je docs zeggen en wat je code daadwerkelijk doet. Het begint als kleine onjuistheden en groeit uit tot verwarring van het type "we zweren dat dit vorige maand werkte".
In een echte teamsetting ziet drift er zo uit: de README zegt dat je een service met één commando kunt draaien, maar er is nu een nieuwe environment-variabele nodig. De API-docs tonen een endpoint met een veld dat is hernoemd. Een runbook vertelt on-call om "worker-a" te herstarten, maar het proces is nu opgesplitst in twee services.
Drift gebeurt zelfs met goede intenties omdat software sneller verandert dan documentatiegewoonten. Mensen shippen fixes onder druk, kopiëren oude voorbeelden of gaan ervan uit dat iemand anders de docs later bijwerkt. Het groeit ook als je te veel plekken hebt die als "bron van waarheid" lijken: README-bestanden, API-referenties, interne wiki-pagina's, tickets en mondelinge kennis.
De kosten zijn concreet:
Het mooier maken van de tekst lost drift niet op als de feiten onjuist zijn. Wat helpt is docs behandelen als iets dat je kunt verifiëren: vergelijk ze met de huidige code, config en echte outputs, en wijs contradicties aan waar de docs gedrag beloven dat de code niet meer heeft.
Drift verschijnt meestal in documenten die mensen als "snel naslagwerk" gebruiken. Ze worden één keer bijgewerkt en daarna beweegt de code door. Begin met deze drie omdat ze concrete beloften bevatten die je kunt controleren.
READMEs drijven af wanneer dagelijkse commando's veranderen. Er komt een nieuwe flag bij, een oude gaat weg, of een environment-variabele wordt hernoemd, maar de setup-sectie toont nog de oude werkelijkheid. Nieuwe teamgenoten copy-pasten instructies, lopen tegen fouten aan en denken dat het project kapot is.
De ergste versie is "bijna goed". Eén ontbrekende environment-variabele kan meer tijd kosten dan een volledig verouderde README, omdat mensen kleine variaties blijven proberen in plaats van het document in twijfel te trekken.
API-docs drijven af wanneer request- of response-velden veranderen. Zelfs kleine verschuivingen (hernoemde keys, andere defaults, nieuwe verplichte headers) kunnen clients breken. Vaak klopt de lijst met endpoints, maar zijn de voorbeelden fout, en precies die voorbeelden kopiëren gebruikers.
Typische signalen:
Runbooks drijven af wanneer deployment-, rollback- of operationele stappen veranderen. Eén verouderd commando, verkeerde servicenaam of ontbrekende prerequisite kan een routinefix in downtime veranderen.
Ze kunnen ook "accuraat maar incompleet" zijn: de stappen werken nog, maar ze slaan een nieuwe migratie, cache-clear of feature-flag toggle over. Dat is wanneer responders het runbook perfect volgen en toch verrast worden.
Claude Code voor documentatiedrift werkt het best als je docs als code behandelt: stel een kleine, reviewbare patch voor en leg uit waarom. In plaats van te vragen om "de README bij te werken", vraag je het een diff te genereren tegen specifieke bestanden. Reviewers krijgen een duidelijk voor/na en kunnen snel ongewenste veranderingen spotten.
Een goede drift-check levert twee dingen op:
Wanneer je prompt, eis bewijs uit de repo: bestandslocaties en details zoals routes, configwaarden of tests die het huidige gedrag aantonen.
Hier is een promptpatroon dat het gegrond houdt:
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.
Als Claude zegt "the API uses /v2", laat het dat onderbouwen met de router, OpenAPI-spec of een integratietest. Als het geen bewijs kan vinden, moet het dat zeggen.
Drift begint meestal met één codewijziging die meerdere docs stilletjes beïnvloedt. Laat Claude eerst de impact afbakenen: wat is er veranderd, waar is het veranderd, welke docs breekt het waarschijnlijk en welke gebruikersacties worden geraakt.
Voorbeeld: je hernoemt een environment-variabele van API_KEY naar SERVICE_TOKEN. Een nuttig rapport vindt elke plek waar de oude naam voorkomt (README setup, API-voorbeelden, runbook secrets-sectie) en produceert een strakke diff die alleen die regels en voorbeeldcommando's bijwerkt die nu zouden falen.
Als je een model op "alle docs" richt zonder regels, krijg je vaak herschreven proza dat nog steeds onjuiste feiten bevat. Een eenvoudige workflow houdt wijzigingen klein, herhaalbaar en makkelijk te reviewen.
Begin met één set documenten: de README, de API-reference, of één runbook dat mensen echt gebruiken. Het volledig oplossen van één gebied leert je welke signalen je kunt vertrouwen voordat je opschaalt.
Schrijf in gewone woorden op waar feiten vandaan moeten komen voor die docset.
Zodra je die bronnen hebt benoemd, worden prompts scherper: "Vergelijk de README met de huidige CLI-output en config-defaults en genereer dan een patch."
Stem van tevoren af welk outputformaat je gebruikt. Mixen van formats maakt het moeilijker om te zien wat veranderde en waarom.
Een eenvoudige regelsuite:
Een praktische gewoonte: voeg een klein notitie toe aan elke doc-PR zoals "Source of truth checked: routes + tests" zodat reviewers weten wat vergeleken is. Dat verandert doc-updates van "ziet er goed uit" naar "geverifieerd tegen iets reëels".
Behandel elke codewijziging als een kleine doc-onderzoek. Het doel is vroeg contradicties te vangen en een minimale patch te produceren die reviewers kunnen vertrouwen.
Begin met het kiezen van de exacte bestanden om te controleren en een duidelijke driftvraag. Bijvoorbeeld: "Hebben we environment-variabelen, CLI-flags, HTTP-routes of errorcodes veranderd die de docs nog steeds noemen?" Specifiek zijn houdt het model tegen om hele secties te herschrijven.
Vervolgens laat je Claude Code eerst harde feiten uit de code halen. Vraag het concrete items op te sommen: commando's die gebruikers draaien, endpoints en methodes, request- en response-velden, config-keys, verplichte environment-variabelen en operationele stappen die door scripts of configs genoemd worden. Als iets niet in de code te vinden is, moet het "not found" zeggen in plaats van te raden.
Vraag daarna om een simpele vergelijkingtabel: doc-claim, wat de code toont en een status (match, mismatch, missing, unclear). Dat houdt de discussie praktisch.
Daarna vraag je om een unified diff met minimale wijzigingen. Zeg dat het alleen de regels mag veranderen die nodig zijn om mismatches op te lossen, de bestaande stijl van de doc moet behouden en geen beloften mag toevoegen die niet door de code ondersteund worden.
Sluit af met een korte reviewer-samenvatting: wat is veranderd, waarom het veranderd is en wat dubbel te controleren (zoals een hernoemde environment-variabele of een nieuw vereist header).
API-docs drijven af wanneer de code stilletjes verandert: een route wordt hernoemd, een veld wordt verplicht of een error-shape verandert. Het resultaat zijn kapotte client-integraties en verloren debugtijd.
Met Claude Code voor documentatiedrift is de taak te bewijzen wat de API doet vanuit de repo en dan te wijzen op mismatches in de docs. Vraag het een inventaris te trekken uit routing en handlers (paths, methods, request- en response-modellen) en dat te vergelijken met wat de API-reference beweert.
Focus op wat mensen daadwerkelijk kopiëren: curl-commando's, headers, voorbeeldpayloads, statuscodes en veldnamen. In één prompt laat je het controleren op:
Als het een mismatch vindt, accepteer dan alleen diffs die bewijs uit de code citeren (de exacte route-definitie, handler-logica of schema). Dat houdt patches klein en reviewbaar.
Voorbeeld: de code retourneert nu 201 op POST /widgets en voegt een verplicht name-veld toe. De docs tonen nog 200 en laten name weg. Een goed resultaat noemt beide contradicties en werkt alleen dat endpoint bij: statuscode en voorbeeld-JSON, de rest blijft onaangeroerd.
Runbooks falen op de meest kostbare manier: ze lijken compleet, maar de stappen komen niet overeen met wat het systeem vandaag doet. Een kleine wijziging zoals een hernoemde env-var of een nieuw deploy-commando kan een incident rekken omdat responders instructies volgen die niet werken.
Behandel het runbook als code: vraag een diff tegen de huidige repo en eis contradictiemeldingen. Vergelijk het met wat het systeem nu gebruikt: scripts, config-defaults en je huidige tooling.
Focus op faalpunten die tijdens incidenten de meeste tijd kosten:
Voeg ook korte prechecks en verwachte outputs toe zodat responders kunnen zien of ze op de juiste weg zitten. "Verify it works" is niet genoeg; geef het exacte signaal dat je verwacht (een statusregel, een versie-string of een health check response).
Als je apps bouwt en deployed op platforms zoals Koder.ai, raakt dit nog belangrijker omdat snapshots en rollback alleen nuttig zijn wanneer het runbook de juiste actie benoemt en de huidige recovery-path reflecteert.
De snelste manier om documentatiedrift te creëren is docs behandelen als "mooie proza" in plaats van een set beweringen die met de code moeten matchen.
Een veelgemaakte fout is eerst om een rewrite te vragen. Als je contradictie-check overslaat, kun je een vloeiendere tekst krijgen die nog steeds het verkeerde gedrag beschrijft. Begin altijd met: wat beweert de doc, wat doet de code en waar verschillen ze?
Een andere fout is het model laten raden. Als gedrag niet zichtbaar is in code, tests of configs, behandel het als onbekend. "Waarschijnlijk" is hoe README-belofteën ontstaan en runbooks in fictie veranderen.
Deze problemen komen vaak voor bij dagelijkse updates:
Een handler verandert van 401 naar 403 voor verlopen tokens, en de headernaam schakelt van X-Token naar Authorization. Als je alleen de auth-sectie herschrijft, kun je missen dat het API-voorbeeld nog de oude header toont en het runbook on-call nog steeds naar 401 spikes laat kijken.
Wanneer je diffs genereert, voeg een korte beslisregel toe zoals: "Auth failures now return 403 to distinguish invalid vs missing credentials." Dat voorkomt dat de volgende persoon de docs terugzet naar het oude gedrag.
Behandel elke doc-update als een kleine audit. Het doel is minder verrassingen wanneer iemand de instructies volgende week opvolgt.
Voordat je op merge drukt, scan README, API-docs en runbooks op concrete claims en verifieer ze één voor één:
Als je twee of meer onbekende claims in hetzelfde document vindt, pauzeer de merge. Voeg bewijs toe (bestandslocaties en functienamen) of trim de doc terug naar wat zeker is.
Een klein team past auth aan: in plaats van een API-key in X-API-Key te sturen, sturen clients nu een kortlevend token in Authorization: Bearer <token>. De code gaat live, tests slagen en het team gaat verder.
Twee dagen later volgt een nieuwe ontwikkelaar de README. Die zegt nog steeds "zet X-API-Key in je omgeving" en toont een curl-voorbeeld met de oude header. Ze krijgen de lokale run niet werkend en denken dat de service down is.
Intussen zijn de API-docs ook verouderd. Ze beschrijven de oude header en tonen nog een response-veld user_id, terwijl de API nu userId terugstuurt. Niets mis met de schrijfkunst, maar het staat haaks op de code, dus lezers kopiëren het verkeerde.
Dan ontstaat een incident. On-call volgt de runbook-stap "rotate the API key and restart workers". Dat helpt niet omdat het echte probleem token-verificatie is na een config-wijziging. Het runbook stuurt ze 20 minuten de verkeerde kant op.
Hier is waar Claude Code voor documentatiedrift nuttig is als het diffs en contradicties produceert, niet een volledige herschrijving. Je kunt het vragen de auth-middleware en route-handlers te vergelijken met README-snippets, API-voorbeelden en runbook-stappen en dan minimale patches voorstellen:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
Het belangrijke is dat het mismatches flagt, de exacte plekken aanwijst en alleen verandert wat de repo bewijst dat verouderd is.
Documentatie blijft accuraat wanneer het controleren saai en herhaalbaar is. Kies een cadans die past bij hoe riskant je wijzigingen zijn. Voor snel bewegende code doe je het op elke PR. Voor stabiele services volstaan een wekelijkse sweep plus een pre-release check.
Behandel doc-drift als een testfout, niet als een schrijfklus. Gebruik Claude Code voor documentatiedrift om een kleine diff en een korte lijst met contradicties te genereren, en maak dan de kleinste wijziging die de docs weer waar maakt.
Een routine die licht blijft:
Maak die diff-samenvattingen later gemakkelijk vindbaar. Een korte notitie zoals "Docs updated to match new /v2 endpoint, removed deprecated header, updated example response" helpt wanneer iemand maanden later vraagt waarom een doc veranderde.
Pas ook het "snapshots and rollback"-denken toe op docs. Als een instructie onzeker is, verander die op één plek, verifieer snel en kopieer de bevestigde versie elders.
Als je snel bouwt, kan het helpen om de app en een eerste versie van de docs samen te genereren in Koder.ai (koder.ai), dan de broncode te exporteren en wijzigingen reviewbaar te houden in je normale workflow. Het doel is niet perfecte proza, maar dat wat mensen doen (commando's, endpoints, stappen) overeenkomt met wat de code daadwerkelijk doet.
Documentation drift betekent dat je documentatie langzaam niet meer overeenkomt met wat de code daadwerkelijk doet. Het begint meestal met kleine wijzigingen (een hernoemde env-var, een nieuw vereist veld, een andere statuscode) die nooit in de README, API-voorbeelden of runbooks worden bijgewerkt.
Omdat code onder druk verandert en documentatie niet dezelfde afdwinging krijgt.
Veelvoorkomende oorzaken:
Begin met de docs die mensen ook echt uitvoeren, niet de mooie extra's. Een praktische volgorde is:
Als je die eerst fixeert, elimineer je de grootste kosten.
Omdat een mooiere tekst nog steeds onjuist kan zijn. Drift gaat vooral over onjuiste claims.
Een betere aanpak is docs behandelen als testbare statements: “voer dit commando uit”, “roep deze endpoint aan”, “zet deze variabele”, en die claims verifiëren tegen de huidige repo, configuraties en outputs.
Vraag twee outputs:
Eis ook: als het bewijs niet in de repo te vinden is, moet het “not found” melden in plaats van te raden.
Omdat reviewers diffs snel kunnen valideren. Een diff toont precies wat er veranderde en ontmoedigt “behulpzame” herschrijvingen die nieuwe claims introduceren.
Een goed uitgangspunt: één bestand per diff wanneer mogelijk, en elke wijziging krijgt één zin reden gekoppeld aan repo-bewijs.
Eis dat het bewijs citeert.
Praktische regels:
Controleer wat mensen daadwerkelijk kopiëren:
Als de endpoint-lijst klopt maar voorbeelden niet, falen gebruikers alsnog—dus behandel voorbeelden als hoge prioriteit.
Runbooks drijven af wanneer operationele realiteit verandert.
Hoge-impact checks:
Zonder verificatie zullen responders tijdens incidenten tijd verspillen.
Gebruik een eenvoudige “source of truth”-regel per documenttype:
Maak het onderdeel van de workflow: voer drift-checks uit op beïnvloede docs per PR en houd wijzigingen klein en reviewbaar.