Спецификация: дизайн-документ

После модуля 8 у Бориса ещё нет спецификации.

Что уже собрано:

— docs/discovery.md с болью, сегментом и MVP; — docs/design.md с результатами brainstorming; — раздел Стек с выбранным техническим направлением; — с чего начинается локальная разработка.

Немало. Это ещё не документ, по которому можно планировать код.

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

Например:

Составь план реализации JobTrack по текущим документам.

На выходе не план, а аккуратная упаковка дыр: ещё не собрано в одно целое, а между кусками могут быть противоречия.

Штука в том, что документы лежат слоями. Discovery про боль, design draft про продуктовые решения, stack decision про технику — и между этими слоями сидят противоречия.

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

На вид всё готово.

Вот это и опасный момент.

Пока спецификация не принята явно, любая следующая задача возьмёт за основу один из этих кусков — какой попадётся. Агент не сломается — выберет один, уверенно пойдёт дальше. Разгребать потом тебе.

Короче, сначала один документ: MVP, данные, экраны, ограничения, критерии приёмки — сведённые в одну версию. Потом план.

Короче, перед планированием стоит спецификация. Скучная. И пропустить её нельзя.

После модулей 7–8 у тебя есть решения, но не обязательно есть цельная спецификация. А документа, из которого агент построит продукт, — ещё нет.

docs/design.md мог расти кусками: сначала brainstorming, потом стек, потом заметки после review. Вроде всё на месте. Но для планирования этого мало — агенту нужен один документ без противоречий: что строим, чего точно нет, какие экраны, какие данные, какие состояния гонять, где кончается MVP. Я сам собирал такую спеку по JobTrack — дыры полезли ровно в этих кусках, которые вроде на месте.

Это работа модуля 9.

Зачем нужна спецификация

Спецификация отвечает, что должно существовать. План — в каком порядке. Код — как это сделано. То есть три разных вопроса, и путать первый с третьим нельзя.

Если уйти в план без спецификации, агент начнёт планировать по обрывкам. Где-то MVP личный, где-то уже несколько пользователей. В одном разделе поиск вырезан, в другом снова торчит в экране. Стек выбран для локального старта — а acceptance criteria требуют публичный URL. Карточка вакансии показывает следующий шаг, но модель данных его не хранит.

Это не мелочи. Это будущий плохой код, просто пока в текстовом виде.

Плохая спецификация дешевле плохого кода. Текст правится за 10 минут. Код, выросший на противоречивом документе, чинится дольше и больнее.

Чем спецификация отличается от предыдущих этапов

Чем спецификация отличается от того, что было раньше? Discovery сказал, какая боль и для кого. MVP scope — какую минимальную проверку берём первой. Brainstorming — какие продуктовые развилки закрыли. Выбор стека — на чём стартуем локально. Спецификация сводит это в один документ перед планированием. Новый MVP она не придумывает. Фичи не добавляет. Её работа — свести уже принятые решения и найти дыры.

Для review пригодятся spec-review и иногда cross-spec-review, а сборку спецификации обычно ведёт spec-writing. Память SPP лежит в docs/spp/pipeline-state.md.

Как вызвать SPP для спецификации

И начинаю я не с документа вслепую. Сначала — проверка, какой SPP workflow вообще нужен. Промпт у меня примерно такой:

Ты работаешь над JobTrack.
Прочитай docs/discovery.md и docs/design.md.

Мы на этапе спецификации перед планированием.
Сначала проверь, какой SPP skill/workflow нужен.
Если есть /spp, используй его или объясни, почему выбираешь другой workflow.

Задача: собрать цельную спецификацию в docs/design.md,
потом провести review спецификации.

Не создавай docs/plan.md.
Не пиши код.
Не начинай реализацию.

Нормальный агент ответит примерно так:

Код не начинаю.
Сначала собираю спецификацию из docs/discovery.md и docs/design.md.
После этого нужен review: scope, UX/data/stack, скрытые допущения,
acceptance criteria и функции из out of scope.
Планирование пока запрещено.

А сорвавшийся — так:

Начну с плана реализации: создам задачи backend, frontend, database и deploy.

Это надо останавливать сразу. Агент перескочил спецификацию и уже поехал строить дом по салфетке.

Что должно войти в спецификацию

Что должно быть в docs/design.md? Минимум такой:

— цель MVP; — контекст и источники; — пользователь/сегмент; — pain; — что входит в MVP; — первый пользовательский сценарий; — in scope; — out of scope, включая не сейчас; — экраны/flows; — состояния empty/loading/error/success; — модель данных на уровне сущностей и полей; — Data ownership и JSON export; — выбранный стек и локальный старт; — ограничения; — открытые вопросы; — acceptance criteria; — Decision log.

