Demo quality gates для capstone

1. «У мене все працює» — це ще нічого не означає

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

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

Для курсу нас цікавить саме demo-ready. Не «ідеально» і не «без жодного бага» — а момент, коли головний сценарій надійний настільки, що його можна показати, пояснити й повторити. Проєкт перестає бути домашнім улюбленцем, що живе тільки у вас на ноутбуці, і стає артефактом, здатним пережити зустріч із зовнішньою людиною.

Корисно тримати в голові й другу важливу межу. Demo-ready не вимагає всіх фіч із мрії, CI рівня NASA й захисту від кінця світу — тільки чесності: все, що входить у core flow, працює; все, що не входить, винесено в limitations, а не сховано під килим README.

2. Хто тримає sprint і demo

Поки sprint триває, дуже легко почати сприймати SPEC.md, README.md, DEMO.md і HANDOFF_PACKAGE.md як просто пачку схожих markdown-файлів. Насправді кожен тримає свій шматок маршруту. Якщо розвести ролі заздалегідь, quality gate потім читається спокійніше.

Корисно бачити це як pipeline, а не як просто стос файлів: spec тримає межі, LATER не дає scope текти, evidence збирає сліди, gate відповідає за stop/go, demo script керує показом, README відкриває вхід, handoff package проводить ревʼюера по всьому цьому. Gate залишається внутрішнім stop/go-документом і не підміняє HANDOFF_PACKAGE.md.

3. DEMO_QUALITY_GATE.md — файл, що економить нерви

Коли розробник нервує перед показом, він майже завжди починає думати неструктуровано. У голові крутиться все одразу: «а раптом не збереться», «а раптом CSV не завантажиться», «а раптом запитають про багатокористувацький режим, якого немає». Саме тому demo gate краще не тримати в голові — його виносять у короткий артефакт DEMO_QUALITY_GATE.md.

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

Найпростіший каркас файла може мати такий вигляд:

# DEMO_QUALITY_GATE.md

## Технічна база
- [ ] команди й базові перевірки зелені
- [ ] у репозиторії немає секретів
- [ ] останній diff прочитано очима

## Основний потік і reproducibility
- [ ] core flow проходить від початку до результату
- [ ] сценарій відтворюється за README

## Чесні межі та limitations
- [ ] README чесно описує demo-ready scope
- [ ] known limitations винесено окремо

Завдання у файла скромне: не дати переплутати «я втомився» з «проєкт готовий». І саме тому він працює.

Нижче — проста схема, яку корисно подумки проганяти перед кожною репетицією показу.

flowchart LR
A[Зробили slice] --> B[Технічна база
команди та diff]
B --> C[Core flow і відтворюваність]
C --> D[Чесні межі
README і limitations]
D --> E[Demo-ready]

4. Технічна база: підлога під ногами

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

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

Наприклад, для MVP на кшталт Personal CFO pre-demo прогін може бути зовсім коротким:

npm run lint          # фронтенд без грубих зауважень
npm run build         # інтерфейс збирається
pytest -q             # backend-smoke зелений
git status            # .env і зайві файли не потрапили до змін
git diff --stat       # diff невеликий і зрозумілий

Якщо у вас не Python, а, скажімо, Java або чистий TypeScript, команди будуть іншими, а принцип той самий: короткий локальний ритуал, що повторюється перед кожним показом. Якщо pre-demo check займає сорок хвилин і вимагає читання трьох сторінок Confluence, ви побудували не gate, а мініквест.

Є ще одна річ, яку тут часто намагаються недооцінити: читання diff. На цьому етапі вже пізно сподіватися, що AI «напевно, не зачепив зайвого». Показуєте Landing Optimizer, а в останньому коміті лежить напівмертва інтеграція, яку забули вичистити — вона спливе не в логу, а в найнеприємнішому місці: у питанні ревʼюера «а навіщо у вас тут цей файл?». Технічна база потрібна для того, щоб такі сюрпризи померли заздалегідь.

5. Core flow: командами ви перевірили не те

Ось тут починається найцікавіше. Лінтер зелений, збирання проходить, швидкі тести теж. Солідно — і все ще мало: командами ви перевірили технічну поверхню, а не продуктовий зміст. Шар про інше: чи проходить обіцяний користувачеві core flow від початку до видимого результату.

Для Personal CFO це: взяти sample CSV, завантажити, отримати категоризацію, побачити місячне зведення. Для Landing Optimizer — ввести URL, отримати аналіз сторінки, побачити backlog гіпотез. Для feature в existing codebase — пройти один користувацький ланцюжок після вашої зміни. Для migration slice — підняти мігрований шлях і показати validation evidence. Різний capstone, одна логіка: вхід, головна дія, спостережуваний результат.

Дуже корисно оформити цей шар не як абстрактну думку, а як короткий сценарій.

