AI do tworzenia i utrzymania dokumentacji technicznej

Dokumentacja techniczna w firmie SaaS starzeje się szybciej niż kod. Runbook napisany przy wdrożeniu v2 opisuje procedury, które przy v4 są już inne. Wiki onboardingowe z maja mówi o endpointach, które w lipcu zmieniły parametry. Nowy inżynier spędza pierwsze dni na weryfikowaniu, czy to, co czyta, jest wciąż prawdą.

My w Cashcrown badamy, jak asystent oparty na RAG może skrócić dystans między kodem a dokumentacją, nie eliminując przy tym roli człowieka jako ostatniego weryfikatora. Ten artykuł opisuje wzorzec drafowania z kodu, problem dryfu dokumentacji i granicę, której żaden automat nie powinien przekraczać.

Klasyczne podejście do automatycznego generowania dokumentacji opiera się na instruowaniu modelu języka słowami w stylu „opisz ten endpoint". Model odpowiada na podstawie wiedzy ogólnej zakodowanej w wagach. Wynik jest poprawny gramatycznie i całkowicie niepewny faktycznie, bo model może nigdy nie widział Waszego API.

Wzorzec, który badamy, jest odwrócony: asystent dostaje pytanie lub zadanie drafowania, retrieval wyciąga trafne fragmenty z zaindeksowanego kodu i istniejącej dokumentacji, a LLM formułuje projekt dokumentu wyłącznie na ich podstawie. Każde zdanie jest powiązane z konkretnym fragmentem źródłowym.

Praktyczne implikacje dla indeksowania:

Guardrail w warstwie generowania blokuje jedno: jeśli retrieval nie zwrócił fragmentu z podobieństwem powyżej progu (orientacyjnie 0,65 dla wyszukiwania semantycznego), asystent nie drafuje nic. Zamiast tego odpowiada wprost: „nie znalazłem pokrycia w zaindeksowanej wersji źródła". Opis parametru, którego nie ma w OpenAPI, nie trafi do draftu.

Więcej o strategiach indeksowania kodu opisuje artykuł o RAG dla kodu i dokumentacji technicznej.

Wygenerowanie pierwszej wersji dokumentacji to rozwiązalny problem. Utrzymanie jej aktualności po sześciu miesiącach intensywnego developmentu to problem, który większość zespołów rozwiązuje przez... nieaktualizowanie dokumentów.

Dryf ma konkretny mechanizm: endpoint zmienia parametr w code review, nikt nie aktualizuje wiki. Za miesiąc nowy programista traci dwie godziny na debugowanie błędu, który w aktualnej dokumentacji wyglądałby jak konfiguracja. Skala dryfu rośnie liniowo z liczbą mikrousług i odwrotnie z dyscypliną aktualizowania.

Trzy warstwy, które stosujemy w podejściu do tego problemu:

Reindeksacja przyrostowa po commicie. Webhook z GitLab lub GitHub (hak post-receive) wyzwala reindeksację zmienionych plików. git diff --name-only HEAD~1 HEAD daje listę. Asystent wie, że ten plik był zmodyfikowany po ostatnim drafcie i może flagować powiązaną sekcję dokumentacji jako wymagającą przeglądu.

Metadane świeżości w każdej odpowiedzi. Każdy chunk w indeksie przechowuje last_commit_sha i datę indeksacji. Asystent ujawnia je w cytacie: „źródło: src/payments/refund.py, linia 43, commit b2f1a09, indeksowano 3 godziny temu". Programista widzi, czy może ufać odpowiedzi, zanim ją zastosuje.

TTL dla dokumentów bez webhooka. Runbooki w Confluence lub Notion nie wysyłają zdarzeń po edycji. Ustawiamy TTL reindeksacji: 24 godziny dla aktywnie zmieniającej się dokumentacji, 7-14 dni dla stabilnych specyfikacji architektonicznych. Po przekroczeniu TTL asystent dodaje ostrzeżenie o potencjalnej nieaktualności.

Człowiek decyduje o progu TTL dla każdej kategorii dokumentów. To nie jest konfiguracja techniczna; to decyzja o ryzyku, którą podejmuje inżynier lub tech lead odpowiedzialny za dany obszar.

Asystent nie decyduje samodzielnie, że sekcja dokumentacji jest nieaktualna i ją nadpisuje. To byłoby niezgodne z zasadą human-oversight. Wykrywanie dryfu działa inaczej: asystent flaguje, człowiek ocenia.

Konkretny wzorzec detekcji dryfu:

Przy każdym zapytaniu o fragment dokumentacji asystent porównuje datę ostatniej modyfikacji strony wiki z datą ostatniego commitu w powiązanym pliku kodu. Jeśli commit jest nowszy o więcej niż zdefiniowany próg (np. 48 godzin), asystent dołącza do odpowiedzi adnotację: „źródło kodu zmienione 3 dni po ostatniej aktualizacji tej sekcji dokumentacji. Zalecam weryfikację przed zastosowaniem".

Dla bardziej zaawansowanego podejścia, agent może generować cykliczny raport: lista sekcji dokumentacji, których powiązane pliki kodu zmieniły się od ostatniego przeglądu, posortowana według liczby zmian. Tech lead przegląda listę co sprint i deleguje aktualizacje konkretnym osobom.

Co jest twardą granicą: asystent nigdy nie publikuje zmiany w dokumentacji bez zatwierdzenia przez człowieka. Proponuje edycje, drafuje zmiany do przeglądu, pokazuje diff między tym, co jest w wiki, a tym, co wynika z aktualnego kodu. Decyzja o przyjęciu draftu należy do właściciela dokumentacji.

