Рубрика ревʼю docs-as-code: перевірка документації через diff, grep і find

1. Документація теж проходить через diff

Чернетка документа нічого не гарантує. Поки текст не пройшов diff і звірку з проєктом, це акуратно оформлене припущення.

«Документація — це теж код» звучить як лозунг, але думка практична. Поганий метод ламає застосунок. Поганий README ламає людину, яка намагається його запустити. Для команди різниця невелика.

Уявіть: Claude згенерував для Commerce OS новий docs/onboarding.md. Текст красивий і структурний. Там сказано, що проєкт запускається командами npm start і ./gradlew run, а платежі обробляє окремий модуль сповіщень. Новий розробник чесно робить усе за інструкцією — і спотикається на першій команді. Це не проблема стилю. Документ збрехав про систему.

Тому документація живе в репозиторії, змінюється через diff і проходить ревʼю. Навіть якщо ви працюєте самі без формального pull request, логіка та сама: будь-який текст про проєкт — перевірний артефакт, а не нотатка «на довірі».

Ось шлях документації від чернетки до прийнятого тексту:

flowchart TD
    D[Чернетка ШІ] --> F[Diff у репозиторії]
    F --> V[Перевірка за кодом, конфігами та командами]
    V --> C[Правки]
    C --> A[Документ ухвалено]

Ключовий зсув: документ ухвалюється не за впевненістю тону і не за тим, наскільки він «приємно читається», а за збігом із кодом, конфігами, командами запуску та реальною поведінкою системи. Claude прискорює написання, але право сказати «це правда» — за вами.

Документацію ухвалюють не за красою формулювань, а за збігом із кодом і поведінкою проєкту.

Для Commerce OS це критично: у нас уже є джерела істини — CODEBASE_INVENTORY.md, API_MAP.md, build-команди, конфіги, тести. Документація, що живе окремо від них, перетворюється на декорацію. А декоративний README працює до першої спроби щось запустити.

2. Вісім критеріїв доброго ревʼю документації

Часта помилка ревʼю — оцінювати все одразу. Коротка рубрика не замінює голову, але не дає пропустити очевидне — особливо коли текст написав ШІ і кожен другий рядок звучить підозріло розумно.

Тримайте цю рубрику поруч під час перевірки документації Commerce OS.

Тонкий момент: complete enough — це не «написати все на світі». Хороша документація не енциклопедія. В onboarding guide важливо, щоб новий розробник підняв Commerce OS локально і зрозумів, де основні модулі; трактат про всі крайні випадки потоку повернення коштів йому не потрібен. В архітектурній нотатці навпаки — там важливі зв’язки між модулями і межі інтеграцій.

Так само й source-anchored не вимагає академічного списку літератури в кожному абзаці. Сенс простіший: якщо документ стверджує щось нетривіальне, ви маєте швидко зрозуміти, звідки це взялося — з build.gradle, application.yml, src/payments/StripeClient.java, тесту на контролер, логу запуску. Джерело не знаходиться — твердження не пройшло перевірку.

Таблиця перетворює ревʼю з туманного «ну ніби нормально» на інженерний процес. Ви перевіряєте конкретні властивості артефакта, а не «красивість».

3. Перевіряємо команди, а не віримо їм на слово

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

Припустімо, Claude згенерував для Commerce OS такий фрагмент onboarding guide:

## Запуск проєкту

```bash
npm start
./gradlew run
```

На вигляд пристойно. Але ви його не обговорюєте — ви його перевіряєте:

npm start                     # npm ERR! Missing script: "start"
./gradlew run                 # Task 'run' not found in root project
./gradlew bootRun             # backend запускається на :8080
cd apps/web && npm run dev    # frontend запускається на :3000
docker compose up -d db       # PostgreSQL піднімається у фоновому режимі

За тридцять секунд зʼясовується: документ дає дві неправильні команди поспіль. Для нового розробника це перша точка контакту з проєктом. Після такого довіра до документації падає до «краще взагалі нічого не читати».

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

Після перевірки фрагмент стає придатним до життя:

## Локальний запуск Commerce OS

```bash
docker compose up -d db       # PostgreSQL
./gradlew bootRun             # backend, порт 8080
cd apps/web && npm run dev    # frontend, порт 3000
```

Перевірено за:
- build.gradle
- apps/web/package.json
- application.yml

Хороший фрагмент конкретніший за поганий: він не просто називає команду, а показує контекст — з якої директорії запускати, який сервіс піднімається, на якому порту. Це важливо для студентів, які не впевнені в терміналі: їм потрібна не «підказка для запуску», а послідовність дій, яку можна чесно повторити.

І ще: приховані умови не можна залишати «між рядками». Потрібен .env — пишіть. База має бути піднята заздалегідь — пишіть. Інакше документ виглядає коректним, а на практиці лишається пасткою.

4. Архітектура, API і найупевненіші галюцинації

З командами все чесно: запускаються чи ні. З архітектурними нотатками й описами API складніше. ШІ пише такі абзаци з виглядом розробника, який особисто проєктував усі сервісні шари, черги та обробники подій. Тому architecture notes — найнебезпечніший тип документації.

Уявіть, що в чернетці щодо Commerce OS зʼявляється пасаж:

Для SMS-сповіщень про повернення коштів використовується модуль
`src/notifications/SmsGateway.java`, який викликається з потоку повернення коштів.

Звучить солідно. Але за правилом evidence-first наступний крок — не роздуми, а пошук:

find src -name "SmsGateway.java"   # нічого не знайдено
grep -R "SmsGateway" src           # збігів немає

