Урок 17.6. Brainstorming: дизайн до кода и маршруты задач

Дополнительные источники: https://mokevnin.github.io/agentic-coding-design-patterns/ru/superpowers.html (раздел о маршрутах), https://lzw.me/docs/opencodedocs/obra/superpowers/core-workflows/design-workflow/index.html

Зачем это нужно

Это первый из семи шагов базового workflow (уроки 17.5 и 17.1) и самый нагруженный скилл Superpowers: именно здесь решается, сколько процесса нужно задаче, — а значит, сколько времени вы потратите. Ошибка классификации на этом шаге — либо церемония на правку двух строк, либо код без дизайна на новую подсистему.

Глава книги «Agentic Design Patterns» описывает этот скилл через маршруты spike/bounded/architectural — различие, которое README не выделяет, но которое составляет половину практической ценности скилла. Здесь маршруты разобраны по первоисточнику skills/brainstorming/SKILL.md, с уточнениями из главы книги.

Основная идея

Скилл brainstorming активируется перед любой творческой работой (создание фич, компонентов, функциональности, изменение поведения) и превращает идею в согласованный дизайн через диалог. Скилл начинается не с вопросов, а с классификации: сколько процесса нужно запросу. Классификация объявляется вслух — «похоже, это bounded, поэтому я предъявлю короткий дизайн в чате, а не буду писать спеку» — чтобы вы могли ее переиграть. Дальше — один из трех маршрутов, каждый со своим набором артефактов и своей контрольной точкой согласования (HARD-GATE).

flowchart TD A["Классификация запроса (объявить вслух)"] --> B{"Маршрут"} B -->|"спайк-проверка идеи"| C["spike: вопрос + план эксперимента, 2-3 предложения"] B -->|"правка существующего кода"| D["bounded: краткий дизайн в чате"] B -->|"новая подсистема / связи"| E["architectural: спецификация + план"] C --> F["Согласование вопроса/эксперимента"] D --> G["Явное «да» дизайну"] E --> H["Ревью спеки → план → согласование способа исполнения"] F --> I["Эксперимент → рекомендация"] G --> J["Реализация (обычный workflow, TDD)"] H --> K["writing-plans → исполнение"]

Установление общего понимания

Результат brainstorming — понимание, которое ваш партнер (в терминах скилла вы — «human partner») может опознать и поправить. Три шага скилла:

Выяснить намерение. По запросу и контексту определить желаемый результат, для кого он и как выглядит успех. Если информации нет — один сфокусированный вопрос о цели или предполагаемом использовании до предложения фич. Знать жанр приложения — не значит знать, зачем партнеру этот замысел.
Переписать понимание своими словами. Краткая заметка: желаемый результат, ограничения, критерии успеха — так, чтобы партнер мог ее оценить. Отделить сказанное им от предположений и пригласить к поправкам.
Пронести намерение в дизайн. Согласованное понимание сохраняется в артефакте маршрута: письменной спеке (architectural), дизайне/пробе в чате (bounded, spike). Каждая предлагаемая фича и техническое решение сверяется с этим пониманием.

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

HARD-GATE: ворота перед реализацией

Ключевой блок скилла (перевод с сохранением структуры оригинала):

<HARD-GATE>
Перед любым действием по реализации — включая вызов имплементационного
скилла, написание кода продукта, скаффолдинг, установку зависимостей
продукта или создание внешнего проекта — выполните пререквизиты
выбранного маршрута:

- Spike: партнер одобряет вопрос и эксперимент.
- Bounded: партнер одобряет краткий дизайн в чате.
- Architectural: партнер ревьюит и одобряет письменную спеку, затем
  ревьюит письменный план реализации и выбирает способ исполнения.
  Согласование дизайна в разговоре дает право только написать спеку;
  одобрение спеки дает право только вызвать writing-plans.

Ответ согласовывает именно предъявленный этап. Одобрение идеи или охвата
фичи не одобряет артефакты, которых еще не существует. Продолжайте с
самого раннего незавершенного этапа; не превращайте одно одобрение в
разрешение пропустить остальную часть маршрута. Read-only исследование
проекта разрешено, пока пререквизиты не выполнены.
</HARD-GATE>

Здесь три правила, которые стоит запомнить отдельно:

одобрение точечное: «yes» относится к предъявленному этапу, не к дороге целиком;
лестница согласований: в architectural разговор → спека → план → способ исполнения, и каждый шаг открывается предыдущим, а не первым;
пока ворота закрыты — только чтение: исследовать проект можно, трогать нельзя.