Szczegółowe omówienie wzorca pracy asystenta na długich dokumentach opisuje artykuł o podsumowywaniu długich dokumentów.

Halucynacja w dokumentacji technicznej ma wyższe koszty niż w większości innych zastosowań. Opis parametru, który nie istnieje w API, doprowadzi programistę do błędu integracji. Runbook z fikcyjną komendą sprawi, że operacja w środku nocy zakończy się incydentem.

Dlatego każdy fragment dokumentacji generowany przez asystenta musi mieć ślad cytowania: skąd pochodzi, który commit, kiedy był zaindeksowany. Format wewnętrzny, którego używamy:

[draft ze źródła: src/payments/refund.ts, linia 67-89, commit a3f9c12, indeksowano 2026-06-18 08:41]

Ten ślad pojawia się w narzędziu do przeglądu dokumentacji, nie w opublikowanym artykule. Recenzent widzi, skąd pochodzi każde zdanie i może w jednym kliknięciu przejść do źródłowego pliku w repozytorium. Jeśli kod od tamtej chwili się zmienił, widzi to przed zatwierdzeniem.

Guardrails blokujące structured output powinny egzekwować obecność cytowania w każdym drafcie. Jeśli model próbuje wygenerować opis parametru bez powiązanego fragmentu z retrieval, generacja jest odrzucana. Lepszy jest pusty draft niż draft z wymyślonym parametrem.

Wzorzec firmowego asystenta opartego na RAG opisuje artykuł firmowy GPT na bazie wiedzy.

Przy każdym wdrożeniu asystenta do tworzenia dokumentacji powtarzamy tę samą rozmowę z zespołem: co asystent robi, a co należy do inżyniera.

Asystent drafuje na podstawie kodu. Inżynier ocenia, czy draft oddaje intencję architektoniczną, a nie tylko mechanikę kodu. Te dwie rzeczy są różne.

Asystent flaguje sekcje, których powiązany kod się zmienił. Inżynier ocenia, czy zmiana w kodzie faktycznie wpływa na semantykę dokumentowanego zachowania. Często nie wpływa; refaktoring nazwy zmiennej nie zmienia API.

Asystent generuje szkielet runbooka z procedur w kodzie. Inżynier uzupełnia o wiedzę operacyjną, której nie ma w kodzie: co sprawdzić jako pierwsze o 3 w nocy, kiedy dzwonić do DBA, jakich błędów NIE naprawiać bez konsultacji. Ta wiedza żyje w głowach ludzi, nie w plikach źródłowych.

Granica, której nie przekracza żaden automat: decyzja o publikacji. Żaden draft nie trafia do oficjalnej dokumentacji bez zatwierdzenia przez osobę odpowiedzialną za dany obszar. To wymóg operacyjny, nie tylko etyczny. Dobra praktyka przygotowania danych pod AI jest opisana w artykule jak przygotować dane firmowe pod AI.

Nie powinien, przynajmniej nie bez etapu przeglądu. Asystent może automatycznie generować draft zmiany i tworzyć pull request do dokumentacji z powiązanym commitem kodu. Ale przyjęcie tego draftu wymaga zatwierdzenia przez inżyniera odpowiedzialnego za dany obszar. Automatyczne nadpisywanie wiki bez przeglądu to realne ryzyko: refaktoring wewnętrzny, który nie zmienia publicznego zachowania, może wygenerować mylące zmiany dokumentacji.

To jeden z najczęstszych problemów przy RAG nad dokumentacją techniczną. Retrieval zwróci kilka fragmentów i model może próbować je połączyć, co może prowadzić do sprzecznych opisów. Wzorzec, który rekomendujemy: przed wdrożeniem asystenta przeprowadź audyt bazy wiedzy i oznacz jedno źródło prawdy dla każdego endpointu. Duplikaty oznacz jako deprecated z odesłaniem do kanonicznego źródła. Asystent indeksuje tylko kanoniczne źródło.

Dwa wskaźniki, które mają sens operacyjny: odsetek draftów zaakceptowanych bez zmian przez recenzenta (cel: powyżej 50 procent po pierwszym miesiącu kalibracji) i czas przeglądu draftu przez inżyniera (cel: poniżej 15 minut dla typowej sekcji). Niski odsetek akceptacji sygnalizuje problem z jakością indeksu lub z promptem systemowym. Długi czas przeglądu sygnalizuje zbyt duże drafty lub zbyt mało konkretne cytowanie źródeł.

To sygnał, że guardrail cytowania nie działa poprawnie. Prawidłowo skonfigurowany asystent nie powinien generować opisu bez pokrycia w indeksie. Jeśli tak się dzieje, sprawdź dwa miejsca: czy guardrail sprawdza obecność cytatu w każdym drafcie, i czy próg podobieństwa retrieval nie jest zbyt niski (dopuszczane są zbyt słabe dopasowania). Opis parametru, który nie istnieje w źródle, jest objawem braku guardrails, nie słabości modelu.

Może drafować szkielety dokumentów onboardingowych z kodu i istniejących procedur. W praktyce onboarding wymaga wiedzy, której nie ma w żadnym pliku: niepisanych konwencji zespołu, historycznych decyzji architektonicznych, miejsc, które są kruche i wiadomo tylko „starym" członkom zespołu. Asystent skraca czas przygotowania dokumentu o kilkadziesiąt procent, ale ostateczna wersja zawsze wymaga wkładu inżyniera z doświadczeniem w danym obszarze.