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 и reproducibility]
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, паника заметно падает. Вместо надежды автора — управляемая готовность. А это уже очень похоже на настоящую инженерную практику.