Dowiedz się, jak używać Claude Code do wykrywania dryfu dokumentacji i utrzymywania README, dokumentacji API i runbooków zgodnych z kodem, generując dify i wskazując sprzeczności.
Dryf dokumentacji to stopniowe rozchodzenie się tego, co opisuje dokumentacja, z tym, co faktycznie robi kod. Zaczyna się od drobnych niezgodności, które potem zamieniają się w „przecież to działało miesiąc temu” i zamieszanie.
W prawdziwym zespole dryf wygląda tak: README mówi, że usługę uruchomisz jednym poleceniem, a tymczasem potrzebna jest nowa zmienna środowiskowa. Dokumentacja API pokazuje endpoint z polem, które zostało przemianowane. Runbook mówi on-call, żeby zrestartować „worker-a”, a proces został rozdzielony na dwie usługi.
Dryf pojawia się nawet przy dobrych intencjach, bo kod zmienia się szybciej niż nawyki dokumentacyjne. Ludzie wypuszczają poprawki pod presją, kopiują stare przykłady lub zakładają, że ktoś inny zaktualizuje dokumenty później. Rosną też problemy, gdy masz zbyt wiele miejsc wyglądających jak „źródło prawdy”: pliki README, referencje API, wewnętrzne wiki, tickety i wiedza plemienna.
Koszty są konkretne:
Poprawianie stylu pisania nie rozwiąże dryfu, jeśli fakty są nieprawdziwe. Pomaga traktowanie dokumentów jak czegoś, co można zweryfikować: porównaj je z aktualnym kodem, konfiguracjami i rzeczywistymi wynikami, a potem wytykaj sprzeczności tam, gdzie dokumentacja obiecuje zachowanie, którego kod już nie ma.
Dryf zwykle pokazuje się w dokumentach, które ludzie traktują jako „szybką referencję”. Są aktualizowane raz, a potem kod nadal się porusza. Zacznij od tych trzech, bo zawierają konkretne obietnice, które możesz sprawdzić.
README dryfują, gdy zmieniają się codzienne polecenia. Pojawia się nowy flag, stary znika, albo zmienia się nazwa zmiennej środowiskowej, a sekcja setup dalej pokazuje starą rzeczywistość. Nowi współpracownicy kopiują instrukcje, napotykają błędy i myślą, że projekt jest zepsuty.
Najgorsza wersja to „prawie dobrze”. Jedna brakująca zmienna środowiskowa może zmarnować więcej czasu niż całkowicie przestarzałe README, bo ludzie będą próbować małych wariacji zamiast zakwestionować dokument.
Dokumentacja API dryfuje, gdy zmieniają się pola requestów lub response’ów. Nawet drobne przesunięcia (zmienione klucze, inne wartości domyślne, nowe wymagane nagłówki) mogą zepsuć klientów. Często lista endpointów jest poprawna, a przykłady nie — i to właśnie kopiują użytkownicy.
Typowe sygnały:
Runbooki dryfują, gdy zmieniają się kroki deploymentu, rollbacku lub operacyjne. Jedno przestarzałe polecenie, zła nazwa usługi lub brakujący prerequisite może zmienić rutynową naprawę w przestój.
Mogą też być „dokładne, ale niepełne”: kroki nadal działają, ale pomijają nową migrację, czyszczenie cache’a albo toggle flagi. Wtedy responderzy stosują się do runbooka idealnie, a i tak się dziwią.
Claude Code do dryfu dokumentacji działa najlepiej, gdy traktujesz dokumenty jak kod: proponuj mały, możliwy do review patch i wyjaśnij dlaczego. Zamiast prosić „zaktualizuj README”, poproś o wygenerowanie diffu względem konkretnych plików. Reviewowi otrzymują jasne before/after i mogą szybko wychwycić niezamierzone zmiany.
Dobry check dryfu daje dwa rezultaty:
Kiedy formułujesz prompt, wymagaj dowodów z repo: ścieżki plików i szczegóły jak trasy, wartości konfiguracji czy testy, które pokazują aktualne zachowanie.
Oto wzorzec promptu, który trzyma wszystko przy ziemi:
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.
Jeśli Claude stwierdzi „API używa /v2”, niech to poprze wskazaniem routera, specyfikacji OpenAPI lub testu integracyjnego. Jeśli nie znajdzie dowodu, powinien to napisać.
Dryf zwykle zaczyna się od jednej zmiany w kodzie, która cicho wpływa na wiele dokumentów. Najpierw miej Claude’a ocenę wpływu: co się zmieniło, gdzie się zmieniło, które dokumenty prawdopodobnie zostały naruszone i jakie akcje użytkowników to dotyczy.
Przykład: zmieniasz nazwę zmiennej środowiskowej z API_KEY na SERVICE_TOKEN. Przydatny raport znajdzie każde wystąpienie starej nazwy (sekcja setup w README, przykłady API, sekcja sekretów w runbooku), a potem wygeneruje wąski diff, który aktualizuje tylko te linie i przykładowe polecenia, które teraz zawiodą.
Jeśli wskażesz modelowi „wszystkie dokumenty” bez zasad, często otrzymasz przeredagowany tekst, który dalej zawiera złe fakty. Prosty workflow utrzymuje zmiany małe, powtarzalne i łatwe do review.
Zacznij od jednego zestawu dokumentów: README, referencja API lub jeden runbook, którego ludzie faktycznie używają. Naprawienie jednego obszaru end-to-end nauczy cię, jakich sygnałów możesz ufać przed skalowaniem.
Zapisz, w prostych słowach, skąd powinny pochodzić fakty dla tego zestawu dokumentów.
Kiedy już nazwiesz te źródła, prompty stają się ostrzejsze: „Porównaj README z aktualnym outputem CLI i domyślnymi wartościami konfiguracji, potem wygeneruj patch.”
Uzgodnij format wyjścia zanim ktoś uruchomi pierwszy check. Mieszanie formatów utrudnia zobaczenie, co się zmieniło i dlaczego.
Proste zasady:
W praktyce: dodaj krótką notkę do każdego PR z dokumentacją: „Source of truth checked: routes + tests”, żeby reviewerzy wiedzieli, co porównano. To zmienia aktualizacje dokumentów z „wygląda ok” na „zweryfikowano względem czegoś rzeczywistego”.
Traktuj każdą zmianę w kodzie jak małe śledztwo dokumentacyjne. Chodzi o wychwycenie sprzeczności wcześnie i wygenerowanie minimalnego patcha, któremu reviewer zaufa.
Zacznij od wyboru dokładnych plików do sprawdzenia i jasnego pytania o dryf. Na przykład: „Czy zmieniliśmy jakieś zmienne środowiskowe, flagi CLI, trasy HTTP lub kody błędów, o których dalej wspomina dokumentacja?” Bycie konkretnym trzyma model od przeredagowywania całych sekcji.
Następnie poproś Claude Code o wyciągnięcie twardych faktów z kodu najpierw. Poproś go, żeby wypisał tylko konkretne elementy: polecenia, które użytkownicy wykonują, endpointy i metody, pola request/response, klucze konfiguracji, wymagane zmienne środowiskowe oraz kroki operacyjne referowane przez skrypty lub configi. Jeśli czegoś nie ma w kodzie, ma napisać „not found” zamiast zgadywać.
Potem poproś o prostą tabelę porównawczą: twierdzenie w dokumencie, co pokazuje kod i status (match, mismatch, missing, unclear). To utrzymuje dyskusję przy ziemi.
Następnie poproś o unified diff z minimalnymi zmianami. Powiedz, żeby zmieniał tylko linie potrzebne do rozwiązania niezgodności, zachował styl dokumentu i unikał dodawania obietnic, których kod nie potwierdza.
Na koniec krótka podsumowanie dla reviewera: co się zmieniło, dlaczego się zmieniło i co sprawdzić dodatkowo (np. zmieniona nazwa zmiennej środowiskowej lub nowy wymagany nagłówek).
Dokumentacja API dryfuje, gdy kod cicho się zmienia: trasa zostaje przemianowana, pole staje się wymagane lub kształt błędu się zmienia. Efekt to zepsute integracje i stracony czas na debugowanie.
Z Claude Code twoim zadaniem jest udowodnić, co API robi na podstawie repo, a potem wskazać niezgodności w dokumentach. Poproś go o wyciągnięcie inwentarza z routera i handlerów (ścieżki, metody, modele request/response) i porównanie tego z tym, co twierdzi referencja API.
Skoncentruj się na tym, co ludzie faktycznie kopiują: polecenia curl, nagłówki, przykładowe payloady, kody statusu i nazwy pól. W jednym promptcie niech sprawdzi:
Gdy znajdzie niezgodność, przyjmuj tylko dify, które potrafią wskazać dowód w kodzie (dokładna definicja trasy, zachowanie handlera lub schemat). To utrzymuje patche małe i możliwe do review.
Przykład: kod teraz zwraca 201 na POST /widgets i dodaje wymagane pole name. Dokumentacja dalej pokazuje 200 i pomija name. Dobry output wskaże obie sprzeczności i zaktualizuje tylko status i przykładowy JSON tego endpointu.
Runbooki zawodzą w najdroższy sposób: wyglądają kompletnie, ale kroki nie zgadzają się z tym, jak system działa dziś. Mała zmiana, jak przemianowanie zmiennej środowiskowej lub nowe polecenie deployu, może wydłużyć incydent, bo responderzy wykonują instrukcje, które nie zadziałają.
Traktuj runbook jak kod: poproś o diff względem aktualnego repo i wymagaj raportu sprzeczności. Porównaj go z tym, czego system używa teraz: skrypty, domyślne konfiguracje i aktualne narzędzia.
Skup się na punktach awarii, które powodują najwięcej zamieszania podczas incydentów:
Dodaj też szybkie prechecki i oczekiwane wyniki, żeby responderzy mogli stwierdzić, czy idą w dobrym kierunku. „Zweryfikuj, że działa” to za mało; podaj dokładny sygnał, np. linię statusu, string wersji lub odpowiedź health checka.
Jeśli budujesz i deployujesz aplikacje na platformach jak Koder.ai, to ma jeszcze większe znaczenie, bo snapshoty i rollback działają tylko wtedy, gdy runbook nazwie poprawną akcję i odzwierciedla aktualną ścieżkę recovery.
Najszybsza droga do stworzenia dryfu to traktowanie dokumentów jako „ładnej prozy” zamiast zestawu twierdzeń, które muszą zgadzać się z kodem.
Częstym potknięciem jest proszenie o przepisanie najpierw. Kiedy pomijasz sprawdzenie sprzeczności, możesz otrzymać ładniejszą wersję, która dalej opisuje złe zachowanie. Zawsze zaczynaj od tego, co dokument twierdzi, co robi kod i gdzie się nie zgadzają.
Inny błąd to pozwalanie modelowi na zgadywanie. Jeśli zachowanie nie jest widoczne w kodzie, testach lub konfiguracji, traktuj je jako nieznane. „Prawdopodobnie” to sposób, w jaki README nabiera obietnic, a runbooki stają się fikcją.
Te problemy pojawiają się często przy codziennych aktualizacjach:
Handler zmienia zachowanie: wcześniej zwracał 401, teraz 403 dla przeterminowanych tokenów, a nazwa nagłówka zmienia się z X-Token na Authorization. Jeśli tylko przepiszesz sekcję auth, możesz nie zauważyć, że przykład w dokumentacji API dalej pokazuje stary nagłówek, a runbook nadal mówi on-call, żeby szukać skoków 401.
Gdy generujesz dify, dodaj krótką decyzję: „Auth failures teraz zwracają 403, by rozróżnić nieprawidłowe vs brakujące poświadczenia.” To zapobiega temu, by ktoś później „naprawił” dokumenty z powrotem do starego zachowania.
Traktuj każdą aktualizację dokumentu jak maudit. Celem jest mniej niespodzianek, gdy ktoś wykona instrukcję w przyszłym tygodniu.
Zanim naciśniesz merge, przeskanuj README, dokumentację API i runbook pod kątem konkretnych twierdzeń i weryfikuj je po kolei:
Jeśli znajdziesz w jednym dokumencie dwie lub więcej nieznane tezy, zatrzymaj merge. Albo dodaj dowody (ścieżki plików i nazwy funkcji), albo przytnij dokument do tego, co jest pewne.
Mały zespół aktualizuje auth: zamiast wysyłać klucz API w X-API-Key, klienci teraz przesyłają krótkotrwały token w Authorization: Bearer <token>. Kod shipuje, testy przechodzą i zespół idzie dalej.
Po dwóch dniach nowy deweloper podąża za README. Nadal mówi „ustaw X-API-Key w środowisku” i pokazuje przykład curl ze starym nagłówkiem. Nie udaje mu się uruchomić lokalnie i myśli, że serwis nie działa.
Równocześnie dokumentacja API jest przestarzała. Opisuje stary nagłówek i dalej pokazuje pole user_id, choć API teraz zwraca userId. Nic nie jest nie tak ze stylem pisania, ale dokumenty przeczą kodowi, więc czytelnicy kopiują złe rzeczy.
Potem pojawia się incydent. On-call wykonuje krok z runbooka „rotate the API key and restart workers”. To nie pomaga, bo rzeczywisty problem to weryfikacja tokena po zmianie konfiguracji. Runbook prowadzi ich w złym kierunku przez 20 minut.
Tu Claude Code do dryfu dokumentacji jest przydatny, gdy generuje dify i raporty sprzeczności, a nie pełny rewrit. Możesz poprosić go, by porównał middleware auth i handlery tras z fragmentami README, przykładami API i krokami w runbooku, a potem zaproponował minimalne patche:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
Ważne jest, żeby wskazał niezgodności, podał dokładne miejsca i zmienił tylko to, co repo dowodzi jako przestarzałe.
Dokumentacja pozostaje poprawna, gdy sprawdzanie jej jest nudne i powtarzalne. Wybierz tempo, które odpowiada, jak ryzykowne są twoje zmiany. Dla szybko zmieniającego się kodu — przy każdym PR. Dla stabilnych usług — tygodniowe sprawdzenie + check przed wydaniem zwykle wystarczy.
Traktuj dryf dokumentów jak błąd testowy, a nie zadanie pisarskie. Użyj Claude Code do generowania małego diffu i krótkiej listy sprzeczności, a potem napraw najmniejszą rzecz, która przywraca dokumenty do prawdy.
Lekki rutynowy proces:
Ułatwiaj odnalezienie podsumowań diffów później. Krótka notka typu „Docs updated to match new /v2 endpoint, removed deprecated header, updated example response” pomaga, gdy ktoś za kilka miesięcy zapyta, dlaczego dokument się zmienił.
Zastosuj myślenie „snapshotów i rollbacku” do dokumentów. Jeśli instrukcja jest niepewna, zmień ją w jednym miejscu, szybko zweryfikuj, a potem skopiuj potwierdzoną wersję w inne miejsca.
Jeśli budujesz szybko, pomocne może być wygenerowanie aplikacji i pierwszej wersji dokumentów razem w Koder.ai (koder.ai), a potem eksport kodu i trzymanie zmian w normalnym workflow repozytorium. Celem nie jest perfekcyjny styl, lecz zgodność tego, co ludzie robią (polecenia, endpointy, kroki) z tym, co faktycznie robi kod.
Dryf dokumentacji to sytuacja, gdy twoja dokumentacja stopniowo przestaje odpowiadać temu, co robi kod. Zwykle zaczyna się od drobnych zmian (zmieniona zmienna środowiskowa, nowe wymagane pole, inny kod statusu), które nigdy nie trafiają do README, przykładów API ani runbooków.
Bo kod zmienia się pod presją, a dokumentacja nie ma takiego samego wymuszenia.
Typowe przyczyny:
Zacznij od dokumentów, które ludzie faktycznie wykonują, nie od tych „miłych do posiadania”. Praktyczna kolejność:
Naprawa tych elementów najpierw usuwa największe koszty błędów.
Bo ładne przekształcenie tekstu nie sprawi, że twierdzenia będą poprawne. Dryf dotyczy przede wszystkim nieprawidłowych twierdzeń.
Lepsze podejście to traktować dokumentację jak zestaw testowalnych stwierdzeń: „uruchom to polecenie”, „wywołaj ten endpoint”, „ustaw tę zmienną”, a następnie weryfikować te twierdzenia względem repozytorium, konfiguracji i rzeczywistych wyników.
Poproś o dwa wyniki:
Wymagaj też: jeśli nie znajdzie dowodu w repo, ma napisać „not found” zamiast zgadywać.
Bo diff jest szybki do weryfikacji przez reviewera. Pokazuje dokładnie, co się zmieniło, i ogranicza „pomocne” przeredagowania wprowadzające nowe obietnice.
Dobry domyślny zestaw zasad: jedna zmiana na plik, gdy to możliwe, i jednozdaniowe uzasadnienie powiązane z dowodem w repo.
Wymagaj cytowania dowodów.
Praktyczne zasady:
Sprawdź to, co ludzie kopiują:
Jeśli lista endpointów jest poprawna, a przykłady nie, użytkownicy i tak zawiodą — traktuj przykłady jako priorytet.
Runbooki driftują, gdy rzeczywistość operacyjna się zmienia.
Wysokowpływowe kontrole:
Jeśli responderzy nie mogą weryfikować postępu, stracą czas podczas incydentu.
Użyj prostej reguły „źródła prawdy” dla typu dokumentu:
Następnie wpisz to w workflow: uruchamiaj checki dryfu dla dotkniętych dokumentów przy każdym PR i utrzymuj małe, łatwe do review poprawki.