Документація за підтримки AI

1. Чому документація — саме тепер

Раніше писати документацію було нічим. Тепер є: CODEBASE_INVENTORY.md, API_MAP.md, звичка перевіряти твердження за кодом, докази з термінала й логів, короткі вичавки з великих розслідувань. Документ тепер збирається з підтверджених артефактів, а не з пам’яті й красивого переказу.

Документація — це переклад із мови проєкту на мову людини. Код знає, що робить RefundService, конфіг — на якому порту запускається backend, тест — який сценарій є коректним. Документація збирає це в форму, зрозумілу іншому розробнику, новому учаснику команди або вам через два тижні. Пам’ять тут підводить: вам здається «я потім розберуся». Здебільшого — ні.

У Commerce OS це видно на поверненнях, оплатах, dashboard-метриках, AI-підказках підтримки. Поки код свіжий, логіка здається очевидною. Але щойно потрібно пояснити, де починається потік повернення, який endpoint його запускає, коли вмикається ручна перевірка і що відбувається локально без webhook, «ну це десь у сервісі» перестає бути документацією.

2. Документи, які підсилюють Claude Code

«AI допомагає писати документацію» в голові часто перетворюється на один величезний README.md, куди звалюють запуск, архітектуру, troubleshooting, огляд API та історію компанії. На практиці корисніше мати набір невеликих документів із конкретним читачем і конкретним завданням.

Мапа того, з чим Claude Code реально допомагає в Commerce OS:

Правило: один документ — одне завдання. «Задокументуй модуль повернень» працює так само, як «зроби красиво». А «збери onboarding-документ для локального запуску backend і frontend» або «зроби чернетку пояснення потоку повернення для рев’ю» дає результат помітно кращий.

Claude сильний у першому каркасі: швидко запропонує розділи, підзаголовки, чернеткові формулювання, винесе assumptions і обмеження. Це багато. Але це каркас, не остаточна правда.

3. Claude пише чернетку, а не істину

Тут головна пастка. Claude пише документацію переконливо — іноді занадто. Він опише модуль, якого в проєкті немає, вигадає правдоподібну команду запуску, згадає інтеграцію, яка «логічно має існувати». Логічно — не означає підтверджено.

Порівняйте формулювання:

AI-документація без перевірки — це ввічлива галюцинація. Виглядає як текст досвідченого інженера, а стоїть на двох прочитаних файлах і уяві.

Правило уроку: усе, що згенерував Claude, — чернетка, доки ви не звірили текст із кодом, конфігами, командами й тестами. Не звірили — це заготовка документації, не документація.

4. Даємо Claude правильний матеріал

Якість документації починається не з формулювання запиту, а з джерел. Дали абстрактне запитання і нуль доказів — отримаєте абстрактний текст. Дали API_MAP.md, конкретні класи, тести та конфіги — Claude вже не так легко відпливає в художню літературу.

Гарний запит для документа про потік повернення в Commerce OS:

Склади чернетку файла `docs/refund-flow.md` для Commerce OS.

Спирайся лише на такі джерела:
- `API_MAP.md`
- `src/orders/OrderController.java`
- `src/refunds/RefundService.java`
- `src/test/java/.../RefundServiceTest.java`
- `src/main/resources/application.yml`

Відокремлюй підтверджені факти від припущень.
Якщо чогось не вистачає, додай розділ «Відкриті питання».
Не вигадуй нові класи, інтеграції та черги.

Цей запит хороший не магією, а межами: де правда, що заборонено вигадувати, як поводитися з невизначеністю. Доросла робота з AI — задавати рамки, а не чекати чудо-промпт.

Якщо модуль великий і читати все в основній сесії не хочеться, спочатку через subagent або з ізольованої investigation-сесії зберіть докази, потім просіть чернетку:

Досліди лише модуль повернень у Commerce OS.
Поверни:
- список файлів, які формують потік повернення,
- пов’язані тести,
- конфіги,
- відкриті питання.
Не пиши документацію, лише збери джерела.

В основну сесію потрапляє не сирий пошук, а коротка перевірювана вичавка. Claude пише з підготовленого набору джерел, а не «з голови».

5. Перетворюємо API_MAP.md на живу документацію

API_MAP.md — один із найкорисніших артефактів рівня. Але сам по собі він залишається картою: компактною, технічною, сухою. Документація робить наступний крок — перетворює карту на маршрут. Не «ось endpoint», а «ось як через нього проходить сценарій і на що дивитися».

