write-product-spec

name	write-product-spec
description	Написание PRODUCT.md для значимой пользовательской фичи — детальное поведение как нумерованные проверяемые инварианты. Использовать, когда нужна продуктовая спека/PRD, нужно зафиксировать поведение до реализации, или фича достаточно крупная/неоднозначная, чтобы письменная спека улучшила реализацию и ревью.
vibeVersion	1.1.0

write-product-spec

Написать PRODUCT.md для значимой фичи.

Суть

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

«Пользователь» — не только конечный пользователь приложения, а потребитель проектируемой поверхности:

• UI/UX-фича → человек в приложении;
• модель данных → код, который её читает и пишет;
• API/протокол/библиотека → вызывающие: другие сервисы, клиентский код, плагины, агенты;
• CLI или developer-facing поверхность → разработчик, который её вызывает.

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

Реализация, валидация и план тестирования живут в парном TECH.md (скилл write-tech-spec). Продуктовая спека — обычно первый шаг двухшагового процесса: после согласования PRODUCT.md вызывается write-tech-spec (или пользователю явно сообщается, что это ожидаемый следующий шаг). Писать так, чтобы техспека выводилась из продуктовой напрямую.

Путь: specs/<id>/PRODUCT.md. Правила выбора <id> и работы с трекером — в скилле spec-driven-implementation.

Перед написанием

Собрать только необходимый контекст: id каталога, краткое описание фичи, целевые пользователи, ключевые поведения, edge cases. Недостающее — спросить у пользователя, а не угадывать.

Дизайн-моки

Если у фичи есть UI или интерактивный дизайн — до черновика секции Behavior спросить, существует ли мок (Figma, Sketch, скриншот). Мок — самый надёжный источник правды о визуальных состояниях, отступах и краевых раскладках; не спросить — значит дать Behavior угадывать намерения, которые дизайнер уже решил.

• Ссылка дана → короткая секция ## Design (или строка в начале Behavior): Design: <link>.
• Мока нет, подтверждено → явная пометка Design: none provided.
• Фича чисто backend (модель данных, API, CLI без визуала) → вопрос пропустить, секцию опустить.

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

Структура

Обязательные секции:

1. Summary — 1–3 предложения: фича и желаемый результат.
2. Behavior — мясо спеки: исчерпывающее описание работы фичи нумерованными проверяемыми инвариантами. Вся длина спеки зарабатывается здесь; остальное остаётся тонким, чтобы не дублировать.

Опциональные — только когда добавляют сигнал сверх ядра; пустую секцию не писать (никаких «None»):

• Problem — только если мотивация неочевидна из Summary.
• Goals / Non-goals — когда рамки неоднозначны или оспаривались.
• Design — см. «Дизайн-моки» выше; для невизуальных фич опустить целиком.
• Open questions — предпочитать инлайновые **Open question:** … рядом с соответствующим поведением; отдельная секция — только если нерешённых вопросов несколько и их стоит собрать.

Не включать секции Validation, Success criteria, Testing — валидация и тест-план живут в TECH.md. Behavior пишется нумерованными инвариантами, проверяемыми сами по себе, — техспека ссылается на них напрямую.

Секция Behavior

Behavior — это и есть спека. Всё остальное — обрамление.

Цель — полное описание работы фичи, достаточно детальное, чтобы техспеку можно было написать прямо из него, не угадывая и не выводя продуктовое намерение заново. Если читатель заканчивает Behavior с вопросами «а что фича делает в ситуации X» — секция не готова.

Описать как минимум:

• поведение по умолчанию и happy-path сценарий;
• каждое видимое пользователю состояние и переходы между ними;
• все входы пользователя и реакцию фичи на них;
• пустые состояния, ошибки, loading/pending, отмену;
• edge cases, о которых разумный исполнитель не догадается спросить: permission denied, оффлайн, таймауты, гонки между изменениями состояния, несколько параллельных инстансов, протухшие/отсутствующие данные, потеря фокуса посреди взаимодействия, взаимодействие со смежными фичами;
• клавиатуру, доступность и фокус, где релевантно;
• инварианты, обязанные выполняться всегда, и поведения, которые не должны регрессировать.

Длина Behavior — по фиче: тривиальной хватит горстки инвариантов, сложной нужны десятки с подсекциями по сценариям. Сомневаешься — перечисли на один edge case больше, а не меньше.

Эвристика длины

Behavior — столько, сколько требует фича; edge cases ради лимита строк не резать. Эвристика — для обрамления вокруг Behavior:

• тривиальный фикс или узкая UI-правка: спека не нужна;
• малая фича (один модуль, мало edge cases): всего ~30–60 строк;
• средняя (кросс-модульная, несколько состояний): ~80–150 строк;
• крупная/поведенчески богатая: длиннее — нормально, и почти вся длина должна жить в Behavior.

