Специфікація для reviewer'а

1. Інженерної чернетки вже недостатньо

На старті інженерна чернетка специфікації справді працює чудово: вона зводить вас і Claude Code до спільного завдання — що робимо, де межі, чого не чіпаємо, як перевіримо. Але в такого документа є слабке місце: він написаний зсередини вашої голови, а reviewer читає його ззовні. І якщо документ зрозумілий лише тому, хто місяць живе проєктом, значить, він досі сирий.

Інженерний draft зазвичай відповідає на питання «що робимо технічно». А версія для reviewerʼа має відповідати на більш неприємні, але дуже корисні питання: кому це допомагає, який шматок реально працює, що я побачу на demo, як перевірити руками, чого ви не обіцяєте. Reviewer не зобов’язаний бути телепатом, навіть якщо ви дуже на це розраховуєте.

Тому тут не відбувається магії й не народжується нова сутність: я не викидаю попередній SPEC.md і не пишу роман з нуля — роблю другий прохід і виводжу з інженерної чернетки текст, який витримає холодний погляд збоку. А холодний погляд, до речі, лікує розповзання scope та фрази на кшталт «ну тут усе приблизно зрозуміло».

2. SPEC.md і MVP_SPEC.md: одне сімейство

У цьому місці багато хто починає плутатися в назвах файлів і влаштовувати маленький локальний серіал під назвою SPEC_final_final_real.md. Краще не треба. Логіка проста: у вас одне сімейство документів на проєкт. Для чистого MVP-архетипу зручно MVP_SPEC.md; для capstone, де SPEC.md уже заведено, — посилюйте його, а не плодіть близнюка.

Найважливіше правило тут — один source of truth. Якщо ви ведете обидва файли, а потім в одному user один, в іншому інший, а demo-сценарій узагалі третій, ви не створюєте гнучкість. Ви створюєте красиву багатосерійну плутанину.

Корисно також не змішувати ролі документів. Специфікація відповідає за задум, межі та перевірку, а EVIDENCE_LOG.md — за сліди виконання: що пробували, запускали, що зламалося, що перевірили. Якщо evidence-лог уже заведений під близькою назвою — використовуйте його. Якщо ж ви почнете складати в специфікацію історію всіх спроб, вона швидко перетвориться на археологічний шар. Для археології в нас є інші файли.

3. Reviewer хоче зрозуміти за пʼять хвилин

Коли людина відкриває специфікацію, готову для reviewerʼа, вона не хоче йти в похід по ваших чатах, комітах і внутрішніх осяяннях — вона хоче за хвилини зібрати в голові просту модель проєкту. Хороша специфікація працює як добре підписана коробка: ви ще не відкрили її до кінця, а вже розумієте, що всередині.

Ці розділи легко почати дублювати, тому що всі вони описують один і той самий проєкт. Але ролі в них різні: кожен закриває своє питання з таблиці. І зверніть увагу на важливу деталь: reviewer читає документ не заради натхнення — він читає його заради рішення. Якщо після пʼяти хвилин читання не можна сказати, що робить продукт, кому допомагає і як перевіряється, значить специфікація досі написана радше «для автора», ніж «для review». Це нормальний етап, але зупинятися на ньому не варто.

4. Проблема — мовою користувача

У розділі Problem reviewer спочатку має побачити біль, а не обраний вами технічний трюк. До цього місця проблема вже зрозуміла вам самому — тепер важливо перевірити, чи не підмінили ви її описом реалізації на кшталт «потрібно зробити AI-класифікацію тікетів і генерацію draft-відповідей».

Нижче — уже робочий фрагмент для нашого AI Support Agent:

## Проблема

Оператор підтримки невеликого інтернет-магазину отримує десятки звернень на день.
Повторювані питання про статус замовлення та повернення з’їдають час на ручні відповіді.
Через це складні та ризиковані кейси обробляються пізніше, ніж потрібно.

Якщо в Problem уже оселилися FastAPI, класифікатор, RAG, ембеддинги та інші смачні технічні слова — reviewer ще не побачив біль, він уже продирається крізь implementation.

5. User і JTBD: від загальної аудиторії до живої ролі

У розділі Target user / JTBD reviewer має побачити одну живу роль, одну робочу ситуацію і поточний workaround. Не «магазини» й не «підтримку взагалі», а конкретну людину, у якої зранку забитий inbox і яка зараз викручується нотатками та копіпастою.

Для архетипу AI Support Agent хороше формулювання виглядає так:

## Цільовий користувач / JTBD

Користувач: оператор підтримки невеликого інтернет-магазину.

Коли зранку inbox заповнений десятками тікетів,
я хочу швидко відокремити типові звернення від risky-case
і отримати чернетку відповіді на прості питання,
щоб не витрачати час на копіювання шаблонів
і не пропускати refund-запити на велику суму.

Корисна ознака reviewer-ready блоку — current workaround видно поруч, а не бовтається окремою думкою. Інакше продукт виглядає так, ніби користувач до вас сидів у вакуумі й терпляче чекав саме ваш MVP.

6. Release slice: один маршрут замість набору функцій

У розділі Release slice reviewer має побачити один завершений маршрут, а не список симпатичних функцій. До цього місця must-have, non-goals і forbidden zone уже вибрані — тепер важливо показати, що реально працює разом.

Тепер переведімо це в текст специфікації:

## Релізний зріз

Вхід: sample ticket з текстом і ідентифікатором клієнта.

Основна дія: система класифікує тікет і,
якщо звернення типове, пропонує чернетку відповіді.

Вихід: оператор бачить мітку, draft і може прийняти
або відредагувати відповідь.

Guardrail: refund > $100 не обробляється автоматично
і потребує ручного схвалення.

