Спецификации которые читают: что писать, а что выбросить

Откройте любую спеку в Confluence или Notion и честно ответьте: вы её прочитали или пролистали до картинок? А разработчик, которому она адресована? А QA? А продакт через три месяца, когда фича уйдёт в доработку?

Большинство спецификаций пишутся в режиме «на всякий случай». Дизайнер закладывает туда всё: контекст, исследования, варианты, отвергнутые варианты, обоснования, ссылки на Miro, скриншоты прошлой версии, два абзаца про принципы. Получается документ на 40 экранов, в который никто не заглядывает после первого спринта. А потом в чате прилетает: «слушай, а тут что должно быть при пустом состоянии?» — и оказывается, что описание было, просто его никто не нашёл.

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

## Почему это вообще важно

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

Несколько вещей, которые ломаются из-за плохих спек:

• разработчик додумывает поведение и угадывает неверно — переделка после демо;
• QA не понимает, что считать багом, а что — фичей, и заводит шум;
• продакт через месяц не помнит, почему приняли именно это решение, и просит «давайте обсудим заново»;
• новый человек в команде не может въехать в продукт без личной экскурсии.

Каждая из этих проблем дешевле решается на этапе написания спеки, чем на этапе релиза.

## Кто читает спеку и зачем

Прежде чем писать, полезно вспомнить, что у документа несколько аудиторий, и им нужно разное. Если писать «для всех сразу», получится «ни для кого».

### Разработчик

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

### QA

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

### Продакт и стейкхолдеры

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

### Будущий ты

Через три месяца ты не вспомнишь, почему кнопка называется именно так и почему модалка, а не отдельный экран. Одна строчка «почему так» в спеке сэкономит час споров.

Вывод простой: документ должен быть устроен слоями. Сверху — то, что нужно всем. Глубже — то, что нужно отдельным ролям. В самом низу или в приложениях — архив контекста.

## Что выбросить из спеки в первую очередь

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

Выкидываем без сожаления:

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

Оставляем, даже если кажется очевидным:

• состояния: пустое, загрузка, ошибка, успех, частично заполненное;
• поведение при нестандартных данных (очень длинный текст, ноль элементов, 10 000 элементов);
• что происходит при отмене, возврате назад, обновлении страницы;
• права доступа: кто что видит и может;
• зависимости от других фич и флагов.

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

## Как устроена спека, которую читают

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

### Шапка на полстраницы

Сверху всегда одно и то же, в одном и том же порядке. Это та часть, которую открывают в чате на телефоне.

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

Если человек прочитал шапку и понял, надо ли ему читать дальше — шапка сделала работу.

### Решение и обоснование

Один абзац: что выбрали и почему именно это. Без пересказа всех вариантов. Если вариантов было три и выбор не очевиден — короткий блок «почему не A и не B», по строчке на каждый.

### Сценарии, а не экраны

Самая частая ошибка — описывать макет «слева направо». Читать это невозможно. Лучше идти по пользовательским сценариям: «человек заходит впервые», «человек возвращается с уведомления», «человек хочет отменить».

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

### Состояния и поведение

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

### Что осталось за кадром

В конце — короткий список того, что сознательно не делаем в этой итерации и почему. Это сильно сокращает количество вопросов «а вот тут вы забыли».

## Рабочий процесс: когда и что писать

Спека не пишется одним заходом за вечер перед демо. Она растёт вместе с дизайном.

### До макета — гипотеза на полстраницы

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

### Во время макета — черновик с дырками

Пока рисуешь, открыт тот же документ. Туда складываются вопросы к себе и команде, найденные пограничные случаи, варианты, которые отвергнул. Это не финальная спека — это рабочий блокнот, и нормально, что половина — «???».

### Перед хэндовером — чистовик

За день-два до передачи в разработку черновик переписывается набело: убирается всё личное, остаются только сценарии, поведение и состояния. Хороший признак — если получилось сократить объём вдвое.

### После релиза — короткая правка

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

## Типичные диагнозы

На ревью спеки обычно повторяются одни и те же болезни. Их полезно уметь называть.

Спека-дневник. Хронологическое описание того, как дизайнер пришёл к решению. Читается как сочинение. Лечится переписыванием от итога, а не от процесса.

Спека-альбом. Двадцать макетов подряд без подписей. Понять, что меняется и почему — невозможно. Лечится аннотациями и удалением дублей.

Спека-эссе. Много рассуждений о пользователе и индустрии, мало конкретики. Лечится правилом «каждый абзац отвечает на вопрос разработчика или QA».

Спека-обещание. «Тут будет описано позже». Через неделю не описано, фича уезжает в разработку, разработчик пишет в чат. Лечится тем, что пустые блоки удаляются — если не успел описать, честнее признать дыру, а не маскировать заглушкой.

Спека-копия Figma. Дубликат макета словами. Если макет меняется, текст устаревает за час. Лечится отказом описывать то, что и так видно глазами.

## Как применять это в макете

Спека и макет — один продукт, а не два. Несколько привычек, которые сильно помогают.

• На макете подписаны все нестандартные состояния прямо рядом с экраном — не отдельной страницей.
• Компоненты из дизайн-системы не описаны словами, а отмечены как инстансы — по ним можно перейти к документации.
• Аннотации в Figma короткие, в формате «когда — тогда», а не абзацами.
• Рядом с экраном лежат версии данных: короткие, длинные, пустые. Это лучше любых слов про «учтите длинный текст».
• Для сложных переходов — небольшая схема состояний, а не три страницы прозы.

