Lär dig använda Claude Code för dokumentationsdrift för att hålla READMEs, API-dokument och runbooks i linje med koden genom att generera diffar och flagga motsägelser.
Dokumentationsdrift är den långsamma glidningen mellan vad dina dokument säger och vad din kod faktiskt gör. Det börjar som små avvikelser och blir sedan till förvirring i stil med "vi svär att det fungerade förra månaden".
I ett verkligt team ser drift ut så här: README säger att du kan köra en tjänst med ett kommando, men en ny miljövariabel krävs nu. API-dokumenten visar en endpoint med ett fält som har bytt namn. En runbook instruerar on-call att starta om "worker-a", men processen är nu uppdelad i två tjänster.
Drift sker även med goda avsikter eftersom mjukvaran ändras snabbare än dokumentationsvanor. Folk levererar fixar under tidspress, kopierar gamla exempel eller antar att någon annan uppdaterar dokumenten senare. Det växer också när du har för många platser som ser ut som "sanningskällan": README-filer, API-referenser, interna wiki-sidor, tickets och tribal knowledge.
Kostnaderna är konkreta:
Att polera texten löser inte drift om fakta är fel. Det som hjälper är att behandla dokument som något du kan verifiera: jämför dem med aktuell kod, konfigurationer och verkliga utslag, och peka ut motsägelser där dokumenten lovar beteenden som koden inte längre har.
Drift visar sig oftast i dokument som folk behandlar som "snabbreferens". De uppdateras en gång och sedan rör sig koden vidare. Börja med dessa tre eftersom de innehåller konkreta löften du kan kontrollera.
READMEs drifts när vardagliga kommandon ändras. En ny flagga läggs till, en gammal tas bort, eller en miljövariabel byter namn, men setup-avsnittet visar fortfarande den gamla verkligheten. Nya kollegor kopierar och klistrar in instruktioner, stöter på fel och antar att projektet är trasigt.
Den värsta varianten är "nästan rätt". En saknad miljövariabel kan slösa mer tid än en helt föråldrad README, eftersom folk fortsätter prova små varianter istället för att ifrågasätta dokumentet.
API-dokument drifts när request- eller response-fält ändras. Även små skiftningar (omdöpta nycklar, andra standardvärden, nya obligatoriska headers) kan bryta klienter. Ofta är endpoint-listan korrekt medan exemplen är fel — och det är exakt vad användare kopierar.
Typiska signaler:
Runbooks drifts när deploy-, rollback- eller operativa steg ändras. Ett föråldrat kommando, felaktigt tjänstenamn eller saknat förutsättningssteg kan förvandla en rutinåtgärd till driftstopp.
De kan också vara "korrekta men ofullständiga": stegen fungerar fortfarande, men de hoppar över en ny migration, en cache-rensning eller en feature-flag-toggling. Då följer responders runbooken perfekt och blir ändå förvånade.
Claude Code för dokumentationsdrift fungerar bäst när du behandlar dokument som kod: föreslå ett litet, granskningsbart patch och förklara varför. Istället för att be den "uppdatera README", be den generera en diff mot specifika filer. Granskare får ett tydligt före/efter och kan snabbt upptäcka oavsiktliga ändringar.
En bra driftkontroll producerar två saker:
När du promptar, kräva bevis från repot: filvägar och detaljer som routes, konfigvärden eller tester som visar aktuellt beteende.
Här är ett promptmönster som håller det grundat:
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.
Om Claude säger "API:t använder /v2", låt den backa upp det genom att peka på routern, OpenAPI-specen eller ett integrationstest. Om den inte kan hitta bevis ska den säga det.
Drift börjar ofta med en kodändring som tyst påverkar flera dokument. Låt Claude först avgränsa påverkan: vad ändrades, var ändrades det, vilka dokument sannolikt bryts och vilka användarhandlingar påverkas.
Exempel: du byter namn på en miljövariabel från API_KEY till SERVICE_TOKEN. En användbar rapport hittar varje ställe det gamla namnet förekommer (README setup, API-exempel, runbook-sektionen om secrets), och producerar sedan en snäv diff som bara uppdaterar de raderna och eventuella exempelkommandon som nu skulle misslyckas.
Om du pekar en modell mot "alla dokument" utan regler får du ofta omskrivningar som fortfarande innehåller felaktiga fakta. Ett enkelt arbetsflöde håller ändringar små, repetitiva och lätta att granska.
Börja med en dokumentsats: README, API-referensen eller en runbook som folk faktiskt använder. Att fixa ett område från början till slut lär dig vilka signaler du kan lita på innan du skalar upp.
Skriv ner, med enkla ord, var fakta ska komma ifrån för den dokumentsatsen.
När du har namngivit dessa källor blir prompts skarpare: "Jämför README med aktuell CLI-hjälp och konfigstandarder, och generera en patch."
Kom överens om ett utdataformat innan någon kör första kontrollen. Blandade format gör det svårare att se vad som ändrats och varför.
En enkel regelsamling:
En praktisk vana: lägg till en liten not i varje doc-PR som "Source of truth checked: routes + tests" så granskare vet vad som jämfördes. Det förvandlar dokumentuppdateringar från "ser bra ut" till "verifierat mot något verkligt".
Behandla varje kodändring som en liten dokumentundersökning. Poängen är att fånga motsägelser tidigt och producera en minimal patch som granskare kan lita på.
Börja med att välja exakt vilka filer som ska kontrolleras och en tydlig driftfråga. Till exempel: "Har vi ändrat några miljövariabler, CLI-flaggor, HTTP-routes eller felkoder som dokumenten fortfarande nämner?" Att vara specifik hindrar modellen från att skriva om hela sektioner.
Be sedan Claude Code extrahera hårda fakta från koden först. Be den lista konkreta objekt endast: kommandon användare kör, endpoints och metoder, request- och response-fält, konfignycklar, obligatoriska miljövariabler och operativa steg som refereras av skript eller konfigfiler. Om något inte finns i koden ska den säga "not found" istället för att gissa.
Be därefter om en enkel jämförelsetabell: dokumentpåstående, vad koden visar, och en status (match, mismatch, missing, unclear). Det håller diskussionen grundad.
Efter det, begär en unified diff med minimala ändringar. Säga åt den att ändra endast de rader som behövs för att lösa mismatcharna, behåll dokumentets befintliga stil och undvik att lägga till löften som inte stöds av koden.
Avsluta med en kort sammanfattning för granskaren: vad som ändrades, varför det ändrades och vad som bör dubbelkollas (t.ex. omdöpt miljövariabel eller ny obligatorisk header).
API-dokument drifts när koden tyst ändras: en route byter namn, ett fält blir obligatoriskt eller ett felformat ändras. Resultatet är brutna klientintegrationer och bortkastad debuggtid.
Med Claude Code för dokumentationsdrift är uppgiften att bevisa vad API:t faktiskt gör utifrån repot, och sedan peka ut mismatch i dokumentationen. Be den extrahera ett inventarium från routing och handlers (paths, metoder, request- och response-modeller) och jämföra det med vad API-referensen påstår.
Fokusera på vad folk faktiskt kopierar: curl-kommandon, headers, exempelpayloads, statuskoder och fältnamn. I en enda prompt, låt den kontrollera:
När den hittar en mismatch, acceptera bara diffs där den kan citera bevis från koden (exakt route-definition, handlerbeteende eller schema). Det håller patcherna små och möjliga att granska.
Exempel: koden returnerar nu 201 på POST /widgets och lägger till ett obligatoriskt fält name. Dokumenten visar fortfarande 200 och utelämnar name. Ett bra utdata påpekar båda kontradiktionerna och uppdaterar bara den endpointens statuskod och exempel-JSON, resten lämnas orört.
Runbooks misslyckas på det mest kostsamma sättet: de ser kompletta ut men stegen matchar inte vad systemet gör idag. En liten ändring som ett omdöpt env-var eller ett nytt deploy-kommando kan förlänga en incident eftersom responders följer instruktioner som inte fungerar.
Behandla runbooken som kod: be om en diff mot aktuellt repo och kräv kontradiktioner. Jämför med vad systemet faktiskt använder nu: skript, konfigstandarder och ditt nuvarande verktyg.
Fokusera på felpunkter som orsakar mest fram- och tillbaka under incidenter:
Lägg också till snabba förkontroller och förväntade utslag så responders kan se om de är på rätt väg. "Verifiera att det fungerar" räcker inte; inkludera den exakta signal du väntar dig (en statusrad, en versionssträng eller ett health-check-svar).
Om du bygger och deployar appar på plattformar som Koder.ai, spelar detta ännu större roll eftersom snapshots och rollback bara är användbara när runbooken namnger rätt åtgärd och reflekterar den faktiska återställningsvägen.
Det snabbaste sättet att skapa dokumentationsdrift är att behandla dokument som "fint skrivna" istället för en uppsättning påståenden som måste matcha koden.
Ett vanligt misstag är att be om omskrivning först. När du hoppar över kontradiktionstest kan du få en smidigare text som fortfarande beskriver fel beteende. Börja alltid med att fråga vad dokumentet påstår, vad koden gör och var de inte stämmer.
Ett annat misstag är att låta modellen gissa. Om ett beteende inte syns i kod, tester eller konfigurationer ska det behandlas som okänt. "Förmodligen" är hur README-löften uppfinns och hur runbooks blir fiktion.
Dessa problem visar sig ofta i vardagsuppdateringar:
En handler ändrar från att returnera 401 till 403 för utgångna token, och headernamnet byts från X-Token till Authorization. Om du bara skriver om auth-sektionen kan du missa att API-dokexemplet fortfarande visar den gamla headern, och runbooken fortfarande säger åt on-call att titta efter 401-toppar.
När du genererar diffs, lägg till en kort beslutsrad som: "Auth-fel returnerar nu 403 för att skilja ogiltiga från saknade referenser." Det förhindrar att nästa person "fixar" tillbaka dokumenten till det gamla beteendet.
Behandla varje dokumentuppdatering som en liten revision. Målet är färre överraskningar när någon följer instruktionerna nästa vecka.
Innan du trycker merge, skanna README, API-dokument och runbook efter konkreta påståenden och verifiera dem en efter en:\n\n- Markera varje påstående som innehåller ett kommando, endpoint, konfignyckel, miljövariabel, port eller exempelpayload.\n- För varje påstående, notera exakt fil som bevisar det (källa, config, schema, migration, test eller CLI-hjälputdata). Om du inte snabbt hittar bevis, markera det som okänt istället för att gissa.\n- Be om en minimal diff endast där bevis finns. Om ett påstående är okänt bör ändringen bli en fråga eller en TODO, inte ett säkert uttalande.\n- Sanity-checka exempel: matchar ingångarna fortfarande vad koden accepterar idag (parameternamn, obligatoriska fält, headers, standardvärden)? Långa exempel är driftmagneter.\n- För runbooks, bekräfta att stegen täcker sannolika fel, säker rollback och hur man verifierar återhämtning.
Om du hittar två eller fler okända påståenden i samma dokument, pausa mergningen. Antingen lägg till bevis (filvägar och funktionsnamn) eller trimma dokumentet tillbaka till det som är säkert.
Ett litet team uppdaterar auth: istället för att skicka en API-nyckel som X-API-Key skickar klienter nu en kortlivad token som Authorization: Bearer <token>. Koden släpps, tester passerar och teamet går vidare.
Två dagar senare följer en ny utvecklare README. Den säger fortfarande "sätt X-API-Key i din miljö" och visar ett curl-exempel med den gamla headern. De får inte igång en lokal körning och antar att tjänsten är nere.
Samtidigt är API-dokumenten också föråldrade. De beskriver den gamla headern och visar fortfarande ett svarsfält som heter user_id, trots att API:t nu returnerar userId. Inget är fel med formuleringen, men det motsäger koden, så läsare kopierar fel.
Sedan inträffar en incident. On-call följer runbook-steget "rotatera API-nyckeln och starta om workers". Det hjälper inte eftersom verkligt problem är tokenverifiering som misslyckas efter en konfigändring. Runbooken leder dem åt fel håll i 20 minuter.
Här är Claude Code för dokumentationsdrift användbart när det producerar diffs och kontradiktioner, inte en full omskrivning. Du kan be den jämföra auth-middleware och route-handlers mot README-snuttar, API-exempel och runbook-steg, och sedan föreslå minimala patcher:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
Det viktiga är att den flaggar mismatcherna, pekar på exakt var de finns och bara ändrar det som repot bevisar är föråldrat.
Dokumentation håller sig korrekt när kontrollen är tråkig och repetitiv. Välj en takt som matchar hur riskabelt era ändringar är. För snabbrörlig kod, gör det på varje PR. För stabila tjänster räcker ofta en veckovis svepning plus en pre-release-kontroll.
Behandla dokumentdrift som ett testfail, inte som en skrivuppgift. Använd Claude Code för dokumentationsdrift för att generera en liten diff och en kort lista med kontradiktioner, och åtgärda sedan det minsta som gör dokumenten sanna igen.
Ett lättviktigt rutinförslag:
Gör diffsammanfattningarna lätta att hitta senare. En kort not som "Dokument uppdaterade för att matcha nya /v2-endpoint, tagit bort deprecated header, uppdaterat exempelrespons" hjälper när någon undrar varför ett dokument ändrades månader senare.
Tillämpa tänkandet "snapshots och rollback" på dokument också. Om en instruktion är osäker, ändra den på ett ställe, verifiera snabbt, och kopiera sedan den bekräftade versionen någon annanstans.
Om du bygger snabbt kan det hjälpa att generera appen och en första uppsättning dokument tillsammans i Koder.ai (koder.ai), exportera källkoden och hålla ändringar granskbara i din vanliga workflow. Målet är inte perfekt prosa. Målet är att hålla vad människor gör (kommandon, endpoints, steg) i linje med vad koden faktiskt gör.
Dokumentationsdrift är när dina dokument långsamt slutar stämma överens med vad koden faktiskt gör. Det börjar ofta med små förändringar (en omdöpt miljövariabel, ett nytt obligatoriskt fält, en annan statuskod) som aldrig reflekteras i README, API-exempel eller runbooks.
För att koden ändras under press men dokumentationen inte får samma efterlevnad.\n\nVanliga orsaker:\n\n- Folk levererar fixar och antar att “någon uppdaterar dokumentationen senare.”\n- Exempel kopieras vidare även efter att beteendet förändrats.\n- Det finns för många “sanningskällor” (README, wiki, tickets, gamla runbooks).
Börja med de dokument som människor faktiskt kör efter, inte de som är “bra att ha”. En praktisk ordning är:\n\n1) README: setup och körkommandon (onboarding-problem)\n2) API-dokumentation: exempel (bryter integrationer)\n3) Runbooks (risk för incidenter)\n\nAtt fixa dessa först tar bort de mest kostsamma felen.
För att snyggare text fortfarande kan vara felaktig. Drift handlar mest om felaktiga påståenden.\n\nEtt bättre tillvägagångssätt är att behandla dokument som testbara uttalanden: “kör det här kommandot”, “anropa denna endpoint”, “sätt denna variabel” — och sedan verifiera dessa påståenden mot nuvarande repo, konfigurationer och verkliga utslag.
Be om två utdata:\n\n- En lista med kontradiktioner: dokumentpåstående → repo-bevis (med filvägar och radintervall)\n- En minimal unified diff: minsta säkra ändringar för att få dokumentet korrekt igen\n\nKräv också: om den inte hittar bevis i repot ska den säga “not found” istället för att gissa.
För att granskare kan validera snabbare. En diff visar exakt vad som ändrats och minskar “hjälpsamma” omskrivningar som inför nya påståenden.\n\nEn bra standard: en fil per diff när möjligt, och varje ändring får en enradig anledning kopplad till repo-bevis.
Kräv att den citerar bevis.\n\nPraktiska regler:\n\n- Varje påstående måste backas upp av en repokälla (router, tester, konfigurationsstandard, CLI-hjälp).\n- Om bevis saknas ska utdata markeras unclear eller unknown.\n- Föredra att ändra dokumentet för att matcha verifierat beteende, inte “vad som verkar rimligt”.
Kontrollera det användare brukar kopiera in:\n\n- Headers och auth-format (token-typ, nödvändiga scopes)\n- Exempel på request/response JSON (fält, obligatoriska fält)\n- Statuskoder och felformat\n- Pagination/filterstandarder\n- Versionering (v1 vs v2)\n\nOm listan över endpoints är korrekt men exemplen är fel, misslyckas användare fortfarande—så behandla exempel som hög prioritet.
Runbooks drifts när den operativa verkligheten förändras.\n\nHögriskkontroller:\n\n- Kommandon och flaggor matchar nuvarande skript/verktyg\n- Tjänstenamn matchar vad som faktiskt körs idag\n- Obligatoriska env-vars/secret matchar deploy-config och kod\n- Rollback-steg matchar nuvarande releasprocess\n- Varje steg inkluderar en snabb verifieringssignal (förväntat utslag, health-check)\n\nOm responder inte kan verifiera framsteg slösar de tid under incidenter.
Använd en enkel “sanningskälla”-regel per dokumenttyp:\n\n- README: aktuell CLI-hjälp + en fungerande setup-väg\n- API-dokument: routerdefinitioner + integrationstester\n- Runbooks: deploy-konfig + skript + de alerts som triggar proceduren\n\nBaka sedan in det i workflow: kör driftkontroller på berörda dokument per PR och håll ändringarna små och läsbara.