От идеи к MVP: гайд по spec-driven development

Спецификация, план, реализация и приёмка руками агента. Код — последний этап, а не первый.

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

Этап 0. Где вы сейчас и куда идёте

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

Главный соблазн этого этапа — открыть агента и написать: «Сделай мне приложение для учёта филаментов». Агент с радостью сгенерирует несколько тысяч строк кода. Проблема в том, что это будет его версия вашего продукта, а не ваша. Он додумает за вас все решения, которые вы не приняли: структуру данных, сценарии, интерфейс, технологии. Потом вы будете неделю пытаться «докрутить» это до того, что было у вас в голове, — и почти наверняка проиграете.

Мы пойдём другим путём — spec-driven development: сначала спецификация, потом план, и только потом код. Ключевая идея:

Код — это последний этап, а не первый. Каждый этап производит артефакт, и вы не переходите дальше, пока лично не прочитали и не утвердили этот артефакт.

Весь процесс выглядит так:

Идея (после discovery)
   │
   ▼
Этап 1. Спецификация ─────►  артефакт: полный дизайн-документ без противоречий
   │   (брейншторм → проверка свежим взглядом → декомпозиция → сверка кусков)
   ▼
Этап 2. Планирование ─────►  артефакт: план из атомарных задач
   │
   ▼
Этап 3. Реализация ───────►  артефакт: код + тесты, коммит после каждой задачи
   │
   ▼
Этап 4. Завершение ───────►  артефакт: работающий MVP, принятый по дизайн-документу

Прежде чем идти по этапам, три принципиальные вещи, без которых остальной гайд не сработает.

0.1. Superpowers — это не магия

