Планирование: от спецификации к первому slice

После модуля 9 у Бориса наконец есть принятая спецификация:

Спецификация принята: <дата>

Теперь можно переходить к реализации, но не напрямую в код.

Но нет.

Следующий шаг — план, а не код. И план тоже можно запороть.

Борису хочется написать агенту коротко:

Сделай JobTrack по спецификации.

Но он уже знает, чем это кончится. Агент возьмёт весь MVP одной кучей и принесёт большой diff, где разом появились scaffold, UI, состояние, тесты, странные компоненты и половина функций из не сейчас.

То есть ровно тот хаос, из которого вся эта труба и должна была вытащить. И да, одной строкой промпта)

Плохой первый план выглядит примерно так:

1. Сделать frontend.
2. Сделать хранение данных.
3. Сделать статусы.
4. Добавить тесты.
5. Сделать polish.

На бумаге выглядит разумно.

В работе — нет.

Это всё ещё план слоями. После первого пункта пользователь не проходит сценарий JobTrack. После второго — непонятно, что вообще должно работать. А к третьему уже поздно: выясняется, что первый сценарий нарезали неправильно.

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

Борис застрял между принятой спецификацией и первой правкой кода. Нарежешь слоями — агент снова утащит всё в большой непроверяемый diff. Нарежешь слишком мелко — получишь список механических задач, после которых пользователь ничего не почувствует.

Работа в другом: разложить спецификацию на шаги, после каждого из которых можно проверить кусок работающего JobTrack.

Без нарезки на проверяемые шаги агент не строит продукт.

Он просто очень быстро генерирует проблему.

В модуле 9 ты принял docs/design.md.

Дальше — реализация, но между спецификацией и кодом нужен ещё один слой. План.

Зачем нужен план

Спецификация говорит, что строим. План — в каком порядке это безопасно делать. Это не занудство, а разница между рабочим MVP и кашей.

Если дать агенту спецификацию и сказать реализуй, он пойдёт по документу формально, а на деле смешает всё в одну кучу: каркас приложения, UI, хранение данных, проверки, полировку экрана и случайный возврат фичей из out of scope. Я это видел не раз.

Короче, получится не реализация, а пожар по спецификации.

План нужен, чтобы заранее ограничить шаг агента. Хороший план говорит: сначала делаем вот этот маленький результат, проверяем его, фиксируем, потом идём дальше.

В модуле 10 код ещё не меняется. Появляются только документы, по которым модуль 11 возьмёт первую задачу и начнёт первый executable slice.

Чем план отличается от спецификации

Спецификация фиксирует решения.

План фиксирует порядок исполнения.

Реализация меняет код.

Вертикальный срез

Вертикальный срез — это кусок продукта, который проходит пользовательский сценарий сверху вниз: интерфейс, данные, проверка, видимый результат.

Плохой срез:

Сделать frontend.

После такого пункта непонятно, что пользователь вообще может сделать.

Хороший срез:

Пользователь открывает JobTrack, видит empty state,
добавляет вакансию и видит её в списке.

Тут есть результат, граница и проверка. Срез можно запустить, проверить и показать, а при ошибке откатить отдельно.

Executable slice — это срез, который реально можно запустить и увидеть в браузере, а не просто набор файлов. Как проверять такие срезы по-человечески, без культа тестов, будет в дополнительном материале Проверки по-человечески.

Scaffold — это тоже slice

Между тем, что кода нет, и тем, что первый экран открывается, есть шаг, который легко пропустить: создать сам проект.

Пустой каркас приложения, который запускается локально и открывается в браузере, — это Slice 0.

Его результат виден человеку: dev server стартует, страница открывается без ошибок. Поэтому scaffold — не подготовка перед планом, а первый executable slice внутри плана.

В модуле 10 ты его только планируешь. Выполнять его нужно первым task уже в модуле 11.

У Slice 0 есть особенность: его expected diff — весь стартовый каркас проекта. Это единственный slice, где большой diff нормален. Дальше правило минимальный diff на задачу снова в силе.

Почему может быть несколько планов

План не обязан быть одним документом на весь проект. Для JobTrack держи 2 уровня:

docs/plan.md — общий порядок реализации MVP: срезы, зависимости, риски, проверки.

docs/todo.md — текущая рабочая очередь: что агент делает сейчас, что следующее, что уже закрыто.

docs/plan.md — куда идём в целом. docs/todo.md — какую одну задачу берём сейчас.