Три маршрута

Таблица маршрутов (сводно; детали ниже):

Маршрут	Задача	Что согласуется	Артефакты	Ворота
`spike`	проверить осуществимость идеи («can we…», «is it possible…», «quick and dirty is fine»)	вопрос и способ эксперимента (2-3 предложения)	ответ-рекомендация; весь наработанный код помечается throwaway	кивок на вопрос и эксперимент
`bounded`	ограниченная правка кода, который уже существует в репо: новый флаг, маленький эндпоинт, однофайловый фикс	краткий дизайн в чате (от пары предложений до пары абзацев)	дизайн в чате; без файла спеки, без плана	явное «да» дизайну
`architectural`	новые проекты, новые подсистемы, изменения, перестраивающие связи компонентов или интерфейсы, на которые опираются другие	спецификация, затем план и способ исполнения	дизайн-документ, план реализации	ревью спеки, ревью плана, выбор исполнения

Spike

Вопрос осуществимости, чей результат — ответ, а не код, который оставляют. Скилл предъявляет вопрос и что будет сделано (2-3 предложения), получает кивок и выясняет ответ настолько дешево, насколько позволяет корректность. Дизайн-документа нет; о найденном сообщается как рекомендация; все построенное помечается throwaway.

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

Bounded

Ограниченная правка кода, который уже есть в этом репозитории. Критерий именно про репозиторий, не про ваше знакомство с типом приложения: «bounded измеряет репо, а не вашу эрудицию». Если потока, который вы меняете, еще не существует — задача не bounded.

Процесс: уточняющие вопросы (те, что важны) → короткий дизайн в чате → стоп до явного «да». Подтверждение bounded-задачи — столь же жесткие ворота, как у architectural; отличается только размер артефакта. После «да» — обычный workflow разработки (TDD применяется), без документа плана.

Architectural

Новые проекты, подсистемы, изменения связей между компонентами. Полный процесс (чек-лист скилла):

Изучить контекст проекта — файлы, доки, недавние коммиты.
Предложить визуального компаньона just-in-time — не сразу: только в первый момент, когда вопрос был бы яснее показан, чем рассказан; если такой момент не наступает — не предлагать вовсе (раздел ниже).
Задавать уточняющие вопросы — по одному за раз: цель, ограничения, критерии успеха.
Предложить 2-3 подхода — с трейд-оффами и рекомендацией.
Предъявить дизайн — секциями, каждая по сложности: от пары предложений до 200-300 слов; после каждой секции — вопрос «пока похоже на правду?».
Записать дизайн-документ — в docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md, закоммитить.
Самопроверка спеки — плейсхолдеры, противоречия, двусмысленности, охват (ниже).
Ревью спеки пользователем — попросить прочесть файл до продолжения.
Переход к реализации — вызывается скилл writing-plans; никакой другой.

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

Антипаттерн «слишком просто, чтобы согласовывать»

Каждый маршрут заканчивается одобрением дизайна партнером до реализации. Bounded может уместиться в два предложения в чате; новый todo-проект — architectural и требует письменной спеки и планирования. Артефакт масштабируется под маршрут, но ворота есть всегда. Таблица «красных флагов» скилла (перевод выборки):

Мысль	Реальность
«Это слишком просто для дизайна»	Иди по выбранному маршруту: bounded — короткий дизайн в чате, architectural — спека и план.
«Назову bounded и пропущу спеку»	Тянуться к ярлыку, чтобы пропустить работу, — и есть сомнение. Бери более тяжелый маршрут.
«Bounded, дизайн очевиден — начну, пока читают»	Ворота — это одобрение, а не длина дизайна. Предъявил — стой до «да».
«Я знаю такие приложения, значит bounded»	Bounded измеряет репо. Нового проекта в репо нет — он architectural.
«Спайк сработал — оставлю код»	Результат спайка — ответ. Оставить код — новый запрос; классифицируй его.
«Выросло, но я почти закончил — не переклассифицирую»	Скрытая сложность повышает маршрут посреди задачи. Остановись и скажи.
«Ему понравился спайк, значит, и следующая правка одобрена»	Каждая задача — своя классификация и свое одобрение.

Дизайн для изоляции и работа в существующем коде

Из требований скилла (архитектурный маршрут):