Щойно цей маршрут зафіксовано, план перевірки й demo перестають жити окремим життям: обидва просто відтворюють саме його.

7. План перевірки і demo: один ланцюжок

У План перевірки і Demo scenario reviewer має побачити, як це перевіряється руками й показується без шаманства. Дуже багато початківців розводять план перевірки і demo scenario по різних кімнатах, ніби це чужі один одному родичі. Насправді це один ланцюжок. План перевірки відповідає на питання «як перевіряємо», а demo scenario робить цю перевірку видимою і відтворюваною. Якщо між ними немає зв’язку, специфікація починає звучати переконливо, але перевіряється як туман.

Нижче — компактний варіант План перевірки для нашого архетипу:

## План перевірки

Запуск: `docker compose up`

Smoke-check:
1. Inbox відкривається з 10 sample tickets.
2. Ticket #3 отримує label `typical` і draft відповіді.
3. Ticket #7 з refund $250 блокується і потребує manual approval.
4. В audit trail видно, що запропонував AI і що зробив оператор.

Тепер подивіться, як це перетворюється на demo-сценарій. Гарний спосіб — буквально зіставити критерії приймання зі сценою показу:

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

Нижче — уже нормальний фрагмент Demo scenario:

## Demo-сценарій

1. Відкрити inbox з 10 sample tickets.
2. Обрати типовий ticket #3 і показати classification + draft.
3. Прийняти draft і відкрити audit trail.
4. Обрати ticket #7 з refund $250 і показати блокування.

Зверніть увагу, як мало тут зайвого. Це не екскурсія застосунком і не спроба вразити кількістю екранів. Це маршрут перевірки. Саме тому такі сценарії зазвичай сприймаються набагато сильніше, ніж demo в стилі «ну тут ще є налаштування, фільтри, графіки і, до речі, ось красивий логотип».

8. Known limitations і Risks: чесність

Коли автор боїться писати обмеження, він зазвичай думає, що виглядає слабше. На практиці відбувається рівно навпаки: сильнішим виглядає проєкт, у якого межі названі вголос. Фраза production-ready притягує проблеми так само, як магніт притягує скріпки. Тому краще бути чесним і конкретним.

Для нашого AI Support Agent розділ може виглядати так:

## Відомі обмеження

- Працюємо на sample data, не на live CRM.
- Accuracy вимірюється тільки на demo-наборі з 10 тікетів.
- Немає multi-language support.
- High-value refund не відправляється автоматично.

А поруч можна коротко окреслити ризики:

## Ризики

- На нових формулюваннях accuracy може бути нижчою, ніж на demo-set.
- Поріг high-value refund зараз заданий правилом, а не adaptive-логікою.
- Чернетка відповіді оцінюється оператором вручну, без окремого quality-score.

У таких розділах немає нічого соромного. Навпаки, reviewer бачить, що ви не продаєте навчальний MVP як enterprise-систему, і довіра зростає. Нормально сказати: «показуємо один робочий slice, але не готові обслуговувати бойовий потік магазину в понеділок зранку». А ось якщо документ звучить так, ніби завтра його можна везти в production, а проєкт тримається на sample data і ручній перевірці, — значить, завелася зайва бравада. Її краще акуратно виселити.

9. Claude Code як reviewer специфікації

На цьому етапі Claude Code особливо корисний не як генератор нових ідей, а як reviewer документа. Це принципово різні ролі. Якщо ви просто попросите «покращ мою специфікацію», Claude з радістю підкине ще сім фіч, два інтеграційні напрями й трохи гарного життя. Звучить заманливо, але scope freeze після цього зазвичай починає тихо плакати в кутку.

Тому запит краще робити жорсткішим і конкретнішим. Наприклад так:

Перевір цю специфікацію як reviewer.

Не пропонуй нових функцій, якщо вони не потрібні для core flow.

Знайди:
1. неясні формулювання для користувача;
2. scope creep і суперечності non-goals;
3. прогалини у verification і demo-сценарії;
4. фрази, які звучать як fake production claims.

Поверни відповідь коротко, за розділами.

Ще краще, якщо для такого review ви відкриєте нову сесію — тоді Claude подивиться на документ холодніше, без інерції попереднього листування. Це той самий випадок, коли свіжий погляд справді допомагає.

Зручно також просити Claude повертати не абстрактне «треба покращити розділ Problem», а формат на кшталт: «цитата з фрагмента → чому неясно → як переформулювати». Тоді review стає робочим, а не філософським. І найголовніше — пам’ятайте, що вам зараз потрібен не партнер по мозковому штурму, а спокійний редактор, який помітить слизькі місця.

10. Каркас готового документа

Коли всі попередні частини зібрані, у вас виходить дуже простий, але сильний каркас: не красивість заради красивості, а документ, який читається зверху вниз без стрибків між файлами й здогадок за контекстом. Якщо у вас чистий MVP, цей каркас може жити в MVP_SPEC.md; якщо ні — в основному SPEC.md.

# SPEC.md

## Value proposition
...

## Проблема
...

## Цільовий користувач / JTBD
...

## Обсяг / Не-цілі
...

## Релізний зріз
...

## Заборонена зона
...

## Метрика успіху
...

## План перевірки
...

## Demo-сценарій
...

## Відомі обмеження / ризики
...

Зверніть увагу, що тут немає нічого екзотичного. Специфікація не зобов’язана бути довгою, щоб бути сильною, — вона зобов’язана бути зв’язною. Reviewer проходить по документу й ніде не спотикається об «пачекайте, а для кого це взагалі?» або «а що я побачу наживо?». Якщо після читання він переказує ваш core flow своїми словами й відтворює demo без шаманства та телепатії — значить, документ уже виконує свою роботу. І це дуже гарний стан для специфікації.