З карти API можна зібрати такий фрагмент:

# Потік повернення коштів

Запит на повернення створюється через `POST /api/orders/{id}/refund`.
Обробник знаходиться в `OrderController.java`, після чого керування
передається в `RefundService#createRequest`.

Якщо сума повернення перевищує ліміт ручного схвалення, заявка не
виконується одразу і отримує статус `PENDING_REFUND_REVIEW`.

## Що перевірено
- `API_MAP.md`
- `src/orders/OrderController.java`
- `src/refunds/RefundService.java`
- `src/test/java/.../RefundServiceTest.java`

Це вже не список endpoint-ів, а документ, що відповідає на конкретне запитання: «Як влаштовано повернення коштів?» Розділ «Що перевірено» — не прикраса, він показує, на чому тримається текст. Змінили поведінку RefundService — одразу видно, який документ оновлювати. Reviewer читає docs/refund-flow.md і може не вірити на слово, а відкрити вихідний код.

6. README і команди запуску: найчастіша брехня

Документація із запуску застаріває першою: команди змінюються швидше за README. Тому setup-розділи звучать правдоподібно і підводять на першому ж кроці.

Правило: команди з документації запускайте буквально. Не «виглядає знайомо», а проганяйте через термінал.

Текст пропонує npm run start, а package.json знає лише npm run dev — це не суперечка про стиль, а помилка в документації. Для чернетки досить: Claude збере структуру розділу «Локальний запуск» і список кандидатів на команди. Статус «це працює» текст отримує лише після перевірки за build.gradle, package.json, application.yml і реального запуску.

7. Документація в коді та архітектурні нотатки

Окрім README.md є короткі коментарі поруч із кодом і невеликі архітектурні нотатки. Їх читають у момент роботи, а не «коли-небудь потім». І вони особливо легко скочуються в брехню — здаються маленькими й безневинними.

Нормальна докстрока для методу в модулі повернень:

/**
 * Створює заявку на повернення і переводить її на ручну перевірку,
 * якщо сума перевищує ліміт схвалення.
 *
 * @param orderId ідентифікатор замовлення
 * @param amount сума повернення
 * @return створена заявка на повернення
 */
public RefundRequest createRequest(Long orderId, BigDecimal amount) {

Вона описує спостережувану поведінку і не обіцяє зайвого — жодних міфів про «гнучкий інтелектуальний рушій повернень нового покоління».

З архітектурними нотатками обережніше: вони звучать солідно і тому легко стають занадто сміливими. Не впевнені — напишіть це прямо:

## Припущення
Мобільний клієнт, імовірно, використовує той самий endpoint повернення, але це
не підтверджено кодом поточного репозиторію.

## Обмеження
Локальне середовище не отримує реальні webhook-події від платіжного
провайдера, тому цей етап перевіряється окремо.

Така чесність робить текст сильнішим. Документація не зобов’язана зображати всезнання — її завдання передавати перевірене знання і явно позначати межі.

8. Чесний фрагмент документації для Commerce OS

Зберімо все разом в один короткий, але дорослий приклад. Ви завершили дослідження потоку повернення і хочете покласти в репозиторій документ, який через місяць можна відкрити без сліз:

# Повернення в Commerce OS

Запит на повернення створюється через `POST /api/orders/{id}/refund`.
HTTP-запит приймає `OrderController`, після чого керування
передається в `RefundService`.

Якщо сума повернення перевищує ліміт ручного схвалення, заявка
не виконується одразу і отримує статус `PENDING_REFUND_REVIEW`.

Для локальної перевірки використовуйте `RefundServiceTest` і запуск backend
через `./gradlew bootRun`.

## Джерела
- `API_MAP.md`
- `src/orders/OrderController.java`
- `src/refunds/RefundService.java`
- `src/test/java/.../RefundServiceTest.java`

## Обмеження
Webhook від платіжного провайдера в локальному середовищі не надходить автоматично.

Гарний результат — не тому, що він довгий або красивий, а тому, що перевірюваний: опора в коді, конкретний сценарій, явні обмеження, жодного враження, ніби текст знає більше, ніж знає. Це вже не «щось, що Claude написав у чаті», а документ, який кладуть у репозиторій Commerce OS і використовують у роботі.