Контекст тут не фон для красоты. Это список источников, из которых собрана спецификация: discovery, MVP scope, brainstorming, выбранный стек и ограничения. Не укажешь источник — агент начнёт спорить с прошлым решением и снова придумывать продукт с нуля.

Модель данных — пока не SQL-схема. Хватит вот такого:

Сущность: Вакансия
Поля:
- компания;
- роль;
- ссылка;
- источник;
- статус;
- следующий шаг;
- заметка.

Требует экран поле, которого нет в модели данных, — проблема спецификации. Держит модель сущность, которой нет в первом сценарии, — тоже проблема.

Prompt для сборки спецификации

Промпт на сборку:

Прочитай docs/discovery.md и docs/design.md.

Собери цельную спецификацию JobTrack в docs/design.md, не удаляя уже принятые решения из draft.
Используй только уже принятые решения и явно отмеченные открытые вопросы.
Не добавляй новые функции без связи с discovery. Экспорт данных уже был развилкой в модуле 7, поэтому раздел Data ownership и JSON export опирается на принятое там решение, а не вводит новое.

Структура:
1. Цель
2. Контекст и источники
3. Пользователь/сегмент
4. Pain
5. MVP
6. Первый сценарий
7. In scope
8. Out of scope
9. Экраны/flows
10. Состояния empty/loading/error/success
11. Модель данных: сущности и поля
12. Data ownership и JSON export
13. Стек и локальный старт
14. Ограничения
15. Открытые вопросы
16. Acceptance criteria
17. Decision log

После правки верни короткий список изменённых разделов и отдельно перечисли, какие решения из draft вошли в спецификацию, а какие не вошли и почему.
Не создавай docs/plan.md. Не пиши код.

Плохая и хорошая спецификация

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

JobTrack - приложение для управления поиском работы.
Будут карточки вакансий, статусы, теги, поиск, импорт,
уведомления, аккаунты и аналитика.
Стек: современный frontend и база данных.
Пользователь сможет удобно отслеживать всё.

Разберём. Нет связи с docs/discovery.md. Нет первого сценария. В scope вернулись теги, поиск, импорт, уведомления и аналитика. Стек не связан с решением модуля 8. Слово удобно ничего не проверяет. Ни состояний вроде empty/loading/error/success, ни модели данных, ни acceptance criteria.

Хорошая спецификация выглядит иначе. Рабочая версия — вот:

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

In scope:
- список вакансий;
- карточка вакансии;
- 4 статуса;
- источник, следующий шаг и заметка;
- ручной JSON export, чтобы пользователь мог забрать свои данные.

Out of scope:
- импорт;
- поиск;
- теги и сложные фильтры;
- аккаунты;
- аналитика.

Acceptance criteria:
- пользователь добавляет вакансию с компанией, ролью и ссылкой;
- вакансия появляется в списке;
- пользователь меняет статус;
- пользователь записывает следующий шаг;
- пользователь может сделать JSON export с version, timestamp и jobs;
- пустое состояние объясняет, что делать, если вакансий нет.

Видно, что строим, чего не строим и как понять, что первый сценарий готов.

Review спецификации

Готовый документ на глаз не принимается. Его ревьюят. Промпт на ревью:

Выступи ревьюером спецификации JobTrack.
Прочитай docs/discovery.md и docs/design.md.

Ищи только проблемы:
- противоречия между разделами;
- функции из out of scope или не сейчас;
- несостыковки UX/data/stack;
- скрытые допущения;
- термины без определения;
- acceptance criteria, которые не проверяют первый сценарий;
- места, где спецификация уже начала планировать реализацию.

Не предлагай новые фичи.
Верни список проблем, риск и точечную правку текста.

После ревью правки надо внести. Не отвечать ревьюеру в духе учту позже — позже это станет кодом.

Типовые противоречия JobTrack

Типовые проблемы JobTrack банальные, я на них уже наступал.

Теги, поиск и импорт снова оказались в экранах, хотя лежали в не сейчас. Гони их обратно в Out of scope и вон из экранов MVP.

Сложные фильтры вырезаны — а filter by source и sort by updatedAt вдруг стали обязательными. Либо в поздний slice, либо в backlog, но не в первый MVP.

localStorage выбран как локальный стек для личного старта — а спецификация уже про аккаунты, роли и несколько пользователей. Одно из двух: режем multi-user или пересматриваем стек до планирования.

Первый сценарий требует следующий шаг, а модель данных держит только статус. Добавляй source, следующий шаг и заметка — или честно признай, что сценарий другой.

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

До планирования

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

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

или:

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

Спецификация прочитана полностью, противоречия исправлены,
открытые вопросы вынесены отдельно. Планирование можно начинать
только от этой версии документа.