Малые единицы с ясными границами: каждая часть — одна ответственность, хорошо определенные интерфейсы, может быть понята и протестирована независимо. Проверка: можно ли понять, что делает единица, не читая ее внутренности? можно ли поменять внутренности, не ломая потребителей?
Выгода и для агента: маленькие сфокусированные файлы агент держит в контексте целиком — его правки надежнее. Разросшийся файл — сигнал, что он делает слишком много.
В существующем коде: сначала изучить структуру, следовать существующим паттернам; целевые улучшения проблемного кода на пути работы включаются в дизайн (как поступил бы хороший разработчик), посторонний рефакторинг — нет. YAGNI безжалостно: убирать лишние фичи из каждого варианта дизайна.

Если запрос описывает несколько независимых подсистем («платформа с чатом, хранилищем, биллингом и аналитикой») — скилл обязан сразу это пометить и помочь декомпозировать на подпроекты, а не уточнять детали проекта, который нужно сначала разбить. Каждый подпроект получает свой цикл спецификация → план → реализация.

После дизайна: документ, самопроверка, ревью

Запись: валидированный дизайн пишется в docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md (предпочтения пользователя перекрывают путь по умолчанию) и коммитится в git.

Самопроверка спеки (свежими глазами, фиксы инлайн, без перепроверки):

Плейсхолдеры: TBD, TODO, незавершенные секции, размытые требования — исправить.
Внутренняя согласованность: секции противоречат друг другу? Архитектура соответствует описаниям фич?
Проверка охвата: достаточно ли сфокусировано для одного плана реализации, или нужна декомпозиция?
Двусмысленности: можно ли прочесть требование двумя способами? Выбрать один и сделать явным.

Ворота ревью пользователя — дословная формула скилла:

Spec written and committed to `<path>`. Please review it and let me know
if you want to make any changes before we start writing out the
implementation plan.

Запрошены изменения — внести и прогнать самопроверку заново; дальше — только после одобрения.

Реализация: вызывается скилл writing-plans. Терминальные состояния привязаны к маршруту: architectural завершается только в writing-plans (никогда — в имплементационных скиллах вроде frontend-design); bounded после «да» идет в обычную разработку без плана; spike — отчетом-рекомендацией.

Визуальный компаньон

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

предлагать just-in-time, не заранее: в первый момент, когда вопрос был бы яснее показан, чем рассказан — настоящим макетом/раскладкой/диаграммой, а не просто «UI-темой»; предложение — отдельным сообщением, только оно одно;
решение по каждому вопросу: даже после принятия компаньона — «лучше ли пользователь поймет это, увидев, чем прочитав?»; концептуальные вопросы (требования, трейд-оффы, scope) — в терминал, визуальные (какая раскладка мастера лучше) — в браузер;
принимается — запускается сервер с --open; отклоняется — к предложению не возвращаются, пока партнер сам не поднимет тему.

Детали — skills/brainstorming/visual-companion.md; телеметрия компаньона и отключение — урок 17.4.

Практика

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

«Проверить, можно ли уложить рендеринг в 16 мс на этом датасете» — какой маршрут и что вы согласуете?
«Добавить флаг --verbose в существующую CLI-команду» — какой? Какие два предложения дизайна в чате вы бы предъявили?
«Вынести поиск в отдельный сервис» — какой? Перечислите лестницу согласований.

Для одного из них доведите до формулировки вопроса/дизайна, который вы бы предъявили до любых действий агента.

Краткое резюме

Brainstorming — скилл превращения идеи в согласованный дизайн. Начинается с объявляемой вслух классификации запроса на spike/bounded/architectural; каждый маршрут — свои артефакты и своя контрольная точка HARD-GATE. Ворота точечные: одобряется предъявленный этап, а не дорога; лестница architectural — разговор → спека → план → исполнение.

Spike — ответ, не код; весь наработанный код throwaway. Bounded измеряет репозиторий, не вашу эрудицию. Architectural — полные артефакты.
Храповик однонаправленный: скрытая сложность повышает маршрут посреди задачи, понижений нет.
Дизайн предъявляется секциями по 200-300 слов с вопросом после каждой; спека проходит самопроверку и ревью пользователя до writing-plans.
Визуальный компаньон — just-in-time инструмент с решением по каждому вопросу, не режим.

Вопросы для самопроверки

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

Что дальше

Дизайн согласован — второй шаг базового workflow: в уроке 17.7 скилл using-git-worktrees изолирует работу в отдельном рабочем дереве и проверяет чистый бейзлайн тестов до первого изменения.

Источники

https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md