Якщо ви рідко в терміналі, запамʼятайте дві команди. find шукає файл за імʼям, а grep — текст за вмістом проєкту. Прості, але вкрай корисні інструменти перевірки AI-документації. Іноді одного grep достатньо, щоб за дві секунди перетворити «упевнене архітектурне твердження» на галюцинацію.

Та сама логіка для API-документації. Якщо текст називає кінцеву точку, перевірте її за API_MAP.md, контролером і тестами. На попередніх лекціях ви вже зібрали карту API та інтеграцій Commerce OS — тепер вона працює як помічник ревʼюера.

Коректний, привʼязаний до джерела фрагмент про потік повернення коштів:

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

- `POST /api/orders/{id}/refund`
- обробник: `src/orders/OrderController.java`
- сервіс: `src/refunds/RefundService.java`
- клієнт платежів: `src/payments/StripeClient.java`
- пов’язані тести: `src/test/java/.../RefundServiceTest.java`

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

Ще правило: якщо API_MAP.md уже містить перевірені факти про кінцеві точки та інтеграції, не вигадуйте їх заново в кожному документі. Спирайтеся на карту як на проміжне джерело і йдіть від неї до коду. Інакше вийде хор із пʼяти файлів, які по-різному розповідають одну історію.

5. Assumptions, Limitations і розмір diff

Спокусливо писати документацію як щось універсальне й завершене. ШІ це любить: у нього все «працює», «підтримується» й «інтегровано». Чесна документація показує не лише, що є в проєкті, а й що припускається і де закінчуються гарантії.

Уявіть onboarding guide, який дає команди запуску — і все. Формально документ є. Практично — ні: новий розробник не розуміє, чи потрібна локальна база, чи зібрано .env, чи працюють платежі в dev-режимі, чи відтворюються webhooks локально. Це не можна залишати на телепатію.

Тому Assumptions і Limitations — не декоративний додаток, а частина перевірки якості:

## Припущення
- локальна база піднята через `docker compose up -d db`
- `.env` зібрано на основі `.env.example`

## Обмеження
- Stripe працює тільки з test keys
- webhooks локально не відтворюються без зовнішнього тунелю

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

Окремо — розмір diff. ШІ любить щедрість. Попросили «поліпшити документацію» — отримаєте переписаний README, новий onboarding guide, розширені архітектурні нотатки, секцію про API і кілька порад щодо запуску. Виглядає старанно. Ревʼюиться жахливо.

Хороший docs diff — reviewable: його реально прочитати й перевірити за один підхід. Переписав Claude одразу все — reviewer майже неминуче пропустить помилку. Великі зміни ріжте: окремо запуск, окремо потік повернення коштів, окремо архітектурна нотатка про payments. Документація любить акуратне нарізання не менше за код.

«Занадто багато корисного одразу» — це реальна проблема. Корисне, яке не встигли перевірити, в репозиторії перетворюється на ризик.

6. Повний прохід по docs diff на прикладі Commerce OS

Зберемо все в один сценарій. Claude підготував оновлення docs/onboarding.md для Commerce OS: розділи про локальний запуск, коротка архітектурна довідка, невеликий блок про payments. Ваше завдання — не «оцінити враження», а провести ревʼю.

Спочатку відкриваєте diff і дивитеся на ширину. Якщо в одному зміненні переписані разом запуск, API, архітектура й troubleshooting — просіть розбити правки. Інакше перевірка перетворюється на лотерею.

Далі — найдешевший і найкорисніший шлях: копіюєте команди й запускаєте. ./gradlew bootRun, npm run dev, docker compose up -d db працюють — добрий знак. Ні — правите документ або зʼясовуєте, що зламано налаштування.

Наступний прохід — по іменованих сутностях. Усі класи, шляхи, контролери, конфіги, інтеграції мають існувати. Тут допомагають find, grep, пошук в IDE і зібраний API_MAP.md. Посилання на неіснуючий SmsGateway.java або вигаданий маршрут — фрагмент видаляється або позначається як неперевірена гіпотеза і до фіналу не потрапляє.

Потім дивитеся на цілісність очима читача. Onboarding guide: чи запустить новий розробник Commerce OS і не застрягне в глухому куті на першому кроці? Чи є assumptions? Чи є limitations? Чи зрозуміло, що платежі локально лише тестові? Чи не обіцяє текст більше, ніж проєкт уміє?

Лише після цих перевірок документ можна лишити в репозиторії. Виправлений фрагмент скромніший за AI-чернетку, зате йому можна довіряти:

## Локальний запуск Commerce OS

```bash
docker compose up -d db       # PostgreSQL
./gradlew bootRun             # backend, :8080
cd apps/web && npm run dev    # frontend, :3000
```

### Припущення
- `.env` зібрано з `.env.example`

### Обмеження
- платежі працюють лише в тестовому режимі

У цей момент ви закриваєте не лише конкретний diff. У вас зібрана повна ланка: тримати проєкт у чистому Git-стані, формулювати задачу, керувати контекстом, будувати CODEBASE_INVENTORY.md, збирати API_MAP.md, використовувати докази з рантайму і ухвалювати документацію за збігом із системою, а не за красою тексту. Claude як і раніше допомагає швидко, але право сказати «цьому документу можна довіряти» — за вами. Це не магія, а нормальна інженерна робота.

І тут видно, які ручні кроки починають повторюватися: зібрати source-anchored evidence, оновити артефакт, перевірити команди, ухвалити diff. Коли вони стабілізувалися вручну, їх пора пакувати в reusable workflow assets і спільний Workflow Kit — явні правила, шаблони та чеклисти, а не збірку з нуля щоразу.