Завершение: Definition of Done

После аудита Борис стал осторожнее.

Прогнал всё: title, favicon, базовый SEO, сборка, тесты, export JSON, mobile, security baseline. Критичное закрыл, остальное — в backlog v2. На его ноутбуке всё работает.

Дальше он кидает ссылку другу:

Если что, просто запусти проект по README.

Через 10 минут друг отвечает — не стартует. README не помог: версии Node нет, команда установки другая, одна переменная окружения забыта, export JSON описан по-старому. Публичной ссылки, кстати, тоже нет: публичная ссылка ещё не появилась — Борис ни разу не деплоил, продукт живёт только на его ноутбуке.

Вот тут и подгорает.

Код почти готов, а показать нечего. На ноутбуке Бориса всё работало, потому что рядом сидел сам Борис — помнил команды, знал ограничения, где лежат данные. Друг всего этого не знает, и объяснить некому.

Короче, вроде работает не равно принято.

Теперь Борису надо доказать, что JobTrack живёт за пределами локального окружения и не разваливается при первом чужом запуске.

Зачем нужен DoD

Вроде работает — это когда автор увидел счастливый сценарий на своём ноутбуке. Один раз. При хорошей погоде.

Принято — когда продукт можно запустить, проверить, показать другому человеку и объяснить, что входит в первую версию.

Definition of Done — вот эта граница.

Для JobTrack это особенно важно после m14. Аудит уже нашёл риски перед показом. Приёмка проверяет другое: запустится ли продукт без автора рядом.

основной сценарий, UI, хранение данных, JSON export, README, public URL или demo mode — всё это должно сходиться. И сходиться в проекте, а не у автора в голове.

Приёмку и фиксацию релиза в SPP закрывают acceptance demo и фаза release-fixation.

SPP пишет состояние проекта в docs/spp/pipeline-state.md: что за продукт, что сделано, какие решения приняты. Файл нужен, чтобы агент в новой сессии не начинал с амнезии. Прервал работу — продолжил с того же места. Следующий модуль просто продолжает тот же pipeline.

Что входит в DoD сольного MVP

Короче, DoD не обязан быть корпоративной простынёй. Для первого MVP хватает такого списка:

— scope: что входит в MVP и что осталось в «не сейчас»; — clean run: проект запускается с нуля; — README: инструкция совпадает с реальностью; — env: переменные окружения описаны, есть безопасный example; — tests или ручная проверка: проверки проходят; — сценарии руками: основной путь пользователя пройден вручную; — данные: JSON export работает, формат не сломан; — data ownership: пользователь понимает, где живут данные и как их забрать; — public URL: есть ссылка или понятный локальный demo mode; — полировка: title, favicon, OG, базовый mobile; — known limitations: что MVP не умеет — записано; — граница релиза: финальный commit или deploy содержит только принятую версию.

DoD проверяет не красоту кода. Он проверяет, можно ли пользоваться MVP без автора рядом.

Clean run

Чистый прогон — это запуск в новом состоянии: новая папка, свежий clone, чистая установка зависимостей, команды из README. Именно там всплывает вся прекрасная бытовая боль:

— забытая версия Node; — неописанная команда установки; — отсутствующий .env.example; — переменная, которая есть локально, но нигде не описана; — seed или demo data не создаются; — build проходит локально и падает на хостинге; — README устарел после последних модулей.

Нормальный prompt для агента:

Review README and setup instructions against the current project.
Do not change product behavior.
Find gaps that would break a clean clone setup:
- runtime versions;
- install command;
- env vars;
- dev command;
- test command;
- build command;
- demo data;
- public URL or local demo mode.
Return exact README edits first.

Сначала review, потом правки. Иначе агент опять начнёт чинить код вместо инструкции — инструкция скучная, а переписать storage в финале релиза это прям праздник)

README как контракт

README в финале — контракт запуска, не реклама. От него я хочу ответы: что делает JobTrack; для кого этот MVP; что входит в текущий scope и что не входит; как поставить зависимости; как запустить локально; как прогнать tests и build; какие env vars нужны; где взять demo data или как создать первую запись; где публичный URL; какие есть известные ограничения.

Если README обещает search, import или auth, которых в MVP нет — это просто враньё пользователю.

Env и секреты

Я не хочу, чтобы финальный MVP зависел от секретов, которые живут только на моём ноутбуке. Проверь:

— .env не попал в Git; — есть .env.example, если env vars нужны; — в README описано, какие переменные обязательны, а какие optional; — локальный режим по умолчанию работает без платных внешних сервисов, если так решено в docs/design.md; — публичный deploy хранит секреты в настройках хостинга, а не в коде.