Мы будем использовать Superpowers — плагин для кодинг-агентов. Важно сразу понять, что это такое: просто набор скиллов — текстовых инструкций, которые подсказывают агенту, как себя вести на каждом этапе. Никакого волшебства внутри нет. Вы можете зайти в репозиторий (https://github.com/obra/superpowers, папка skills/) и прочитать каждый скилл — это обычные markdown-файлы.

Что плагин на самом деле даёт:

систематизирует процесс — агент сам ведёт вас по этапам и отказывается писать код, пока нет утверждённого дизайна и плана;
страхует от типовых ошибок — «сначала код, потом подумаем», задачи-монстры, «всё работает» без тестов;
автоматизирует повторяющиеся действия — циклы TDD, коммиты, ревью между задачами.

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

0.2. Спецификация — самый важный этап

Запомните закон, который работает в каждой задаче этого месяца: время, вложенное в дизайн и спецификацию, вычитается из времени на отладку — с процентами.

С агентом есть два крайних способа работать:

Минимальная спека, максимум правок. Пишете два предложения, агент генерирует продукт, дальше бесконечное «нет, не так, переделай здесь». Каждая правка ложится на код, который вы не проектировали и не понимаете. Через несколько десятков итераций вы запутаетесь: код, ваши представления о продукте и реальное поведение продукта разойдутся в три разные стороны.
Максимум работы со спецификацией, потом реализация. Вы не пишете ни строчки кода, пока спецификация не описывает продукт полностью и без противоречий. Правки на этом этапе стоят секунды — это правки текста. Реализация после этого проходит быстро и предсказуемо.

Мы работаем по второму способу. Он кажется медленнее — первые два-три дня у вас «нет продукта, только документы». Но это иллюзия: вы просто переносите неизбежную работу по принятию решений туда, где ошибки дешевле всего исправлять.

0.3. Сначала проектируем целиком; потом цикл повторяется

Четыре этапа со схемы — «Спецификация → Планирование → Реализация → Завершение» — сейчас вы пройдёте один раз, для всего MVP. Но выучиваете вы их не на один раз: когда MVP заживёт и вы будете добавлять в него любую заметную фичу, вы прогоните тот же цикл в миниатюре — короткий брейншторм по фиче, правка спецификации, маленький план, реализация. Меняется масштаб, порядок — никогда.

Особенность первого прохода: прежде чем что-либо реализовывать, нужно спроектировать всё приложение целиком на уровне текста. Должен появиться «спецификационный продукт» — полное описание MVP без противоречий и серых зон; только с ним можно идти по плану и ничего не забыть. Одного брейншторма с агентом для этого недостаточно: он хорош, но вы вдвоём неизбежно что-то упустите. Поэтому в этап «Спецификация» встроены ещё два обязательных шага — проверка документа свежим чатом и декомпозиция на куски со сверкой их между собой; как именно — в разделах 3.5 и 3.6. Практический вывод: в этом месяце вы качаете два навыка, а не один — не только брейнштормить, но и декомпозировать.

И сразу договоримся о словах — дальше они используются строго в этих значениях:

Спецификация (она же дизайн-документ) — текстовое описание продукта: файл docs/design.md плюс детальные куски рядом. Два слова, один документ.
Кусок — часть спецификации про одну подсистему (модель данных, интерфейс…). Отвечает на вопрос «что это».
Подидея (она же фича) — крупный шаг реализации, вертикальный срез вроде «учёт катушек». Отвечает на вопрос «в каком порядке строить».
Задача — атомарный шаг на 2–5 минут внутри плана. Полный цикл проходят продукт и фичи; задачи просто выполняются.

Весь гайд построен на одном сквозном примере, и мы пройдём его от идеи до MVP.

1. Сквозной пример: FilaTrack

Идея после discovery. Локальное веб-приложение для владельцев 3D-принтеров: библиотека филаментов и настроек печати.

Пользователь. Человек с одним-двумя принтерами и десятком+ катушек дома.

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

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

Это всё, что у нас есть на входе. Заметьте: здесь нет ни структуры базы данных, ни списка экранов, ни выбора технологий. И это нормально — всё это появится на следующих этапах.

2. Подготовка (один раз)

Если git и GitHub для вас новые — честно закладывайте на подготовку полдня. Это нормально: всё здесь делается один раз.

2.1. Агент

Superpowers работает с большинством современных кодинг-агентов: Claude Code, Codex (CLI и приложение), Cursor, GitHub Copilot CLI, OpenCode и другими. Берите тот, с которым уже работаете. Промпты из этого гайда одинаково работают в любом агенте; различаются только установка плагина и интерфейсные мелочи (меню, слэш-команды) — такие места я буду оговаривать отдельно.

2.2. Проект — это папка

Базовая модель работы одинаковая и в Claude Code, и в Codex: проект = папка на вашем компьютере, и агент работает внутри неё.

Порядок действий такой:

Создайте пустую папку filatrack любым привычным способом: в проводнике/Finder, в диалоге выбора папки десктоп-приложения (кнопка «Новая папка») или командой mkdir filatrack в терминале.
Откройте её в агенте: десктоп Claude Code — выбрать эту папку; терминал — перейти в неё (cd filatrack) и запустить claude; Codex — «Создать проект» → указать эту папку.
Первым же промптом попросите агента подготовить структуру: Создай в проекте папку docs — там будут жить документы проекта.

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

Из этого следуют два правила. Первое: один продукт — одна папка, не смешивайте проекты. Второе: всё важное для проекта должно жить в этой папке в виде файлов — дизайн-документ, план, заметки. Чат с агентом — вещь эфемерная (контекст переполняется, сессии заканчиваются), а файлы в папке агент может прочитать в любой новой сессии. Это, кстати, главная причина, почему все артефакты этапов мы сохраняем в docs/, а не оставляем в переписке.

2.3. Установка Superpowers

Установка плагина — это действие пользователя, а не агента: агент не может установить плагин сам в себя, и в любом случае скиллы подхватываются только новой сессией.

Claude Code: наберите в чате команду
```
/plugin install superpowers@claude-plugins-official
```

и перезапустите сессию (новый чат).

Codex: откройте /plugins (в приложении — раздел Plugins в сайдбаре), найдите Superpowers, нажмите установить.
Другие агенты: инструкции в README репозитория https://github.com/obra/superpowers, раздел Installation — там расписано для каждого агента. Если инструкция непонятна, вставьте её текст агенту и попросите объяснить по шагам, что нажать, — но выполнять шаги придётся вам.

Проверка: в новой сессии напишите «какие скиллы Superpowers тебе доступны?» — агент должен перечислить brainstorming, writing-plans и остальные.

После установки ничего специально «включать» не нужно: скиллы срабатывают автоматически. Как только агент видит, что вы собираетесь что-то строить, он не бросается писать код, а начинает задавать вопросы — это и есть скилл brainstorming.

2.4. Git и GitHub: минимальный набор

Если вы никогда не работали с git — вот всё, что нужно знать на старте.

Git — это система контроля версий: программа, которая хранит историю изменений вашего проекта в виде «снимков» (коммитов). Каждый коммит — это зафиксированное состояние всех файлов плюс подпись, что и зачем изменилось. Зачем это вам:

Откат. Агент сделал шаг, который всё сломал? Возвращаетесь к предыдущему коммиту за секунды. Команду запоминать не обязательно — достаточно промпта: «Откати все изменения последней задачи, вернись к предыдущему коммиту» (под капотом это git revert или git reset). Без git неудачный шаг агента может стоить вам дня работы.
История решений. По коммитам видно, как рос продукт: «добавил модель катушки», «добавил списание веса». Это ваша страховка и ваша документация одновременно.
Контроль агента. Правило «коммит после каждой атомарной задачи» превращает работу агента из непрерывного потока изменений в цепочку проверяемых шагов.

GitHub — это сервис, где ваш репозиторий (проект с историей) хранится в облаке. Даже для локального проекта он нужен: резервная копия, доступ с любой машины, и агенты умеют с ним работать напрямую.

Порядок настройки:

Зарегистрируйтесь на https://github.com (бесплатный аккаунт).
Создайте репозиторий filatrack (кнопка New repository, можно приватный).
Настройте интеграцию на своей машине. Проще всего — через GitHub CLI: установите gh (https://cli.github.com), выполните gh auth login и следуйте подсказкам. После этого и вы, и агент можете отправлять изменения на GitHub без паролей.
Инициализируйте git в папке проекта и свяжите с GitHub — это можно попросить сделать агента: «Инициализируй git в этой папке и подключи к моему репозиторию filatrack на GitHub».

Два понятия, которые вам будут встречаться:

Коммит — сохранённый снимок изменений с описанием. В нашем процессе агент делает коммит после каждой атомарной задачи; git push отправляет коммиты на GitHub.
Пулл-реквест (PR) — предложение влить пачку изменений, оформленное так, чтобы её можно было просмотреть и обсудить перед принятием. Это основной инструмент командной работы; для сольного MVP он не нужен — достаточно знать, что это слово значит.

Пока работаем максимально просто: одна ветка (main), все коммиты — в неё. Ветки и пулл-реквесты понадобятся, когда над продуктом работает больше одного человека или идёт несколько направлений работы параллельно, — для сольного MVP это лишняя сложность. Если Superpowers предложит создать отдельную ветку или worktree — отвечайте «работаем в main».

2.5. Положите в репозиторий результаты discovery

У вас после недели discovery накопились разрозненные материалы: заметки с интервью, one-pager, описание MVP, наброски. Сначала сделайте их доступными агенту — любым из двух способов: скопируйте файлы в папку проекта (например, в docs/discovery-raw/ — обычным перетаскиванием в проводнике/Finder) или просто вставьте тексты прямо в чат. Затем попросите собрать всё в один документ:

Мои материалы с этапа discovery лежат в docs/discovery-raw/ (и часть
вставляю сюда текстом). Это не брейншторм продукта — решения пока не
принимаем и дизайн не обсуждаем. Просто задай уточняющие вопросы, если
в материалах чего-то не хватает, и собери всё в один связный документ —
пользователь, боль, гипотеза MVP. Сохрани его в docs/discovery.md.

Обратите внимание на границу: здесь мы только сводим факты discovery в одно место. Проектирование продукта — брейншторм дизайна — начнётся в этапе 1, и это отдельный разговор. Агент будет опираться на docs/discovery.md во время того брейншторма, и вам не придётся пересказывать контекст в каждой новой сессии.

2.6. Какая модель для чего

Если ваш агент позволяет выбирать модель (в Claude Code — команда /model, в Codex — переключатель модели в чате), правило простое: этапы 1–2 — спецификацию и план — делайте самой сильной моделью из доступных. Там принимаются все решения проекта, и ошибка модели стоит дорого. А вот реализацию по готовому подробному плану (этап 3) можно отдавать моделям попроще и подешевле — думать там уже почти не над чем, план всё решил. На первом проекте можно не заморачиваться и делать всё на одной модели, но запомните принцип «дорогая модель проектирует, дешёвая исполняет» — при регулярной работе он экономит заметные деньги.

3. Этап 1. Спецификация: из идеи — в полный дизайн-документ

Этот этап состоит из трёх шагов: брейншторм (3.1–3.4), проверка спецификации свежим взглядом (3.5) и декомпозиция со сверкой кусков (3.6). Первую версию дизайн-документа даст брейншторм, но этап закончится только после всех трёх шагов.

3.1. Брейншторм: что происходит

Скилл brainstorming превращает агента из генератора кода в дотошного собеседника. Он работает по сократическому методу: задаёт вопросы по одному, предлагает альтернативы, подрезает лишнее (принцип YAGNI — You Aren’t Gonna Need It) и в конце собирает всё в дизайн-документ, который показывает вам по секциям на утверждение.

Запуск — просто скажите агенту, что хотите построить:

Я хочу сделать локальное веб-приложение для учёта филаментов и настроек
3D-печати. Контекст discovery лежит в docs/discovery.md. Давай проработаем
дизайн MVP.

Скилл сработает сам — Superpowers активирует brainstorming, как только видит намерение что-то строить. Если агент всё же рванул писать код, остановите его и попросите явно: «Стоп. Используй скилл brainstorming из Superpowers — сначала прорабатываем дизайн».

3.2. Как выглядит диалог (сокращённо, на примере FilaTrack)

Ниже — реалистичный сокращённый диалог. Обратите внимание, какие решения вытаскивает агент: это ровно те решения, которые при «сделай мне приложение» он принял бы за вас молча.

Агент: Кто пользователь приложения — только вы на своей машине, или предполагается несколько пользователей с аккаунтами?

Вы: Только я, локально. Никаких аккаунтов.

Агент: Понял, это сильно упрощает MVP. Что для вас «филамент» как сущность? Например: PLA — это тип материала, «eSUN PLA+ чёрный» — конкретный продукт, а физическая катушка на полке — экземпляр. На каком уровне ведём учёт?

Вы: Хм. Мне важны физические катушки — их остаток. Но настройки печати одинаковые для всех катушек одного продукта.

Агент: Тогда предлагаю две сущности: «Филамент» (продукт: производитель, материал, цвет, диаметр) и «Катушка» (экземпляр филамента: начальный вес, текущий остаток). Профили печати привязываем к филаменту, а не к катушке. Так?

Вы: Да, именно так.

Агент: Как учитывать остаток на катушке? Варианты: (а) вручную — взвесили и ввели; (б) списание после каждой печати — вводите расход по данным слайсера; (в) интеграция с принтером. Вариант (в) для MVP явно избыточен.

Вы: Давай (а) и (б): и ручную корректировку, и списание расхода.

Агент: Профиль печати — это набор параметров под пару «филамент + принтер» или только под филамент? У вас один принтер?

Вы: Принтера два. Профиль — под пару «филамент + принтер».

Агент: Тогда нужна третья сущность «Принтер» (просто название и модель). Какие поля в профиле печати обязательны для MVP? Предлагаю минимум: температура сопла, температура стола, скорость, ретракт (длина/скорость), обдув, свободное поле для заметок. Остальное — в заметки.

Вы: Согласен. Ещё хочу пометку «проверенный профиль / экспериментальный».

Агент: Хорошо. Теперь про хранение: приложение локальное — предлагаю SQLite, один файл, без внешних сервисов. И про стек: есть предпочтения?

Вы: Я python-разработчик, давай FastAPI.

Агент: FastAPI + SQLite + серверные шаблоны (Jinja2) с HTMX для интерактивности — без отдельного фронтенд-фреймворка. Для MVP этого достаточно, и это на порядок меньше кода, чем React + API. Возражения?

Вы: Нет, отлично.

Агент: Последнее: чего точно НЕ будет в MVP? Предлагаю исключить: фотографии катушек, интеграцию со слайсером и принтером, парсинг G-code, импорт/экспорт, мультипользовательность, мобильное приложение.

Вы: Согласен. Экспорт в CSV хотелось бы…, но ладно, режем.

Отдельно про вопрос о стеке. В примере пользователь — python-разработчик, поэтому выбрал сам. Если вы не разработчик — не выбирайте. Ответьте так:

Я не разработчик. Выбери стек за меня по критериям: максимально
распространённые технологии (чтобы ты хорошо их знал и мало ошибался),
минимум движущихся частей, всё локально, легко запускать одной командой.
Объясни выбор в двух предложениях.

Агент предложит что-то консервативное и массовое — это ровно то, что нужно: на популярных стеках агенты ошибаются заметно реже.

И договорённость о код-листингах дальше по гайду (в примере дизайн-дока и в примере задачи из плана): их не нужно уметь писать — и даже читать построчно. Смотрите на них как на «что должно произойти»: тест = проверка «при создании катушки остаток равен начальному весу», модель = список полей катушки. Писать всё это будет агент; ваша работа — решения и проверки.

Диалог занимает 30–60 минут. Это самые дешёвые решения в проекте: изменить строчку в дизайн-документе — секунды, переделать готовую структуру БД — часы.

3.3. Ваша роль в брейншторме

Отвечайте честно, а не «как правильно». Агент предлагает варианты — выбирайте тот, который нужен вашему пользователю, а не тот, что звучит солиднее.
Режьте скоуп безжалостно. Каждое «а ещё было бы неплохо…» — минус день из вашего месяца. Правило: если фича не нужна для проверки гипотезы MVP — в раздел «Не входит».
Не соглашайтесь на то, чего не поняли. Если агент предлагает решение, а вы не понимаете, зачем оно, — спросите. «Ок» из вежливости вернётся к вам багом.

3.4. Артефакт этапа: дизайн-документ

В конце агент собирает документ и показывает его по секциям — прочитайте каждую. Для FilaTrack он выглядит примерно так (сокращённо):

# FilaTrack — дизайн MVP

## Цель
Локальное веб-приложение: учёт катушек филамента (с остатками)
и проверенных профилей печати под пары «филамент + принтер».

## Пользователь и сценарии
Один пользователь, локально. Ключевые сценарии:
1. Добавить филамент и катушку к нему.
2. Посмотреть список катушек с остатками; отфильтровать по материалу/цвету.
3. Списать расход после печати (или вручную скорректировать остаток).
4. Создать профиль печати для пары «филамент + принтер», пометить «проверен».
5. Перед печатью: найти филамент → увидеть его профили под нужный принтер.

## Модель данных
- Printer: id, name, model
- Filament: id, brand, material (PLA/PETG/ABS/TPU/other), color, diameter
- Spool: id, filament_id, initial_weight_g, remaining_weight_g, note
- PrintProfile: id, filament_id, printer_id, nozzle_temp, bed_temp,
  print_speed, retraction_length, retraction_speed, fan_speed,
  status (verified/experimental), notes

## Технологии
Python 3.12, FastAPI, SQLite (через SQLAlchemy), Jinja2 + HTMX, pytest.
Запуск одной командой, БД — один файл рядом с приложением.

## Не входит в MVP
Аккаунты и мультипользовательность, фото, интеграции с принтером
и слайсером, парсинг G-code, импорт/экспорт, мобильная версия.

## Риски
- Списание расхода по данным слайсера неточное → допускаем ручную
  корректировку остатка в любой момент.

Вы прочитали документ целиком, согласны с каждым разделом, раздел «Не входит в MVP» вызывает лёгкую боль (если не вызывает — вы вырезали мало). Сохраняем его в docs/design.md и коммитим. Но это первая версия, а не финал: вы с агентом только что час договаривались и наверняка что-то «замылили» вместе. Дальше — два обязательных шага проверки.

3.5. Проверка свежим взглядом

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

Я написал спецификацию продукта, она в docs/design.md. Посмотри на неё
критически: найди противоречия, серые зоны и узкие места. Не предлагай
новых фич — ищи проблемы в том, что уже описано. Потом обсудим по пунктам.

Для FilaTrack свежий взгляд находит, например, такое:

Сценарий 3 говорит «списать расход после печати», но не сказано, с какой катушки — а у одного филамента может быть несколько катушек. Как пользователь выбирает?

Остаток remaining_weight_g может уйти в минус при списании — это ошибка или допустимо (данные слайсера неточные)?

Что происходит с профилями при удалении принтера? Каскадное удаление или запрет?

«Фильтр по материалу/цвету» — цвет это свободный текст, фильтр по нему будет бесполезен при опечатках.

Каждый пункт обсуждаете, принимаете решение — и фиксируете его промптом:

По пункту 2 решение такое: остаток не может уйти ниже нуля; если списание
больше остатка — списываем в ноль и показываем предупреждение. Обнови
docs/design.md: внеси это в модель данных и в раздел «Риски». Покажи,
что именно поменял.

В документе после этого появляется конкретика вместо дыры, например:

- Spool.remaining_weight_g >= 0 всегда. Списание больше остатка
  обнуляет остаток и показывает предупреждение «списано больше,
  чем числилось — проверьте катушку».

Заметьте: любая из этих дыр, найденная на этапе кода, стоила бы часа отладки; здесь она стоит одну строчку текста.

3.6. Декомпозиция спецификации и сверка кусков

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

Декомпозируй спецификацию из docs/design.md на части (подсистемы/этапы)
так, чтобы каждую можно было проработать отдельно и ничего не потерять.
Сохрани список частей в docs/design/00-parts.md.

00-parts.md — это просто оглавление. Для FilaTrack оно выглядит так:

# Куски спецификации FilaTrack
1. 01-data-model.md — модель данных и правила целостности
2. 02-spools.md    — учёт катушек и списание
3. 03-profiles.md  — профили печати
4. 04-ui.md        — интерфейс: страницы и навигация
5. 05-search.md    — поиск и фильтры

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

Общая спецификация — в docs/design.md, список кусков — в docs/design/00-parts.md.
Сейчас углубляем кусок «Интерфейс: страницы и навигация». Проведи брейншторм
только по нему: задавай вопросы по одному, предлагай варианты. Не выходи
за границы куска. Результат сохрани в docs/design/04-ui.md.

На куске «интерфейс» всплывут вопросы, которых не было в общем документе: какие страницы существуют, что на главной, откуда доступно списание. На куске «модель данных» — точные правила. Вот фрагмент готового 01-data-model.md, чтобы был понятен уровень детализации:

# 01. Модель данных и правила целостности (фрагмент)
- Spool.remaining_weight_g всегда >= 0. Списание больше остатка
  обнуляет остаток и показывает предупреждение.
- Filament нельзя удалить, пока существуют его Spool или PrintProfile.
- Цвет филамента — выбор из фиксированного списка (12 базовых цветов),
  плюс свободное поле «оттенок» для уточнения.
- Диаметр — только 1.75 или 2.85 мм (выпадающий список, не свободный ввод).

Сравните с общим документом из 3.4: там про цвет была одна строка color, здесь — правило, по которому можно писать код и фильтры. Это самая долгая часть этапа — по 15–30 минут на кусок, — и именно она делает спецификацию пригодной для реализации.

И финальный шаг, который чаще всего пропускают:

Возьми все части спецификации, сравни их друг с другом и с общим
документом. Найди места, где они противоречат друг другу, и стыки,
которые не описаны ни в одной из частей.

Как выглядит ответ сверки для FilaTrack:

02-spools vs 04-ui: списание в 02 описано «на странице катушки», в 04 кнопка списания нарисована на главной. Противоречие.

05-search vs 01-data-model: фильтр по цвету в 05 предполагает точное совпадение, 01 разрешает свободное поле «оттенок» — фильтр по оттенку работать не будет. Серая зона: участвует ли оттенок в поиске?

Не описано нигде: что видит пользователь, когда катушек ещё нет (пустое состояние главной страницы).

Каждый стык закрываете тем же способом, что и в 3.5, — решение плюс промпт фиксации:

Решение по стыку 1: ввод списания живёт на странице катушки, на главной —
только ссылка «списать» у каждой катушки, ведущая туда же. Обнови
02-spools.md и 04-ui.md, чтобы они совпадали, и docs/design.md, если он
затронут. Покажи, что поменял.

Стыки — главное место обитания багов. Пока такие расхождения есть — спецификация не готова.

Правило выхода с этапа: общий дизайн-документ и все куски согласованы между собой, серых зон не осталось, всё закоммичено в docs/. У вас на руках «спецификационный продукт» — полное описание MVP, по которому можно строить, ничего не додумывая. Только теперь этап 1 закончен.

4. Этап 2. Планирование: подидеи и атомарные задачи

Дизайн отвечает на вопрос «что строим». План отвечает на вопрос «в каком порядке и какими шагами». Это два разных уровня декомпозиции.

4.1. Уровень 1: разбить продукт на подидеи

Сначала MVP режется на крупные функциональные блоки — подидеи. Хорошая подидея — это вертикальный срез: законченный кусок функциональности, который можно открыть в браузере и потрогать. Плохая подидея — горизонтальный слой («сделать весь бэкенд», «сделать весь UI»): после неё потрогать нечего.

Нарезку делает агент, вы — обсуждаете и утверждаете:

Спецификация готова: docs/design.md + куски в docs/design/. Разбей MVP
на подидеи — вертикальные срезы в порядке реализации. Требования: каждая
подидея опирается только на предыдущие; после каждой приложение можно
запустить и потрогать руками; последняя — «запуск и README». Предложи
разбиение здесь в чате с одной строкой пояснения на подидею — обсудим,
прежде чем писать детальный план.

Предложение агента вы правите обычным разговором («объедини 2 и 3», «поиск слишком рано, перенеси в конец») — утверждённый список станет каркасом плана на следующем шаге. Для FilaTrack после пары таких итераций подидеи выглядят так:

Каркас — приложение запускается, БД создаётся, есть пустая главная страница.
Принтеры и филаменты — CRUD двух справочников.
Катушки — добавление катушек, список с остатками.
Списание расхода — списать вес после печати, ручная корректировка.
Профили печати — создание профиля под пару «филамент + принтер», статус «проверен».
Поиск и фильтры — фильтр катушек по материалу/цвету, профили на странице филамента.
Запуск и README — установка и старт одной командой, короткая инструкция «как пользоваться».

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

Чем подидеи отличаются от кусков спецификации из шага 3.6? Куски отвечают на вопрос «что это за продукт» и режутся по подсистемам (модель данных, интерфейс) — так удобно проектировать. Подидеи отвечают на вопрос «в каком порядке строить» и режутся вертикально — так удобно реализовывать. Одна подидея обычно тянет знания из нескольких кусков: «Катушки» опирается и на модель данных, и на интерфейс, и на кусок про списание. Это не дублирование, а два разреза одного продукта.

4.2. Уровень 2: атомарные задачи (скилл `writing-plans`)

Дальше агент (скилл writing-plans) разворачивает каждую подидею в план из задач. Требование Superpowers жёсткое: план должен быть написан так, чтобы его мог выполнить «энергичный джуниор без вкуса, без контекста проекта и с нелюбовью к тестам». На практике это значит, что каждая задача:

занимает 2–5 минут работы агента;
указывает точные пути файлов;
содержит готовый код, включая падающий тест, а не псевдокод;
заканчивается проверкой и коммитом.

Запуск:

Дизайн утверждён: общий документ — docs/design.md, детальные куски —
в docs/design/. Напиши план реализации по подидеям, с опорой на куски.
Сохрани план в docs/plan.md.

Вот как выглядит одна задача из плана FilaTrack (подидея «Катушки»; фикстуры db_session и make_filament созданы предыдущими задачами — план всегда опирается только на уже сделанное):

### Задача 3.2: Модель Spool и создание катушки

**Файлы:** app/models.py, tests/test_spools.py

**Шаг 1 — падающий тест** (tests/test_spools.py):
def test_create_spool_sets_remaining_to_initial(db_session):
    filament = make_filament(db_session)
    spool = Spool(filament_id=filament.id, initial_weight_g=1000)
    db_session.add(spool); db_session.commit()
    assert spool.remaining_weight_g == 1000

**Шаг 2 — проверить, что тест падает:** pytest tests/test_spools.py -x
Ожидаем: FAILED (модели Spool не существует).

**Шаг 3 — реализация** (app/models.py):
class Spool(Base):
    __tablename__ = "spools"
    id = Column(Integer, primary_key=True)
    filament_id = Column(ForeignKey("filaments.id"), nullable=False)
    initial_weight_g = Column(Integer, nullable=False)
    remaining_weight_g = Column(Integer, nullable=False)
    note = Column(String, default="")

    def __init__(self, **kwargs):
        # при создании остаток равен начальному весу (см. design: 01-data-model)
        kwargs.setdefault("remaining_weight_g", kwargs.get("initial_weight_g"))
        super().__init__(**kwargs)

**Шаг 4 — проверить, что тест проходит:** pytest tests/test_spools.py -x

**Шаг 5 — коммит:** git commit -am "Add Spool model with remaining weight"

Таких задач в плане FilaTrack будет 25–40. Это нормально: маленькие задачи — это то, что не даёт агенту уйти в самодеятельность. Сразу откалибруем ожидания по времени: 25–40 задач по 2–5 минут — это от одного до трёх-четырёх часов чистой работы агента. Но календарно реализация займёт дни, и это не потому что «что-то идёт медленно»: время уходит на чекпоинты, ручные проверки продукта, найденные дыры в дизайне и отладку. Так и задумано — если агент отработал план за пару часов, вы ничего не пропустили.

Когда план готов, заведите файл статуса — docs/todo.md:

План лежит в docs/plan.md. Выпиши его в docs/todo.md в виде чеклиста:
подидеи и их задачи. После каждого выполненного шага отмечай его в этом
файле. Если план меняется — сначала обнови docs/plan.md, затем todo.md,
потом продолжай.

Разделение ролей между файлами простое: plan.md — источник правды (что и как делаем, с кодом и шагами), todo.md — компактный статус поверх него (что сделано, что дальше). При любом расхождении прав plan.md, а todo.md перегенерируется из него. Зачем нужен отдельный статус: он переживает любую сессию — контекст переполнился, чат закрылся, сели за другую машину — открываете новый чат, агент читает todo.md и точно знает, где вы остановились. И вы сами в любой момент видите реальный прогресс, а не «вроде уже много сделали».

4.3. Проверка атомарности

Здесь важно разделить две разные проверки. Атомарность (формальные критерии ниже) — механическая работа, её отдаём агенту. Понятность — понимаете ли вы сами каждую задачу — не делегируется никому: это ваша проверка из правила выхода. Атомарность агент проверяет так, лучше в свежем чате:

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

Сами критерии всё же знать нужно — чтобы понимать, что агент проверяет, и глазами ловить явные проблемы:

[] Задача описывает одно проверяемое изменение. Если в формулировке есть «и» («создать модель и страницу и фильтры») — почти наверняка это 2–3 задачи.
[] Понятно, как проверить, что задача выполнена (тест, команда, что увидеть в браузере).
[] Указаны конкретные файлы.
[] Задача не зависит от решений, которые ещё не приняты («сделать красиво», «выбрать подходящую библиотеку» — это не задачи, это несделанный брейншторм).
[] Задачу можно закоммитить отдельно, и проект останется рабочим.

Антипример: задача «Сделать управление катушками». Что тут проверять? Какие файлы? Это подидея, а не задача, — её место на уровне 1.

Что значит «понимать задачу», если вы не читаете код: вы можете сказать своими словами, что задача меняет в продукте и зачем. Для задачи 3.2 из примера это «после неё в системе появляются катушки, и у новой катушки остаток равен её начальному весу». Если по формулировке в плане так сказать не получается — не пропускайте, спросите:

Объясни задачу 3.2 из docs/plan.md простыми словами, без кода: что она
меняет в продукте, какое решение из спецификации реализует и как я
своими глазами увижу, что она сделана.

Если и после объяснения задача не складывается в голове — это дефект плана, а не ваш: просите переформулировать или разбить.

Правило выхода с этапа: агент проверил атомарность, а вы прочитали план и понимаете каждую задачу — в смысле, описанном выше. Это ключевой момент: если задача непонятна вам, агент сделает не то — просто уверенно. docs/plan.md и docs/todo.md закоммичены.

5. Этап 3. Реализация

Только теперь — код. Заметьте, что к этому моменту сделана бо́льшая часть интеллектуальной работы, и именно поэтому реализация пройдёт быстро.

Если пользуетесь переключением моделей (раздел 2.6) — сейчас тот самый момент перейти на модель попроще: все решения уже приняты планом.

5.1. Git-дисциплина

Как договорились в разделе 2.4, работаем в одной ветке main (и так же отвечаем Superpowers, если он предложит ветку или worktree). Два ритуала. Первый: коммит после каждой атомарной задачи — это делает агент сам, по плану. Второй: в конце каждой рабочей сессии — ваш промпт: «Закоммить всё несохранённое и запушь на GitHub». Страховка работает только так: частые коммиты локально, свежая копия в облаке.

5.2. Два режима выполнения

executing-plans — агент выполняет задачи батчами и останавливается на чекпоинтах, ожидая вашего решения. Для первого проекта берите этот режим: вы видите каждый шаг и учитесь на процессе.
subagent-driven-development — на каждую задачу запускается свежий субагент, результат проходит двухступенчатое ревью (сначала соответствие плану, потом качество кода). Агент может работать автономно часами. Это режим для следующих проектов, когда процесс станет привычным и вы будете уверены в качестве своих планов.

Запуск:

План утверждён, он в docs/plan.md. Выполняй по плану, режим
executing-plans, чекпоинт после каждой подидеи.

Как выглядит чекпоинт: агент останавливается и отчитывается — какие задачи выполнены, что показали тесты, что изменилось в todo.md. Ваши действия на чекпоинте, по порядку:

Прочитать отчёт: все ли задачи подидеи закрыты, нет ли «сделал по-другому, потому что…» (это красный флаг — см. 5.5).
Запустить приложение и руками проверить сценарий этой подидеи (как — в 5.4).
Заглянуть в docs/todo.md: отметки соответствуют реальности?
Дать решение — одним из трёх промптов: «Продолжай следующую подидею»; «Стоп. [что именно не так, например: форма добавления катушки не сохраняет данные]. Найди корневую причину, доложи — код пока не меняй»; «Откати задачу N до предыдущего коммита, обсудим».

Чекпоинт — это 5–10 минут. Не превращайте его в формальность: это единственное место, где вы контролируете продукт, а не отчёты о нём.

5.3. TDD: почему это не опционально

Каждая задача выполняется в цикле RED–GREEN–REFACTOR: написать падающий тест → увидеть, что он падает → написать минимальный код → увидеть, что тест проходит → закоммитить. Superpowers принуждает к этому (скилл test-driven-development) вплоть до того, что код, написанный до теста, удаляется.

С агентами TDD важнее, чем с людьми, по простой причине: тест — это спецификация, которую нельзя заболтать. Агент может убедительно рассказать, что «всё работает». Падающий тест с ним не спорит — он просто красный.

5.4. Ваша роль во время реализации

Вы — не зритель, вы — тимлид у агента-джуниора:

На каждом чекпоинте запускайте приложение руками. На первом же чекпоинте (после «Каркаса») спросите: «Как мне запустить приложение и посмотреть его в браузере? Запиши команду запуска в README.md». Для FilaTrack это будет что-то вроде uvicorn app.main:app и адрес http://localhost:8000. Дальше после каждой подидеи: запустили, открыли браузер, прошли сценарий («Катушки» — добавьте катушку, посмотрите на остаток). Тесты зелёные — это хорошо, но продукт вы принимаете глазами.
Пресекайте расширение скоупа. Агент по дороге предложит «заодно» добавить пагинацию, тёмную тему и кэширование. Стандартный ответ: «Идея хорошая, но не сейчас: запиши её в docs/backlog.md и продолжай по плану» — файл агент создаст при первом же таком случае. После MVP backlog станет сырьём для следующих циклов.
Если что-то сломалось — не «попробуй ещё раз». Скилл systematic-debugging ведёт агента через поиск корневой причины вместо случайного перебора правок. Требуйте: «найди корневую причину, потом чини».
Между задачами работает ревью (скилл requesting-code-review). Как это выглядит: после задачи или пачки задач агент сверяет сделанное с планом и докладывает найденные проблемы по серьёзности; критичные блокируют движение дальше, пока не исправлены. От вас ничего специального не требуется — только не саботировать: не просите «пропусти ревью, времени мало» и не отвечайте «продолжай» на доклад с критичной проблемой. Это единственные два способа его «отключить».

5.5. Если реализация уткнулась в дыру в дизайне

Это случится — и это нормально: даже после сверки кусков что-то всплывает только на живом продукте. Не решайте это молча в коде — вернитесь на шаг назад, в брейншторм. Разберём на конкретной ситуации.

Идёт подидея «Профили печати». Агент спрашивает (или вы сами замечаете на чекпоинте): а может ли у пары «филамент + принтер» быть несколько профилей — например, черновой для быстрой печати и качественный? В дизайн-документе про это ни слова. Что делаете:

Останавливаете реализацию. Говорите агенту: «Стоп, это дыра в дизайне, код пока не трогаем».

Короткий брейншторм по дыре — прямо промптом:

Открой docs/design.md, раздел про профили печати. Мы не решили: может
ли у пары «филамент + принтер» быть несколько профилей? Давай короткий
брейншторм: предложи 2–3 варианта с плюсами и минусами для MVP.

Принимаете решение. Скажем: да, профилей может быть несколько, у каждого — название («черновой», «качество»); уникальность пары не нужна.
Фиксируете в документах: «Обнови docs/design.md этим решением. Проверь, затрагивает ли оно задачи в docs/plan.md и docs/todo.md, — если да, поправь их и покажи мне диф».
Только теперь продолжаете реализацию.

Весь цикл занимает 5–10 минут. Дорого стоит не он, а его пропуск: решение, принятое молча в коде, не существует ни в дизайне, ни в плане — и следующая же задача, опирающаяся на старое понимание, начнёт ему противоречить. Дизайн-документ должен оставаться правдой о продукте.

6. Этап 4. Завершение и приёмка MVP

В Superpowers за завершение отвечает скилл finishing-a-development-branch, но он рассчитан на работу в отдельной ветке (проверить тесты, предложить merge или PR, прибрать worktree). Мы работаем в main, поэтому финал у нас проще и делается одним промптом: «Все задачи плана выполнены. Прогони весь тестовый набор, сверь docs/todo.md с реальностью, проверь, что всё закоммичено, и запушь на GitHub».

Дальше проведите приёмку против дизайн-документа — вручную пройдите каждый сценарий из раздела «Пользователь и сценарии»:

Добавил филамент eSUN PLA+ чёрный и катушку 1000 г? ✓
Вижу список катушек с остатками, фильтр по PLA работает? ✓
Списал 63 г после печати — остаток 937 г? ✓
Создал профиль для пары «eSUN PLA+ / Ender 3», пометил «проверен»? ✓
Открыл филамент — вижу его профили под каждый принтер? ✓

Definition of Done для MVP: все сценарии из дизайн-документа проходятся руками, все тесты зелёные, приложение ставится и запускается по README (за README и запуск одной командой отвечала подидея 7 — если её пропустили, сейчас самое время). «По README» значит: на машине с установленным Python и git, но без вашего проекта, инструкция из README приводит к работающему приложению — и ничего сверх написанного делать не приходится.

Проверьте это честно, не выходя из агента: «Склонируй репозиторий с GitHub в отдельную временную папку и выполни установку и запуск строго по README, ничего не додумывая. Если застрянешь — это баг README, скажи где».

После этого MVP готов, и вы возвращаетесь к тому, ради чего всё затевалось: отдать продукт пользователям и проверять гипотезу.

7. Типичные ошибки — и как они выглядят в жизни

Пропустить брейншторм: «я и так всё знаю». Как выглядит: студент пишет «сделай трекер филаментов», агент за вечер выдаёт приложение — с учётом по типам материала, без катушек. Пользователю нужны катушки и остатки. Переделка структуры БД и всего, что на ней висит, съедает три дня — больше, чем стоили бы все брейнштормы вместе.
Утверждать секции дизайна не читая. Как выглядит: на секции «модель данных» вы нажали «ок» не глядя, там профиль привязан только к филаменту. На реализации профилей выясняется, что для двух принтеров нужны разные температуры — а «ок» на однопринтерную модель дали вы сами. Возврат в дизайн, правка модели, перегенерация трёх задач.
Остановиться на первой версии спецификации. Как выглядит: сверку кусков пропустили. Кусок «списание» считает, что расход вводится на странице катушки; кусок «интерфейс» нарисовал ввод на главной. Агент реализовал оба — в продукте два разных способа списания, которые по-разному округляют вес. Нашли через неделю, когда остатки перестали сходиться.
Крупные задачи в плане. Как выглядит: задача «сделать страницу катушек» на 40 минут агентской работы. Внутри агент сам решил добавить пагинацию, сортировку и модалку подтверждения — 600 строк, из которых треть не нужна, а тест один. Ревью такой пачки занимает дольше, чем заняло бы разбиение на пять задач.
Разрешать «заодно». Как выглядит: агент предложил «заодно добавить график расхода по месяцам», вы ответили «давай». Графика нет ни в дизайне, ни в плане; через два дня он ломается на катушках без истории — и никто, включая вас, не помнит, как он должен себя вести. Правильный ответ был: «в docs/backlog.md».
Пропускать чекпоинты и не запускать продукт руками. Как выглядит: четыре подидеи подряд «тесты зелёные, продолжай». На пятой открыли браузер впервые — форма добавления катушки не отправляется, сломана ещё со второй подидеи: тесты проверяли API, а кнопку не проверял никто. Откапывать, где именно сломалось, приходится через четыре подидеи кода.
Менять дизайн молча посреди реализации. Как выглядит: в чате реализации вы на ходу сказали «пусть остаток можно редактировать прямо в списке». Агент сделал. В design.md по-прежнему написано «редактирование на странице катушки», план опирается на старую версию, следующая задача перезаписывает вашу правку. Три источника правды, все разные.
Работать без коммитов. Как выглядит: агент три часа «улучшал» списание без единого коммита, в процессе сломал модель катушек. Откатиться некуда — последний коммит был до начала работы. Вечер уходит на археологию вместо одной команды отката.

8. Чеклист всего процесса — с промптами запуска

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

Подготовка (после создания папки, установки Superpowers и gh auth login)

Создай папку docs. Инициализируй git и подключи к моему репозиторию
filatrack на GitHub. Сырьё discovery — в docs/discovery-raw/: собери из
него сводный docs/discovery.md (пользователь, боль, гипотеза MVP), задав
мне вопросы, если чего-то не хватает. Решения о продукте не принимаем.

[] Папка проекта создана (внутри — docs/), агент работает в ней
[] Superpowers установлен: в новой сессии агент перечисляет его скиллы
[] Аккаунт на GitHub, репозиторий создан, gh auth login пройден
[] git инициализирован в папке и связан с репозиторием на GitHub
[] Сырьё discovery — в docs/discovery-raw/, сводный docs/discovery.md собран агентом

Этап 1 — Спецификация (три шага — три промпта, шаги 2 и 3 в новых чатах)

1. Я хочу сделать [продукт]. Контекст discovery — в docs/discovery.md.
   Давай проработаем дизайн MVP. Результат сохрани в docs/design.md.

2. Спецификация в docs/design.md. Найди противоречия, серые зоны и узкие
   места — не предлагая новых фич. Обсудим по пунктам.

3. Декомпозируй docs/design.md на части, список — в docs/design/00-parts.md.
   [затем по куску за чат: «углубляем кусок N ...»; в конце — сверка кусков]

[] Прошёл брейншторм: пользователь, сущности, сценарии, стек, границы MVP
[] Раздел «Не входит в MVP» заполнен и слегка болит
[] Спецификация проверена свежим чатом: противоречия и узкие места разобраны
[] Спецификация декомпозирована на куски, каждый кусок проштурмлен отдельно
[] Куски сверены друг с другом, серых зон на стыках нет
[] Всё лежит в docs/, прочитано целиком, закоммичено

Этап 2 — Планирование

Спецификация готова: docs/design.md + куски в docs/design/. Сначала
предложи разбиение MVP на подидеи (вертикальные срезы, последняя —
«запуск и README») — обсудим. После утверждения напиши детальный план
в docs/plan.md и выпиши его чеклистом в docs/todo.md.

[] MVP разбит на подидеи — вертикальные срезы в правильном порядке
[] Каждая подидея развёрнута в задачи по 2–5 минут
[] План проверен на атомарность (агентом в свежем чате)
[] План выписан в docs/todo.md, агент отмечает в нём выполненное
[] docs/plan.md понятен вам, утверждён, закоммичен

Этап 3 — Реализация

План утверждён, он в docs/plan.md. Выполняй по плану, режим
executing-plans, чекпоинт после каждой подидеи. Работаем в main,
коммит после каждой задачи, todo.md обновляй по ходу.

[] Работаем в main: коммит после каждой задачи, push в конце сессии
[] Режим executing-plans, чекпоинт после каждой подидеи
[] TDD и код-ревью между задачами не отключены
[] На каждом чекпоинте продукт запущен и потроган руками
[] Все «заодно» отправлены в docs/backlog.md

Этап 4 — Завершение

Все задачи плана выполнены. Прогони весь тестовый набор, сверь
docs/todo.md с реальностью, проверь, что всё закоммичено, и запушь
на GitHub. Затем склонируй репозиторий во временную папку и выполни
установку и запуск строго по README — застрянешь, значит баг README.

[] Все тесты зелёные, всё закоммичено и запушено на GitHub
[] Все сценарии дизайн-дока пройдены вручную
[] Установка и запуск по README проверены на чистом клоне репозитория

9. Ориентировочная раскладка на 3 недели

Время	Что делаем
День 1	Подготовка (агент, Superpowers, GitHub) + брейншторм → первая версия дизайн-документа
День 2	Проверка свежим чатом + декомпозиция спецификации + сверка кусков
День 3	Планирование: подидеи → атомарные задачи
Дни 4–10	Реализация по подидеям, чекпоинт = конец подидеи
Дни 11–12	Приёмка по дизайн-доку, фиксы, проверка README на чистом клоне
Оставшееся время	Продукт у пользователей, сбор обратной связи

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

Полезные ссылки

Репозиторий Superpowers (установка, полный список скиллов): https://github.com/obra/superpowers
Оригинальный анонс методологии от Джесси Винсента: https://blog.fsck.com/2025/10/09/superpowers/

Гайд закрывает середину пути: спецификацию, план и реализацию. Полный маршрут — от сырой идеи до задеплоенного продукта и защиты перед живыми людьми — мы проходим за шесть недель на курсе по созданию AI-продукта.