Документація як docs-as-code артефакт

1. Документація — частина delivery, а не застосунок

Коли розробник чує слово «документація», мозок іноді перекладає його як «щось текстове, потім допишемо». Для delivery це небезпечний автопереклад. README з неправильного командою ламає запуск не гірше за зіпсований shell-скрипт, а runbook із вигаданим кроком псує вечір усій команді підтримки. Просто тихіше й пасивно-агресивніше.

Уявіть Commerce OS. Команда перевела локальний запуск на docker compose, build зелений, CI щасливий. А в README залишилася стара інструкція: спочатку ./gradlew bootRun, потім npm run dev. Новий розробник іде за документацією, отримує половину середовища, дивні помилки підключення до бази й підозрює все підряд — від Java до ретроградного Меркурія. Формально вада не в коді. Практично вона вже в поставці.

Саме тому ми говоримо про docs-as-code. Документація живе в репозиторії, змінюється разом із кодом, проходить diff і review, приймається лише після перевірки за джерелом істини — не за «спогадами автора», а за кодом, командами, конфігами та спостережуваною поведінкою.

Корисно побачити різницю між двома схожими, але насправді дуже різними завданнями:

Саме тут і відбувається головний зсув: документація перестає бути додатком до фічі та входить у change set.

2. Які документи Commerce OS вести як код

Якщо автоматизувати все підряд, вийде не інженерна система, а фабрика дуже переконливого шуму. Тому спочатку корисно розділити документи за прив’язкою до реальної поведінки: що сильніше документ пов’язаний із запуском, API, конфігом і підтримкою, то більше сенсу перевіряти його як код.

Для Commerce OS це виглядає приблизно так:

README.md

Зверніть увагу на важливу деталь. Ключове слово — delivery artifacts: документи, що безпосередньо беруть участь у запуску, перевірці, експлуатації та розумінні change. На тексті без прив’язки до коду автоматизація швидко починає фантазувати.

Тому є тексти, де Claude — помічник зі структури, але не основний автор: архітектурне рішення, ADR, postmortem, пояснення вибраного компромісу. Тут надто багато відповідальності й людського судження. Модель оформить чернетку, але фінальний сенс — за людиною. Інакше виходить документ, який виглядає серйозно, але відповідає не на те питання.

Тут корисно тримати просте правило: якщо перевіряється механічно за кодом, командами або логами — у docs-as-code workflow. Якщо описує reasoning, відповідальність і компроміси — повністю автоматизувати небезпечно.

3. Звіряйте з кодом, командами та поведінкою

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

Візьмемо простий приклад із Commerce OS. Припустімо, у README досі написано так:

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

1. `./gradlew bootRun`
2. `npm run dev`
3. Переконайтеся, що PostgreSQL уже запущений локально

Але команда давно перейшла на єдиний сценарій через контейнери:

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

1. `docker compose up -d`   # піднімає PostgreSQL, backend і frontend
2. `./gradlew test`         # backend-перевірки
3. `npm run lint`           # frontend-перевірки

Саме тут Claude корисний як інструмент порівняння, а не як літературний талант. Дайте йому дуже обмежене завдання:

Порівняй README розділ «Локальний запуск» з docker compose, Gradle tasks і frontend scripts.
Поверни лише:
1. розбіжності;
2. команди, які реально існують;
3. місця, де є невпевненість.
Файли не змінюй.

Такий запит хороший тим, що не просить «поліпшити README» — він просить знайти розбіжності між текстом і джерелом істини. Це набагато інженерніша постановка завдання.

Так само працює звірка API-документації. Візьмемо backend-код:

@RestController
@RequestMapping("/api/orders")
public class RefundController {

    @PostMapping("/{id}/refund")
    public RefundResponse requestRefund(@PathVariable UUID id) {
        return refundService.request(id);
    }
}

Отже, документація не має права раптом розповідати про PUT /api/orders/{id}/refund або про поле amount, якого в коді немає. Коректний фрагмент виглядатиме скромніше й чесніше:

### Запит на повернення
`POST /api/orders/{id}/refund`

Створює запит на повернення для існуючого замовлення.
Відповідь повертається у форматі `RefundResponse`.

Тут є важливий практичний нюанс: перевірки по файлах іноді мало. Команда може існувати в package.json, але не працювати на чистому середовищі. Endpoint може бути оголошений у controller, але падати через відсутній профіль. Тому docs-as-code verification майже завжди вимагає хоча б одного кроку реального виконання — маленького, але справжнього.

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

4. Нехай Claude звіряє, а не фантазує

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

Добра роль — знайти розбіжності, запропонувати чернетку, позначити невпевненість, послатися на джерело. Погана — вигадувати команди, env vars, endpoints і сценарії відновлення, яких він не бачив.

Тому корисно закріпити це прямо в проєктних інструкціях. У CLAUDE.md Commerce OS:

## Правила для документації
- не вигадуй endpoints, env vars і команди
- для API-тверджень указуй файл-джерело
- якщо не впевнений, пиши "не перевірено"
- ADR і postmortem залишай людині

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

Ось корисне порівняння ролей Claude за типами документів:

Іноді дуже корисно просити Claude не переписувати документ цілком, а працювати по diff — показати лише рядки, які варто змінити. Інакше разом із однією виправленою командою ви раптово отримуєте півпереписаний README в новому стилі, з новими заголовками та несподіваною філософією життя.

Ще один сильний прийом — просити модель розділяти підтверджені факти та припущення:

Перевірено:
- backend піднімається через `docker compose up -d`

Не перевірено:
- нативний запуск без Docker на Windows

Такий стиль не виглядає глянцево, зате чудово працює в команді. Глянець у runbook рідко комусь потрібен.

5. Документація як diff усередині PR і quality gate

Коли ви починаєте ставитися до документації як до коду, наступний крок очевидний: правка docs входить у той самий PR, що й зміна поведінки. Не «потім допишу», не наступної п’ятниці, не після коментаря тимліда з сумним смайликом. У той самий change set, щоб reviewer бачив причину й наслідок поруч.

Найзручніше закріплювати це прямо в шаблоні PR:

## Перевірка документації
- [ ] README оновлено, якщо змінювалися команди запуску або setup
- [ ] API docs оновлено, якщо змінювалися routes або response
- [ ] приклади команд перевірено на чистому середовищі
- [ ] секрети не потрапили в приклади та `.env`

Тут важливий не сам формат галочок, а звичка: документацію перевіряють не «взагалі», а за конкретною ознакою зміни. Не змінювали запуск — README можна не чіпати. Змінювали response повернення — API note вже обов’язкова частина diff.

Якщо базовий QUALITY_GATES.md уже описує прохід PR -> main, docs-правила краще додавати туди ж окремою секцією — поруч із кодовими перевірками:

## Документація в PR
- README і runbook оновлено, якщо змінювалися команди, env або routes
- команди з docs перевірено на чистому середовищі
- API-описання звірено з controller і тестами
- секрети не потрапили в приклади та документацію

Просто тепер видно, що gate стосується не лише build і test jobs. Той самий принцип потім знадобиться для changelog із release notes: текст перевіряється за спостережуваними змінами, а не за впевненим тоном.

Зверніть увагу, що тут уже трапляються і deterministic, і human-driven перевірки. Secret scan і наявність changed files у docs автоматизуються надійно. А чесну перевірку, що приклад запиту відповідає змісту endpoint, краще поєднувати з review людиною і, за потреби, AI-assisted звіркою за вихідниками.

Дуже важливо не змішувати документацію з «красивим текстом для клієнта». Нас цікавлять delivery artifacts: README, setup, API docs, runbook, onboarding. Маркетинговий текст, локалізація, customer-facing copy живуть за іншими правилами та створять тут лише шум.

Коли документація потрапляє в gate, вона перестає бути хвостом комети. Вона стає таким самим перевірюваним елементом change, як код.

6. Крізний приклад: README і API note без брехні

Тепер зберемо все в один невеликий сценарій, щоб картина не залишилася набором правил. Команда Commerce OS додала обов’язкове ручне підтвердження для повернень дорожчих за 100 доларів. Backend навчився повертати нову ознаку для support-модуля. Код оновили, тести пройшли, а документація живе вчорашнім днем.

Наприклад, тепер backend відповідає так:

{
  "requestId": "rf_123",
  "status": "PENDING_APPROVAL",
  "approvalRequired": true
}

Якщо API note все ще обіцяє просто «повернення створено», support-команда не побачить важливої гілки поведінки. А якщо runbook мовчить про approvalRequired = true, оператор почне повторювати запити, хоча треба чекати ручного рішення. Тобто помилка в документації вже б’є по продукту.

У цьому разі розумний workflow виглядає спокійно й без магії. Просите Claude порівняти controller, DTO та наявний markdown із API-описанням. Перевіряєте реальний response через тест або локальний виклик. Оновлюєте документацію невеликим diff, а не переписуванням половини розділу.

Наприклад, коректний runbook fragment може стати таким:

### Повернення дорожчі за 100 $
Якщо `approvalRequired = true`, оператор не надсилає повторний запит.
Потрібно дочекатися ручного підтвердження в панелі підтримки.
Статус до підтвердження: `PENDING_APPROVAL`.

А поруч у PR — оновлений API note і, якщо потрібно, секція README для локальної перевірки refund flow. Reviewer бачить і код, і docs, і тест. Gate не випускає назовні change, який змінює поведінку, але мовчить про неї в супровідних артефактах.

І ось тут документація нарешті поводиться як інженерний артефакт: не «текст, який треба додати», а частина робочої системи. Збігається з кодом, командами та поведінкою — допомагає рухатися швидше; не збігається — такий самий дефект поставки, як зламаний smoke test. Тому документацію в delivery цінують не за красу, а за перевірюваність.