Claude Code voor documentatiedrift: houd docs in lijn

Wat documentatiedrift is (en waarom het blijft gebeuren)

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:

• Onboarding faalt (nieuwe medewerkers verliezen dagen aan setup-problemen).
• Deploys mislukken (stappen komen niet overeen met de huidige config).
• Supportlast stijgt (gebruikers volgen verouderde instructies).
• Incidenten duren langer (runbooks sturen responders de verkeerde kant op).

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.

Waar drift zich laat zien: README, API docs en runbooks

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.

README: de eerste plek waar gebruikers pijn voelen

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: mismatches in shapes en misleidende voorbeelden

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:

• Voorbeeldpayloads bevatten velden die de server niet meer accepteert.
• Responsvoorbeelden tonen oude foutformaten of statuscodes.
• Parameter-tabellen noemen velden optioneel die nu verplicht zijn.
• Auth-notities noemen headers of scopes die niet meer werken.
• Paginatie-, sorteer- of filterregels komen niet overeen met de werkelijkheid.

Runbooks: stille drift die luide incidenten veroorzaakt

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.

Hoe je Claude Code gebruikt: diffs en contradictie-meldingen

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:

1. Een minimale diff
2. Een contradictierapport dat eerlijk en specifiek is: "Doc zegt X, repo toont Y."

Vraag om bewijs, geen meningen

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.

Bepaal de scope van de wijziging voordat je verandert

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.

Zet een eenvoudige workflow op voordat je iets prompt

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.

Bepaal wat de bron van waarheid is

Schrijf in gewone woorden op waar feiten vandaan moeten komen voor die docset.

• Voor een README: CLI help output en een werkend voorbeeld-app.
• Voor API-docs: router-definities plus integratietests.
• Voor runbooks: deployment-config en de alerts die de procedure triggeren.

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

Kies een output die reviewers snel kunnen valideren

Stem van tevoren af welk outputformaat je gebruikt. Mixen van formats maakt het moeilijker om te zien wat veranderde en waarom.

Een eenvoudige regelsuite:

• Vereis een diff voor elke docwijziging, plus één-zin reden.
• Sta alleen een korte contradictielijst toe wanneer het tool niet veilig een bewoording kan voorstellen.
• Houd diffs zoveel mogelijk beperkt tot één docbestand per wijziging.
• Behandel falende voorbeelden (commando's, requests, code-snippets) als hogere prioriteit dan algemene bewoording.

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

Stapsgewijs: houd docs uitgelijnd met code bij elke wijziging

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: een praktische manier om endpoints en voorbeelden te verifiëren

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:

• Auth-vereisten (headers, token-type, publieke endpoints)
• Paginatie-params en defaults
• Foutstatuscodes en JSON-formaat
• Versiebeheer-gedrag (v1 vs v2)
• Of voorbeelden overeenkomen met huidige validatieregels

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: reduceer outages door verouderde procedures te voorkomen

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:

• Kommen de genoemde commando's overeen met huidige scripts en flags?
• Kommen de "default" configwaarden overeen met wat de app nu shipped?
• Worden vereiste env-vars en secrets door de code en deploy-config gerefereerd?
• Komen deploy- en rollback-stappen overeen met je huidige release-tooling en naamgeving?
• Kloppen "known good" waarden (poorten, regio's, timeouts) nog met de realiteit?

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.

Veelgemaakte fouten die drift erger maken

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.

Fouten die stille misalignment veroorzaken

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 sectie bijwerken maar voorbeelden, foutmeldingen en edge cases ongemoeid laten
• Een concept in één plek hernoemen (README) maar niet in API-docs, config-keys of runbooks
• Endpoint-beschrijvingen aanpassen maar request- en response-voorbeelden vergeten
• Gedrag veranderen maar defaults of beperkingen niet bijwerken
• Doc-edits mergen zonder korte "waarom dit veranderde"-notitie in de diff-samenvatting

Een klein voorbeeld

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.

Snelle checklist voordat je doc-updates samenvoegt

Behandel elke doc-update als een kleine audit. Het doel is minder verrassingen wanneer iemand de instructies volgende week opvolgt.

Vijf checks die de meeste drift vangen

Voordat je op merge drukt, scan README, API-docs en runbooks op concrete claims en verifieer ze één voor één:

• Markeer elke claim met een commando, endpoint, config-key, env-var, poort of voorbeeldpayload.
• Noteer voor elke claim het exacte bestand dat het bewijst (source, config, schema, migratie, test of CLI help output). Als je geen bewijs snel kunt vinden, markeer het als onbekend in plaats van te raden.
• Vraag alleen een minimale diff waar bewijs bestaat. Als een claim onbekend is, maak de wijziging een vraag of TODO, geen stellig statement.
• Sanity-check voorbeelden: komen de inputs nog overeen met wat de code vandaag accepteert (parameter-namen, verplichte velden, headers, defaults)? Lange voorbeelden lokken drift uit.
• Voor runbooks: bevestig dat de stappen waarschijnlijke fouten, veilige rollback en hoe herstel te verifiëren dekken.

Een korte stop-regel

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.

Voorbeeldscenario: één featurewijziging, drie documenten driften

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.

Volgende stappen: maak drift-checks routine

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:

• Per PR: voer een drift-check uit op de bestanden die de wijziging kunnen beïnvloeden (README, API docs, runbooks).
• Sla de diff-samenvatting op in je PR-omschrijving of review-notities zodat reviewers zien wat veranderde en waarom.
• Geef de voorkeur aan kleine bewerkingen die je makkelijk kunt terugdraaien boven grote herschrijvingen.
• Voor releases: hercontroleer alles wat gebruikers gaan kopiëren (curl-voorbeelden, env-vars, deploy-stappen).
• Wekelijks: test één of twee oudere runbooks en bevestig dat ze nog bij de huidige commando's en dashboards passen.

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.