Если держать всё в одном чеклисте, документ быстро превращается в мусорную корзину: стратегия, текущая задача, заметки, идеи на потом и случайные правки вперемешку.

Ну такое. План и todo лучше разделить.

Атомарная задача

Атомарная задача — маленькая единица работы, которую можно отдать агенту без риска, что он перепишет половину проекта. У неё один результат, понятная граница diff, проверка, acceptance criteria и rollback/commit boundary.

Пример:

Task: показать empty state списка вакансий.

Результат:
- пользователь открывает JobTrack;
- видит пустой список и понятный текст.

Acceptance criteria:
- empty state виден на стартовой странице;
- текст не обещает поиск, импорт и аналитику;
- сценарий можно проверить локально.

Expected diff:
- только область стартового экрана;
- без хранения данных и статусов.

Rollback/commit boundary:
- изменения можно откатить отдельно от следующих задач.

Плохая атомарная задача:

Сделать весь первый MVP.

Это не задача. Это разрешение агенту переписать всё, до чего дотянется.

Как составить план через SPP

План собирай через workflow. Запрос сделай план в лоб даёт кашу — агент навалит всё сразу.

На этом этапе SPP ведёт тебя фазой plan-writing, внутри будет review плана через plan-review.

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

Модуль 11 — не новый заход, а следующая фаза того же pipeline.

Prompt:

Прочитай accepted docs/design.md.
Используй /spp и выбери подходящий workflow для планирования.
Если доступен planning/plan-writing workflow, используй его.

Задача: составить docs/plan.md для реализации MVP JobTrack.

Требования:
- опирайся только на accepted docs/design.md;
- не добавляй новые функции;
- не пиши код;
- не создавай scaffold;
- нарежь работу на vertical slices, а не на frontend/backend/database;
- выдели первый executable slice;
- задачи должны быть атомарными;
- у задач должны быть acceptance criteria, expected diff, проверка и rollback/commit boundary;
- отдельно отметь, какие проверки подтвердят первый slice в модуле 11, но не пиши тесты сейчас.

Если агент сразу предлагает писать код, его надо остановить:

Стоп. Сейчас модуль 10: только docs/plan.md и docs/todo.md.
Код начнётся в модуле 11 после принятого плана.

Что должно быть в docs/plan.md

Минимальная структура:

# Plan

## Source
- Accepted spec: docs/design.md
- Status: Спецификация принята: <дата>

## Goal
Первый проверяемый результат JobTrack.

## Vertical slices
### Slice 1. Добавление вакансии в список
- User result:
- Tasks:
- Acceptance criteria:
- Expected diff:
- Checks:
- Rollback/commit boundary:

### Slice 2. Сохранение после перезагрузки
- User result:
- Tasks:
- Acceptance criteria:
- Expected diff:
- Checks:
- Rollback/commit boundary:

## Risks
- Что может сломать план.
- Что надо проверить до реализации.

Этого достаточно для первого проекта. Не надо превращать план в проектный устав на 40 страниц.

Как сделать docs/todo.md

docs/todo.md можно собрать после docs/plan.md.

Prompt:

На основе docs/plan.md создай docs/todo.md.

Формат:
- current: ровно одна задача, которую можно дать агенту в модуле 11;
- next: следующие 2-3 задачи;
- done: пока пусто;
- backlog: следующие срезы из плана.

Не добавляй новые задачи, которых нет в docs/plan.md.
Не пиши код.

Если в current больше одной задачи, это плохой todo. Агент должен фокусироваться на одном ближайшем действии.

Проверки в этом модуле

Автотесты здесь не начинаются. В модуле 10 мы только планируем, какая проверка подтвердит первый slice в модуле 11.

Логика такая: сначала договорились, что считаем работающим, потом пишем ровно столько кода, чтобы это заработало.

Сейчас достаточно зафиксировать в плане:

• какую проверку сделать первой;
• какой ручной fallback годится, если тестовая инфраструктура ещё не готова;
• что считается успешной проверкой;
• и что пропущенные тесты не считаются успешной проверкой.

Как проверить план

План плохой, если начинается с frontend/backend/database, тащит обратно функции из out of scope, а первый срез нельзя запустить и показать. Плохой, если задачи нельзя выполнить по отдельности. Плохой, если нет acceptance criteria, expected diff, проверки, rollback/commit boundary — или todo живёт отдельно от plan.

Хороший план оставляет один вопрос: какую задачу взять в модуле 11 и как понять, что она готова.

Запреты модуля