И только теперь — в модуль 10, превращать спецификацию в план.

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

В этом модуле ты не создаёшь docs/plan.md и не пишешь код. Результат — принятая спецификация в docs/design.md. Правило простое: не пиши код, пока спецификация не принята. Иначе агент начнёт реализовывать не решение, а туман.

Шаг 1. Проверь входные документы

Перед началом должны быть:

• docs/discovery.md;
• draft docs/design.md из модулей 7–8;
• в docs/design.md есть brainstorming-решения, не сейчас/out of scope и раздел Стек;
• код приложения ещё не начат.

Если нет docs/discovery.md, возвращайся к discovery. Если нет draft docs/design.md, возвращайся к brainstorming и выбору стека.

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

Напиши агенту:

Ты работаешь над моим MVP.
Прочитай docs/discovery.md и docs/design.md.

Мы на этапе спецификации перед планированием.
Сначала проверь, какой SPP skill/workflow нужен.
Если есть /spp, используй его или объясни, почему выбираешь другой workflow.

Задача: собрать цельную спецификацию в docs/design.md,
потом провести review спецификации.

Не создавай docs/plan.md.
Не пиши код.
Не начинай реализацию.

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

Стоп. Планирование и код запрещены.
Сейчас нужно собрать и отревьюить спецификацию в docs/design.md.

Шаг 3. Собери спецификацию

Prompt:

Прочитай docs/discovery.md и docs/design.md.

Собери цельную спецификацию в docs/design.md, не удаляя уже принятые решения из draft.
Используй только уже принятые решения и явно отмеченные открытые вопросы.
Не добавляй новые функции без связи с discovery.
В конце перечисли, какие решения из draft вошли в спецификацию, а какие не вошли и почему.

Структура:
1. Цель
2. Контекст и источники
3. Сегмент/пользователь
4. Pain
5. MVP
6. Первый сценарий
7. In scope
8. Out of scope
9. Экраны/flows
10. Состояния empty/loading/error/success
11. Модель данных: сущности и поля (`title`, `company`, `url`, `source`, `status`, `nextStep`, `notes`)
12. Data ownership и JSON export
13. Стек и локальный старт
14. Ограничения
15. Открытые вопросы
16. Acceptance criteria
17. Decision log

После правки верни короткий список изменённых разделов.
Не создавай docs/plan.md. Не пиши код.

Шаг 4. Проверь плохую и хорошую форму

Плохая спецификация:

• говорит общими словами;
• возвращает функции из не сейчас;
• не показывает первый сценарий;
• не описывает состояния;
• не связывает данные с экранами;
• не содержит acceptance criteria;
• начинает планировать реализацию.

Хорошая спецификация:

• опирается на docs/discovery.md;
• использует решения из модулей 7–8;
• явно разделяет In scope и Out of scope;
• описывает экраны, состояния и модель данных;
• фиксирует JSON export как способ забрать данные, если JobTrack хранит вакансии;
• фиксирует стек и локальный старт;
• acceptance criteria проверяют первый сценарий MVP;
• не создаёт docs/plan.md и не начинает код.

Если документ похож на плохую форму, попроси агента переписать:

Спецификация слишком общая и/или расширяет MVP.
Перепиши её только для первого MVP.
Опирайся на docs/discovery.md и уже принятые решения в docs/design.md.
Не возвращай функции из out of scope.

Шаг 5. Проведи review спецификации

Prompt:

Выступи ревьюером спецификации.
Прочитай docs/discovery.md и docs/design.md.

Найди проблемы:
- противоречия между разделами;
- возврат функций из не сейчас/out of scope;
- несостыковки UX/data/stack;
- скрытые допущения;
- термины без определения;
- acceptance criteria, которые не проверяют первый сценарий;
- места, где спецификация уже начала планировать реализацию.

Не предлагай новые фичи.
Верни список проблем, риск и точечную правку текста.
Не создавай docs/plan.md. Не пиши код.

Шаг 6. Попроси внести правки

Если review нашёл проблемы, дай агенту узкую задачу:

Внеси правки в docs/design.md только по замечаниям review.
Не добавляй новые функции.
Не создавай docs/plan.md.
Не пиши код.

После правки покажи список изменённых разделов.

Если review не нашёл проблем, запиши это в документ:

Review спецификации: замечаний нет.

Шаг 7. Прими спецификацию

В конце docs/design.md добавь один из вариантов:

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

или:

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

Спецификация прочитана полностью, противоречия исправлены,
открытые вопросы вынесены отдельно. Планирование можно начинать
только от этой версии документа.

После этого остановись. docs/plan.md появится только в следующем модуле.

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

Не делай Git руками, если работаешь через агента. Попроси его провести Git-шаг:

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

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