## Основний потік і reproducibility

1. Відкрити проєкт за README.
2. Використати sample data з `data/sample.csv`.
3. Пройти головний сценарій від початку до кінця.
4. Побачити очікуваний результат на екрані.
5. Повторити той самий сценарій на fresh clone.

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

У цьому шарі зазвичай спливає найкорисніша правда про проєкт. Що core flow проходить тільки після заходу в адмінський розділ. Що README мовчить про потрібний seed-файл. Що sample data лежать у вас на робочому столі, а не в репозиторії. Відкриття неприємні — але саме вони перетворюють «працює в автора» на «працює як проєкт».

І ще один важливий момент. Шар перевіряє головний сценарій, а не всі мислимі фічі. Є експорт PDF поза обіцяним core flow — не тягніть його в gate штучно: export це nice-to-have поза demo slice, але якщо він обіцяний як частина цінності — зобовʼязаний проходити. Хитрувати формулюваннями не можна: core flow визначається змістом проєкту, а не настроєм автора в день показу.

6. Чесні межі: шар інженерної репутації

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

Це місце, де demo-ready відділяється від production-ready не словами в розмові, а прямо в артефактах. README не має обіцяти більше, ніж система вміє. Демо-логін замість справжньої авторизації — так і пишете. Багатокористувацький режим не реалізовано — не ховаєте це за «проєкт легко масштабується». Інтеграція з рекламними API в Landing Optimizer поки мокова — це limitation, а не «enterprise-ready connector».

Гарний блок обмежень може виглядати дуже просто:

## Обмеження

- У demo використовується sample data, а не реальні акаунти.
- Авторизацію замінено демо-логіном одного користувача.
- Файли більше 10 MB не тестувалися.
- Multi-currency поки не входить до поточного scope.

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

Подивіться, як сильно відрізняється слабке формулювання від сильного.

Цей шар корисний ще й тому, що не дає ховати архітектурні борги в красивих словах. Техбаза і core flow формально пройдено, а README написано так, ніби завтра його можна продавати великому банку — і ревʼюер перестає довіряти вже всім артефактам. Чесні межі — шар інженерної репутації. Він робить проєкт не пафоснішим, а дорослішим.

7. DEMO_QUALITY_GATE.md під свій capstone

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

Для більшості проєктів базового каркаса більш ніж достатньо. Якщо ваш capstone відносно невеликий, не роздувайте gate до сорока пунктів. Чим менше зайвого, тим охочіше ви ним користуєтеся.

# DEMO_QUALITY_GATE.md

## Технічна база
- [ ] build, lint і швидкі checks зелені
- [ ] у репозиторії немає `.env` і секретів
- [ ] останній diff прочитано очима

## Основний потік і reproducibility
- [ ] core flow проходить за README
- [ ] fresh clone дає той самий результат

## Чесні межі та limitations
- [ ] README описує demo-ready scope
- [ ] known limitations винесено окремим блоком

Якщо проєкт складніший, у Middle і Senior зазвичай зʼявляються додаткові перевірки. Не «так солідніше», а тому, що більше ризикованих кутів.

Тут важливо не впасти в іншу крайність: додаткові перевірки корисні, тільки коли реально знімають ризик. Для Personal CFO без браузерних тонкощів скриншот-верифікація кожного стану надмірна; для Landing Optimizer, де цінність багато в чому візуальна, — виправдана.

Гарна звичка — заповнювати файл буквально галочками, а не «мислено». Пункт не зелений — не вважайте, що «ну там же майже готово». Gate — не місце для слова «майже». Його й придумано, щоб це «майже» відрізати.

8. Робота з червоними пунктами

Найбільша цінність quality gate проявляється не тоді, коли файл увесь зелений, а тоді, коли в ньому раптом спалахує червоний пункт. У цей момент у вас зʼявляється вибір: не сховати проблему, а прийняти інженерне рішення. І ось тут якість capstone зазвичай видно найкраще.

Червоний у технічній базі — лагодити до показу: build, що впав, секрет у репозиторії, сміттєвий diff — це не обмеження проєкту, а технічний борг, що заважає довірі. Червоний у core flow — або лагодите, або чесно ріжете scope. Але scope не скорочується магією слів: обіцяли export як частину центральної цінності, а він не працює — не можна тихо перефарбувати його в nice-to-have за пʼять хвилин до показу. Ревʼюер чудово відчуває такі перестановки меблів.

З чесними межами ситуація тонша: тут червоний пункт часто лагодиться не кодом, а формулюванням. Проєкт уже demo-ready, але README написано мовою стартап-презентації після трьох чашок кави — переписувати треба не архітектуру, а опис і limitations. Це теж інженерна робота: гарний проєкт — не тільки те, що працює, а й те, що правильно описано.

Нижче корисна коротка памʼятка.

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