Если JobTrack пока полностью локальный и env vars не нужны — так и напиши: env vars not required for MVP. Это лучше пустого загадочного раздела, который выглядит как дверь в подвал)

Финальные сценарии проверки

Прогоняю финальные сценарии на том же MVP, что выбрал раньше. Для JobTrack минимум:

1. Открыть приложение.
2. Добавить вакансию с title, company, source и status.
3. Увидеть её в списке.
4. Изменить status или заметку.
5. Проверить, что следующий шаг или заметка видны после обновления.
6. Сделать JSON export.
7. Открыть export и убедиться, что там есть version, timestamp, jobs, source, status, createdAt, updatedAt.
8. Проверить, что export не тащит секреты и debug data.

Есть автотесты — пусть закрывают ключевую логику. Но руками проверить всё равно надо: пользовательский путь ломается не только в функциях, но и в UI.

Public URL, домен и поддомен

Принятый MVP надо чем-то показать. Способов хватает: локальный demo mode, если показываешь экран сам; preview URL хостинга; публичный URL платформы; домен или поддомен. Домен для первой демонстрации не нужен. Нужен рабочий способ дать доступ. Выбрал локальный demo mode — пусть это будет решение, а не отмазка, что deploy никто не проверил.

Если используется публичный URL, проверь:

— ссылка открывается в приватном окне или другом браузере; — build соответствует последнему commit; — в клиенте нет тестовых секретов; — 404 или 500 не встречает пользователя на первом экране; — базовый mobile не разваливается.

Product polish без новых фич

Финальная полировка — это не новый dashboard. Минимум:

— title страницы отражает продукт; — favicon не дефолтный, если проект публичный; — OG title, description и image не врут; — mobile не ломает основной сценарий; — empty и error states понятны; — длинные русские строки не вылезают из контейнеров.

Захотелось на этом шаге добавить ещё функцию — занеси её в backlog v2. DoD закрывает текущий MVP, а не открывает новый цикл разработки.

Known limitations

Известные ограничения лучше назвать самому. Для JobTrack это может быть так: данные хранятся локально; нет синхронизации между устройствами; нет auth; нет импорта из job-сайтов; JSON export ручной; аналитика минимальная или её нет; продукт не обходит ToS job-сайтов и не собирает данные автоматически.

Названные ограничения защищают от ложных ожиданий. С ними MVP и пойдёт в упаковку на m16.

Финальный commit и deploy

Финальный commit должен быть скучным. README, setup, env. Финальные checks. Мелкие fixes, найденные чистым прогоном. Deploy config, если нужен. Известные ограничения.

Плохой финальный commit — это README плюс новая фича, переписанный storage, auth, search и redesign. Это опять scope creep, только в костюме завершения)

Перед финалом:

— git diff прочитан; — git diff --staged прочитан; — build или чистый прогон прошёл; — автотесты прошли, а если их нет — documented ручная проверка закрывает только тестовую часть; — public URL или local demo mode проверен; — docs/todo.md закрывает MVP и переносит остальное в backlog v2.

DoD — не торжественная ленточка, а приёмка. Прошёл — MVP идёт к живым людям и первому feedback. Не прошёл — у тебя всё ещё просто вроде работает.

Цель: закрыть JobTrack как принятый MVP, который можно запустить, проверить и показать без устных объяснений автора.

Шаг 0. Запусти SPP verification workflow

Перед финальной приёмкой попроси агента выбрать workflow для verification/release acceptance. Здесь опасно чинить всё подряд: задача не расширить продукт, а доказать, что MVP принят.

Используй /spp.

Мы на модуле 15. MVP уже реализован через m11-m13, а в m14 пройден аудит перед показом. Нужно принять мой проект по Definition of Done.

Задача:
- собрать DoD из docs/design.md, docs/plan.md, docs/todo.md и текущего продукта;
- проверить README как clean-run контракт;
- проверить env/secrets;
- выполнить clean run, build/tests или documented manual fallback;
- пройти manual scenarios;
- проверить public URL или явно записать local demo mode;
- не добавлять search/import/auth/redesign;
- финальный diff должен быть только acceptance/docs/setup/fixes.

Модуль 15 — самый тяжёлый. Практика разбита на два блока, и их можно пройти в два подхода: сначала приёмка, потом деплой. Не пытайся героически закрыть всё одним рывком, если уже начинаешь путать проверки.

Блок 1. Приёмка

Шаг 1. Собери финальный DoD

Открой docs/design.md, docs/plan.md, docs/todo.md и результаты модулей 11–14.