В модуле 10 нельзя: создавать src/app/components, писать код, поднимать scaffold, деплоить, просить агента сделать весь MVP. И нельзя принимать план, нарезанный по слоям frontend/backend/database, как готовый.

Результат модуля — docs/plan.md и docs/todo.md.

Код начнётся дальше. Сейчас задача скучнее и важнее: не дать будущей реализации разъехаться на первом же шаге.

Цель практики — превратить принятую спецификацию в docs/plan.md и короткий docs/todo.md. Код не начинается. Сейчас скучный, но важный шаг: не дать реализации разъехаться ещё до первой строчки.

Шаг 1. Проверь вход

В docs/design.md должен быть статус:

Спецификация принята: <дата>

или:

Решение: принято перед планированием

Если этого нет, вернись в модуль 9. План без принятой спецификации снова превращает проект в гадание.

Шаг 2. Попроси SPP выбрать workflow

Prompt:

Прочитай accepted docs/design.md.
Используй /spp и выбери workflow для планирования.
Если доступен planning/plan-writing workflow, используй его.

Задача: подготовить docs/plan.md.

Не пиши код.
Не создавай scaffold.
Не создавай src/app/components.
Не деплой.

Если агент сразу начинает реализацию, останови:

Стоп. Сейчас только планирование.
Нужно составить docs/plan.md из accepted docs/design.md.
Код начнётся в следующем модуле.

Шаг 3. Создай docs/plan.md

Prompt:

На основе accepted docs/design.md создай docs/plan.md.

Требования:
- опирайся только на спецификацию;
- не добавляй новые функции;
- нарежь работу на vertical slices, а не на frontend/backend/database;
- первым сделай Slice 0: scaffold проекта и запуск dev server, это первый executable slice;
- задачи должны быть атомарными;
- у задач должны быть acceptance criteria, expected diff, checks и rollback/commit boundary;
- slices вместе должны покрывать все acceptance criteria из спецификации;
- запланируй первую проверку поведения для модуля 11, но не пиши тесты сейчас.

Минимальная структура:

# Plan

## Source
- Accepted spec: docs/design.md
- Status: Спецификация принята: <дата>

## Goal

## Vertical slices
### Slice 0. Scaffold и запуск dev server
- User result: приложение запускается локально, стартовый экран открывается в браузере.
- Tasks: создать проект выбранным в модуле 8 стеком; запустить dev server.
- Acceptance criteria: dev server стартует, страница открывается в браузере без ошибок.
- Expected diff: весь стартовый каркас проекта. Это единственный slice, где большой diff - норма.
- Checks: dev server открывается в браузере.
- Rollback/commit boundary: отдельный commit chore: scaffold проекта.

### Slice 1. ...
- User result:
- Tasks:
- Acceptance criteria:
- Expected diff:
- Checks:
- Rollback/commit boundary:

## Risks

Шаг 4. Проверь план

Попроси агента проверить план как ревьюер:

Проверь docs/plan.md как ревьюер.

Ищи только проблемы:
- план нарезан слоями frontend/backend/database;
- первый slice нельзя запустить и показать;
- нет Slice 0 со scaffold и запуском dev server;
- slices не покрывают все acceptance criteria из спецификации;
- задачи слишком крупные;
- появились функции из out of scope;
- нет acceptance criteria;
- нет expected diff;
- нет checks;
- нет rollback/commit boundary;
- план начал реализацию вместо планирования.

Верни замечания и точечные правки.
Код не пиши.

Если замечания есть, попроси внести правки только в docs/plan.md.

Шаг 5. Создай docs/todo.md из плана

Prompt:

На основе принятого docs/plan.md создай docs/todo.md.

Формат:
## current
- ровно одна первая задача - Slice 0: scaffold и запуск dev server

## next
- 2-3 следующие задачи (остаток Slice 0 и начало Slice 1)

## done
- пока пусто

## backlog
- следующие slices из docs/plan.md

Не добавляй новые задачи.
Не пиши код.

Если в current больше одной задачи, попроси исправить. В следующем модуле агент должен взять ровно одну задачу.

Шаг 6. Попроси агента подготовить commit

Git тоже делай через агента:

Проверь git status.
Покажи diff по docs/plan.md и docs/todo.md.
Убедись, что в diff нет кода, scaffold, src/app/components и deploy-настроек.
Если diff содержит только plan/todo, подготовь docs/plan.md и docs/todo.md к commit.
Покажи staged diff.
После моего подтверждения сделай commit с сообщением:
docs: составить план реализации MVP

Если в diff попал код, остановись и попроси убрать его из staged.