Одна и та же мысль повторяется в Summary, Problem, Goals и Behavior → схлопывать обрамление, не контент Behavior.

Принципы письма

• Конкретное наблюдаемое поведение вместо лозунгов.
• Behavior — списком инвариантов, а не прозой, где возможно.
• Фиксировать инварианты-нерегрессии и легко упускаемые edge cases.
• Детали реализации — только если неизбежны для UX.
• Секция либо отрабатывает место, либо удаляется.

Актуальность спеки

Поддержание PRODUCT.md синхронным с реализацией (тот же PR, обновление при изменении поведения/UX) — по каноническим правилам скилла implement-specs.

Связанные скиллы

implement-specs, write-tech-spec, spec-driven-implementation

Пример секции Behavior

Образец для гипотетической фичи — рендеринг GFM-таблиц в блочном списке чата/терминала. Демонстрирует ожидаемую форму: нумерованные, проверяемые инварианты с позиции пользователя — умолчания, edge cases, битый ввод, стриминг, выделение/копирование, поиск, шаринг, темизация, кросс-поверхностная консистентность, один инлайновый открытый вопрос.

## Behavior

1. Когда блок вывода содержит GFM-таблицу (строка заголовка, строка-разделитель из сегментов `---` и одна или более строк тела, всё разделено `|`), она рендерится как визуально оформленная таблица, а не как сырой pipe-текст.

2. Таблица рендерится с: визуально выделенной строкой заголовка; выравниванием колонок по разделителю (`|:---|` влево, `|:---:|` по центру, `|---:|` вправо; `|---|` без двоеточий — дефолт: текст влево, числовые значения вправо); видимыми разделителями строк в соответствии с активной темой.

3. Инлайновый markdown внутри ячейки рендерится инлайново: жирный, курсив, инлайн-код, зачёркивание и ссылки — как в окружающем блоке. Переносы внутри ячейки (`<br>` или экранированный `\n`) — как внутриячеечные переносы.

4. Ширины колонок подбираются под естественное содержимое, пока таблица помещается в блок. Очень длинная ячейка переносит текст внутри своей колонки, а не растягивает колонку до неразумной ширины.
   - **Open question:** если перенесённая ячейка делает строку неразумно высокой — клипуем с аффордансом «развернуть» или даём строке расти неограниченно?

5. Горизонтальный скролл: общая ширина превышает блок (много колонок или несжимаемо широкие) → таблица скроллится горизонтально внутри блока, открывая офф-скриновые колонки без клиппинга. Вертикальный скролл блока работает независимо.

6. При ресайзе блока (окно, сплит панели, открытие сайдбара) таблица перевёрстывается под новую ширину без потери порядка строк и колонок.

7. Пустые ячейки рендерятся видимо пустыми (та же высота строки, без плейсхолдеров). Строка из одних пустых ячеек всё равно рендерится строкой.

8. Таблица из заголовка и разделителя без строк тела — как header-only таблица, не как сырой текст.

9. Одноколоночная таблица — одноколоночной таблицей (не схлопывается в список).

10. Битые таблицы деградируют аккуратно: нет разделителя → preformatted-текст, не таблица; рваные строки (меньше/больше ячеек, чем в заголовке) → недостающие пустыми, лишние показываются, заголовок по возможности визуально расширяется — блок никогда молча не теряет данные; незакрытая таблица (последняя строка обрезана стримом) → частичная таблица, см. (11).

11. Стриминг: пока команда выдаёт строки, таблица рендерится инкрементально — новые строки дописываются по мере прихода. Заголовок фиксируется по получении строки-разделителя; строки до разделителя рендерятся обычным текстом, пока таблица не распознана.

12. Выделение и копирование: выделение мышью/клавиатурой по ячейкам выбирает видимый текст; копирование выделения по умолчанию даёт tab-separated текст (строка на строку, ячейки через tab); аффорданс (контекстное меню, шорткат) копирует исходный markdown; копирование блока целиком сохраняет исходный markdown дословно.

13. Поиск внутри блока матчится по тексту ячеек; совпадения подсвечиваются на месте в отрендеренной ячейке; навигация по совпадениям доскролливает таблицу, включая горизонтально к офф-скриновой колонке.

14. Шаринг/экспорт блока сохраняет исходный markdown, не отрендеренную форму.

15. Темизация: рамки, фон заголовка, чередование строк (если есть), стили ссылок/кода — из активной темы приложения. Без хардкода цветов.

16. GFM-таблицы рендерятся консистентно везде, где блочный markdown уже рендерится: одинаковый вход — одинаковая таблица на каждой поверхности.

17. Не-табличный pipe-контент не рендерится таблицей по ошибке: текст с `|`, но без валидной пары «заголовок + разделитель» остаётся обычным текстом, даже если визуально похож на таблицу.