Запиши Definition of Done в docs/release.md:

# Definition of Done для JobTrack MVP

- Scope MVP совпадает с docs/design.md
- Все must-have задачи закрыты
- Clean run проходит по README
- Build или clean run проходит; автотесты проходят, а если автотестов нет, documented manual fallback закрывает только тестовую часть
- Основной сценарий JobTrack проверен руками
- JSON export работает и сохраняет формат m13
- Must-fix из m14 audit report закрыты или явно перенесены в backlog v2
- README описывает запуск, env, checks и ограничения
- Public URL или local demo mode проверен
- Known limitations записаны

Не добавляй новые must-have в DoD. Если хочется расширить продукт, это backlog v2.

Шаг 2. Проверь scope

Сравни текущий продукт с docs/design.md и docs/plan.md.

Проверь:

• основной сценарий из MVP есть;
• m11 first executable slice не сломан;
• m12 UI-polish не превратился в новую функциональность;
• m13 data boundaries и JSON export работают;
• must-fix из m14 audit report закрыты или явно перенесены в backlog v2;
• search/import/auth/tags не вернулись в MVP случайно.

Если находишь расхождение, реши: это bugfix текущего MVP или backlog v2. Не тащи новую фичу в финальную приёмку.

Шаг 3. Проверь README как clean-run контракт

Попроси агента сначала сделать review:

Используй выбранный SPP verification workflow.

Review README against the current project.
Do not change product behavior.
Find gaps that would break a clean clone setup:
- runtime versions;
- install command;
- env vars;
- dev command;
- test command;
- build command;
- demo data;
- public URL or local demo mode;
- known limitations.
Return exact README edits first.

После review обнови README.

README должен содержать:

• что делает JobTrack;
• текущий MVP scope;
• что не входит в MVP;
• Node/runtime version;
• install command;
• dev command;
• test/build command;
• env vars или явное env vars not required;
• как создать первую вакансию;
• как сделать JSON export;
• какие must-fix из m14 закрыты;
• public URL или local demo mode;
• known limitations.

Шаг 4. Проверь env и секреты

Проверь:

• .env не закоммичен;
• .env.example есть, если env vars нужны;
• README объясняет обязательные и optional env vars;
• локальный режим не зависит от личных секретов;
• public deploy хранит секреты в настройках хостинга;
• export JSON не содержит токены, ключи, session data и debug dumps.

Если env vars не нужны, добавь в README короткую строку: env vars not required for MVP.

Шаг 5. Сделай clean run

Проверь запуск с чистого состояния — как будто проект открыл другой человек, у которого нет твоей папки и твоей памяти.

Самый честный способ — склонировать репозиторий во вторую папку. Как это сделать, зависит от инструмента из модуля 5:

• Дорожка A (Codex App): создай рядом новую пустую папку, например jobtrack-clean, и открой её в Codex App. Попроси агента склонировать твой GitHub-репозиторий jobtrack в эту папку по HTTPS URL и дальше идти строго по README.
• Дорожка B (Claude Code): в терминале перейди в папку рядом с проектом и выполни git clone <HTTPS URL репозитория> jobtrack-clean, затем открой jobtrack-clean в Claude Code.

Если clone невозможен, возьми свежую временную папку или сделай clean install после удаления локальных артефактов (node_modules, кэши, build).

Иди только по README:

• install;
• dev;
• tests;
• build;
• первый manual scenario.

Если на каком-то шаге ты используешь знание из головы, README неполный. Обнови его и повтори проверку.

Шаг 6. Прогони build/clean run и тесты

Перед ручной приёмкой ещё раз закрой техническую проверку:

• build или clean run проходит;
• автотесты проходят;
• если автотестов нет, documented manual fallback закрывает только тестовую часть;
• manual fallback не заменяет проверку основного сценария руками.

Запиши команду, дату и результат в docs/release.md.

Шаг 7. Прогони финальные manual scenarios

Проверь мой проект руками:

• открыть приложение;
• добавить 2–3 вакансии с разными sources;
• увидеть вакансии в списке;
• изменить status или заметку;
• сделать JSON export;
• открыть export вручную;
• проверить version, timestamp, jobs, source, status, createdAt, updatedAt;
• убедиться, что секретов и debug data в export нет.

Запиши результат в docs/release.md: дата, окружение, что прошло, что не прошло.

Блок 2. Деплой и финал

Дальше идёт деплой. Если проходишь курс в два подхода, здесь удобная граница: приёмку выше ты уже закрыл, а деплой можно начать отдельной сессией. В SPP это фаза 8 deploy-strategy: она выбирает executed-режим с реальным деплоем или deferred-режим с честным local demo mode.