Чем больше поведения видно прямо на холсте, тем меньше остаётся для текстовой спеки — и тем выше шанс, что её прочитают.

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

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

• Если читать только шапку — понятно, о чём документ?
• Разработчик найдёт все состояния, не задавая вопросов в чате?
• QA сможет написать тест-кейсы, не возвращаясь к дизайнеру?
• Продакт увидит обоснование решения в одном абзаце?
• Видно, что мы сознательно не делаем в этой итерации?
• Нет ни одного блока «опишу позже»?
• Если убрать любой раздел — кто-то это заметит?

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

## Короткий итог сегмента

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

## Когда базовой схемы не хватает

Слоёная спека и гигиена работают для обычной фичи в одну команду. Но есть ситуации, где этого мало: фича едет полгода, её делают три команды, у неё веб и мобайл, или часть решения генерирует AI. Здесь спека перестаёт быть документом и становится интерфейсом между людьми. И ломается там же, где любой плохой интерфейс — на стыках.

### Длинная фича на несколько спринтов

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

### Несколько платформ

Веб, iOS, Android — соблазн написать три спеки. На практике лучше одна спека логики и поведения плюс короткие приложения по платформенным различиям. Если различий больше, чем общего, это сигнал, что продукт расходится концептуально, и проблема не в документации.

### Несколько команд

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

## Спека и AI: что меняется в процессе

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

### AI как соавтор спеки

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

Где AI стабильно врёт:

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

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

### Спека для AI-фичи

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

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

### MCP, плагины и автогенерация из Figma

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

## Как защищать решение перед командой

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

• Продакт: почему именно так, что мы измерим, что отрезали.
• Разработчик: какие состояния, какие крайние случаи, что отдаёт сервер.
• QA: где границы валидаций, какие сценарии обязательны.
• Дизайн-ревью: как это укладывается в систему, что новое появилось в паттернах.

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

## Вопросы для ревью со стороны

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

• Понятно, какую проблему решаем, без моих пояснений?
• Видно, что мы сознательно оставили за рамками?
• Где в документе ты бы задал вопрос — и почему?
• Если бы ты это реализовывал, чего не хватает?
• Какой абзац ты бы удалил без потери смысла?

Ответы на эти пять вопросов обычно дают больше, чем час обсуждения в команде.

## Короткий итог сегмента

Чем сложнее контекст — длинная фича, несколько команд, AI внутри продукта — тем важнее, чтобы спека была не складом мыслей, а интерфейсом между людьми. AI ускоряет черновик, но не отменяет вычитку. А лучший тест качества — не свой чеклист, а пять минут с человеком не из проекта.

## Чеклист готовности спеки

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

• В первом экране видно, какую задачу решаем и для кого.
• Есть явный список «вне рамок» — что мы сознательно не делаем.
• Перечислены все состояния: пусто, загрузка, ошибка, частичные данные, оффлайн.
• Описан контракт с бэком: события, ответы, коды ошибок.
• Видно, где валидация на клиенте, где на сервере, и что показываем при отказе.
• Для каждой ошибки понятно, что видит пользователь и что он может сделать.
• Есть раздел про доступность хотя бы на уровне фокуса, контраста и озвучки состояний.
• Для AI-фичи описано поведение при низкой уверенности и при отказе модели.
• Тексты не «Lorem», а реальные строки, согласованные с редактором.
• В макетах нет слоёв «final-2-ok», на которые ссылается спека.
• Любой человек из команды находит нужный раздел за десять секунд.

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

## Анти-паттерны, которые встречаются чаще остальных

### Спека-альбом

Двадцать экранов подряд, между ними пустые комментарии «тут всё понятно». Читать невозможно: непонятно, где начало флоу, где альтернативные ветки, где просто варианты на подумать. Лечится разделением на сценарии и явной разметкой «основной поток / альтернативы / отбраковано».

### Спека-протокол совещания

Документ с историей решений: «обсудили с Петей, договорились так, потом передумали». Полезно для архива, бесполезно для исполнителя. Решения вынести в отдельный лог, в спеке оставить только итог.

### Спека-вики

Всё в одном бесконечном файле: продуктовые цели, исследование, конкуренты, макеты, тексты, аналитика. Открывать страшно, искать невозможно. Лучше короткий документ-хаб со ссылками, чем монолит.

### Спека «по диагонали»

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

### Спека под одного человека

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

### Спека, которая боится решений

Везде «возможно», «вероятно стоит», «обсудить». Документ перекладывает выбор на читателя, и каждый делает по-своему. Если решение действительно открыто — это должно быть явно помечено как открытый вопрос с владельцем, а не растворено в тексте.

## Вопросы, которые стоит задать самому себе перед отправкой

• Что я уберу из этого документа, если мне дадут на это пять минут?
• Какие три абзаца самые важные, и стоят ли они в начале?
• Что я не написал, потому что «и так понятно» — и кому именно это понятно?
• Если фичу будут делать без меня, что сломается в первую очередь?
• Какие состояния я придумал на ходу, пока писал, и не отрисовал в макете?
• Где в документе я прикрываю словами то, что не решил в дизайне?

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

## Практический итог

Хорошая спека — это не объём и не красивое оформление. Это документ, из которого человек, не сидевший с вами на встречах, может собрать продукт без догадок. Чтобы он таким стал, достаточно трёх привычек: писать сценариями и состояниями, а не экранами; явно проговаривать границы и контракты; и каждый раз спрашивать себя, какие куски можно удалить без потери смысла. Всё, что выживает после этих трёх фильтров, обычно и есть та часть спеки, которую действительно читают.