Технічна документація в SaaS-компанії старіє швидше, ніж код. Ранбук, написаний під час впровадження v2, описує процедури, які у v4 вже інші. Вікі для онбордингу від травня згадує ендпоінти, параметри яких змінилися в липні. Новий інженер перші дні витрачає на перевірку, чи те, що він читає, все ще відповідає дійсності.
Ми в Cashcrown досліджуємо, як асистент на базі RAG може скоротити відстань між кодом і документацією, не усуваючи при цьому ролі людини як кінцевого верифікатора. Ця стаття описує шаблон створення чернеток з коду, проблему дрейфу документації та межу, яку жоден автомат не повинен перетинати.
Створення чернеток з коду: RAG над джерелами, а не з пам'яті моделі
#Класичний підхід до автоматичної генерації документації базується на інструктуванні мовної моделі фразами на кшталт «опиши цей ендпоінт». Модель відповідає на основі загальних знань, закодованих у вагах. Результат граматично правильний, але фактично непевний, бо модель могла ніколи не бачити вашого API.
Шаблон, який ми досліджуємо, зворотний: асистент отримує запитання або завдання на створення чернетки, retrieval витягує релевантні фрагменти з проіндексованого коду та наявної документації, а LLM формулює проєкт документа виключно на їхній основі. Кожне речення пов'язане з конкретним фрагментом джерела.
Практичні наслідки для індексації:
| Тип джерела | Що індексуємо | Обов'язкові метадані |
|---|---|---|
| Вихідний код (TS, Python, Go) | Функції, класи, методи (chunking AST) | file_path, symbol_name, start_line, last_commit_sha |
| Специфікація OpenAPI / Swagger | Один ендпоінт на chunk | method, path, version, operationId |
| Наявні ранбуки / вікі | Розділи за заголовками H2/H3 | page_url, section_title, last_modified |
| Changelog | Записи за версією | version, date, author |
Guardrail на рівні генерації блокує одне: якщо retrieval не повернув фрагмент зі схожістю вище порогу (орієнтовно 0,65 для семантичного пошуку), асистент не створює чернетку. Натомість відповідає прямо: «не знайдено покриття в проіндексованій версії джерела». Опис параметра, якого немає в OpenAPI, не потрапить до чернетки.
Детальніше про стратегії індексації коду розповідає стаття про RAG для коду та технічної документації.
Дрейф документації: чому синхронізація — більша проблема, ніж створення чернеток
Створення першої версії документації — це вирішувана проблема. Підтримка її актуальності після шести місяців інтенсивного розроблення — це проблема, яку більшість команд вирішує... не оновлюючи документи.
Дрейф має конкретний механізм: ендпоінт змінює параметр у code review, ніхто не оновлює вікі. За місяць новий програміст витрачає дві години на дебаг помилки, яка в актуальній документації виглядала б як конфігурація. Масштаб дрейфу зростає лінійно з кількістю мікросервісів і обернено пропорційно до дисципліни оновлення.
Три шари, які ми застосовуємо в підході до цієї проблеми:
Інкрементальна реіндексація після коміту. Webhook з GitLab або GitHub (хук post-receive) запускає реіндексацію змінених файлів. git diff --name-only HEAD~1 HEAD дає список. Асистент знає, що цей файл був змінений після останньої чернетки, і може позначати пов'язаний розділ документації як такий, що потребує перегляду.
Метадані свіжості в кожній відповіді. Кожен chunk в індексі зберігає last_commit_sha і дату індексації. Асистент показує їх у цитаті: «джерело: src/payments/refund.py, рядок 43, коміт b2f1a09, проіндексовано 3 години тому». Програміст бачить, чи може довіряти відповіді, перш ніж її застосувати.
TTL для документів без webhook. Ранбуки в Confluence або Notion не надсилають подій після редагування. Встановлюємо TTL реіндексації: 24 години для активно змінюваної документації, 7–14 днів для стабільних архітектурних специфікацій. Після перевищення TTL асистент додає попередження про потенційну неактуальність.
Людина вирішує поріг TTL для кожної категорії документів. Це не технічна конфігурація; це рішення про ризик, яке приймає інженер або техлід, відповідальний за певну область.
Виявлення застарілих розділів: guardrails як сигнал, а не вирок
#Асистент не вирішує самостійно, що розділ документації застарів, і не перезаписує його. Це було б суперечно принципу human-oversight. Виявлення дрейфу працює інакше: асистент позначає, людина оцінює.
Конкретний шаблон виявлення дрейфу:
При кожному запиті щодо фрагмента документації асистент порівнює дату останньої модифікації сторінки вікі з датою останнього коміту у пов'язаному файлі коду. Якщо коміт новіший за визначений поріг (наприклад, 48 годин), асистент додає до відповіді примітку: «джерело коду змінено 3 дні після останнього оновлення цього розділу документації. Рекомендую перевірити перед застосуванням».
Для більш просунутого підходу агент може генерувати періодичний звіт: список розділів документації, пов'язані файли коду яких змінилися від останнього перегляду, відсортований за кількістю змін. Техлід переглядає список кожен спринт і делегує оновлення конкретним особам.
Що є жорсткою межею: асистент ніколи не публікує зміну в документації без затвердження людиною. Пропонує правки, створює чернетки для перегляду, показує diff між тим, що є у вікі, і тим, що випливає з актуального коду. Рішення про прийняття чернетки залишається за власником документації.
Детальніше про шаблон роботи асистента з довгими документами розповідає стаття про підсумовування довгих документів.
Цитування джерел: операційна вимога, а не опція
Галюцинація в технічній документації має вищу ціну, ніж у більшості інших застосувань. Опис параметра, якого немає в API, призведе програміста до помилки інтеграції. Ранбук із вигаданою командою спричинить інцидент під час операції посеред ночі.
Тому кожен фрагмент документації, згенерований асистентом, повинен мати слід цитування: звідки походить, який коміт, коли був проіндексований. Внутрішній формат, який ми використовуємо:
[чернетка з джерела: src/payments/refund.ts, рядок 67-89, коміт a3f9c12, проіндексовано 2026-06-18 08:41]
Цей слід з'являється в інструменті для перегляду документації, а не в опублікованій статті. Рецензент бачить, звідки походить кожне речення, і може одним кліком перейти до вихідного файлу в репозиторії. Якщо код відтоді змінився, він бачить це перед затвердженням.
Guardrails, що блокують structured output, повинні забезпечувати наявність цитування в кожній чернетці. Якщо модель намагається згенерувати опис параметра без пов'язаного фрагмента з retrieval, генерація відхиляється. Краще порожня чернетка, ніж чернетка з вигаданим параметром.
Шаблон корпоративного асистента на базі RAG описує стаття корпоративний GPT на базі знань.
Роль людини: де межа жорстка
При кожному впровадженні асистента для створення документації ми повторюємо ту саму розмову з командою: що робить асистент, а що залишається за інженером.
Асистент створює чернетки на основі коду. Інженер оцінює, чи відображає чернетка архітектурний намір, а не лише механіку коду. Це дві різні речі.
Асистент позначає розділи, пов'язаний код яких змінився. Інженер оцінює, чи впливає зміна в коді на семантику документованої поведінки. Часто не впливає; рефакторинг назви змінної не змінює API.
Асистент генерує каркас ранбука з процедур у коді. Інженер доповнює оперативними знаннями, яких немає в коді: що перевірити в першу чергу о 3-й ночі, коли дзвонити до DBA, яких помилок НЕ виправляти без консультації. Ці знання живуть у головах людей, а не у файлах.
Межа, яку не перетинає жоден автомат: рішення про публікацію. Жодна чернетка не потрапляє до офіційної документації без затвердження особою, відповідальною за певну область. Це операційна вимога, а не лише етична. Хороша практика підготовки даних для ШІ описана в статті як підготувати корпоративні дані для ШІ.
FAQ
#Чи може асистент самостійно оновлювати вікі після кожного коміту?
Не повинен, принаймні без етапу перегляду. Асистент може автоматично генерувати чернетку зміни та створювати pull request до документації з пов'язаним комітом коду. Але прийняття цієї чернетки потребує затвердження інженером, відповідальним за певну область. Автоматичне перезаписування вікі без перегляду — реальний ризик: внутрішній рефакторинг, який не змінює публічну поведінку, може згенерувати оманливі зміни в документації.
Як обробляти документацію, коли той самий ендпоінт описаний у кількох місцях?
Це одна з найпоширеніших проблем при RAG над технічною документацією. Retrieval поверне кілька фрагментів, і модель може спробувати їх об'єднати, що призведе до суперечливих описів. Шаблон, який ми рекомендуємо: перед впровадженням асистента проведіть аудит бази знань і позначте одне джерело істини для кожного ендпоінта. Дублікати позначте як deprecated з посиланням на канонічне джерело. Асистент індексує лише канонічне джерело.
Як вимірювати якість згенерованої документації?
Два показники, які мають операційний сенс: відсоток чернеток, прийнятих без змін рецензентом (ціль: понад 50 відсотків після першого місяця калібрування) та час перегляду чернетки інженером (ціль: менше 15 хвилин для типової секції). Низький відсоток прийняття сигналізує про проблеми з якістю індексу або системним промптом. Тривалий час перегляду сигналізує про занадто великі чернетки або недостатньо конкретне цитування джерел.
Що робити, коли асистент генерує опис параметра, якого немає в OpenAPI?
#Це сигнал, що guardrail цитування працює некоректно. Правильно налаштований асистент не повинен генерувати опис без покриття в індексі. Якщо таке трапляється, перевірте два місця: чи guardrail перевіряє наявність цитати в кожній чернетці, і чи не занижений поріг схожості retrieval (допускаються занадто слабкі збіги). Опис параметра, якого немає в джерелі, — це симптом відсутності guardrails, а не слабкості моделі.
Чи може ШІ автоматизувати документацію для онбордингу нових програмістів?
Може створювати каркаси онбордингових документів з коду та наявних процедур. На практиці онбординг потребує знань, яких немає в жодному файлі: неписаних конвенцій команди, історичних архітектурних рішень, місць, які є крихкими і відомі лише «старожилам» команди. Асистент скорочує час підготовки документа на кілька десятків відсотків, але остаточна версія завжди потребує внеску інженера з досвідом у певній області.