Шаг 7a. Первый деплой через deploy-strategy

Для многих это первый деплой в жизни. Разберём по шагам.

Выбор хостинга зависит от стека из модуля 8. Дефолт для типичного MVP на Next.js, Vite или статике — Vercel: бесплатен для маленьких проектов, подключается к GitHub и сам собирает проект при пуше. Критерии, если Vercel не подходит: хостинг поддерживает твой стек, бесплатного tier хватает для demo, умеет читать репозиторий GitHub, даёт HTTPS public URL и хранит env-переменные в настройках. Альтернативы под стек: Netlify и Cloudflare Pages для статики и SPA; Railway или Render, если нужен постоянный backend или база.

Шаги деплоя:

1. Регистрация. Заведи аккаунт на выбранном хостинге, войди через GitHub.
2. Подключи репозиторий. Импортируй репозиторий jobtrack. Хостинг сам определит стек и команду сборки; если не определил, укажи build и dev команды из README.
3. Env-переменные. Если у проекта есть обязательные env vars из docs/design.md и README, добавь их в настройки проекта на хостинге. Секреты в репозиторий не коммить.
4. Первая сборка. Запусти деплой и дождись сборки. Если сборка падает, читай лог: чаще всего не хватает env-переменной или неверно указана команда сборки.
5. Public URL. Получи публичный HTTPS-адрес проекта.

Промпт агенту, если делаешь деплой через него:

Помоги задеплоить мой проект на <выбранный хостинг>.
Не меняй продуктовое поведение.
Проведи по шагам: подключение репозитория, build команда, env-переменные, запуск сборки, получение public URL.
Если сборка падает, объясни лог и что поправить.

Критерий успеха: сборка прошла, ты получил public URL, и он открывается.

Ветка «осознанный local demo mode»: если деплой не получается или сейчас не нужен, останови его сознательно. Это deferred-режим deploy-strategy: деплой отложен, но способ показа зафиксирован. Запиши в docs/release.md, что показываешь MVP локально (экран, локальный запуск или видео), и не притворяйся, что домен подключён. Это честный допустимый вариант для первого показа.

Шаг 8. Проверь public URL или local demo mode

Если сделал деплой в Шаге 7a:

• открой public URL в приватном окне или другом браузере;
• проверь, что build соответствует последнему commit;
• пройди основной manual scenario;
• проверь mobile ширину.

Если пока только локальный demo:

• запиши это как conscious decision;
• укажи, как показываешь продукт: экран, локальный запуск, видео или demo session;
• не притворяйся, что домен подключён.

Для публичного MVP также проверь title, favicon и OG. Они не должны обещать больше, чем есть в продукте.

Шаг 8b. Опционально: friend-тест

Самая честная проверка приёмки — чужой человек. Попроси одного знакомого пройти по README или demo flow без твоих подсказок: открыть проект (или public URL), установить и запустить по README, добавить вакансию, сделать JSON export.

Твоя задача — молчать и записывать, где он застрял: непонятный шаг README, пропущенная env-переменная, неочевидная кнопка. Каждое место, где пришлось объяснять голосом, — это баг README или demo flow, а не глупость человека. Поправь то, что мешает, остальное запиши в known limitations или backlog v2.

Шаг 9. Запиши known limitations

В README или docs/release.md добавь раздел Known limitations.

Для JobTrack возможные ограничения:

• данные хранятся локально;
• нет auth;
• нет синхронизации между устройствами;
• нет импорта из job-сайтов;
• JSON export запускается вручную;
• аналитика минимальная;
• автоматический сбор данных с job-сайтов не входит в MVP.

Пиши ограничения конкретно. Не надо красивых общих слов.

Шаг 10. Закрой todo и backlog v2

Обнови docs/todo.md:

• все must-have задачи MVP moved to done;
• незакрытые идеи перенесены в backlog v2;
• рядом с каждой backlog item есть причина: feedback, limitation, idea или risk;
• задачи из не сейчас не переехали в done.

Это мост к m16: там ты будешь упаковывать MVP, готовить public URL или demo mode и выводить продукт наружу.

Шаг 11. Финальный diff, commit, deploy

Перед финальным commit:

• запусти build или clean run, автотесты или documented manual fallback для отсутствующих автотестов;
• прочитай git diff;
• прочитай git diff --staged;
• убедись, что diff не содержит новую функциональность вне DoD;
• убедись, что секретов нет.

Финальный commit должен закрывать acceptance, README/setup/env/docs и мелкие fixes после clean run. Не добавляй search/import/auth/redesign в финальный commit.