Как написать техническое задание для разработчика, чтобы сделали с первого раза

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

Цель: объяснить зачем, а не просто что

Первый раздел ТЗ — не технические детали, а бизнес-цель. Зачем нужен этот функционал? Какую проблему пользователя он решает? Разработчик, который понимает контекст, принимает более умные решения, чем тот, кто просто выполняет пункты.

Плохая формулировка: «Сделать кнопку "Сохранить" в профиле». Хорошая формулировка: «Пользователь должен иметь возможность сохранить изменения в личных данных (имя, телефон, email) без перезагрузки страницы. После сохранения появляется всплывающее уведомление об успехе, а если данные не прошли валидацию — подсвечивается ошибка. Цель: снизить количество брошенных анкет на этапе редактирования профиля на 20%».

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

Функциональные требования: как система должна себя вести

Это самая большая часть ТЗ. Здесь описываются конкретные действия пользователя и реакции системы на них. Функциональные требования отвечают на вопрос «что делает система». Важно избегать общих фраз вроде «всё должно работать быстро» или «интерфейс должен быть удобным». Вместо этого пишут сценарии.

Плохая формулировка: «На главной странице должна быть форма поиска». Хорошая формулировка: «В шапке сайта справа от логотипа расположено поле ввода с плейсхолдером "Поиск по товарам". Пользователь вводит от двух символов, через 0,5 секунды после остановки печати система отправляет запрос на сервер. Результаты (до 10 штук) отображаются выпадающим списком под полем ввода. По клику на результат пользователь переходит на карточку товара. Если результатов нет, показывается сообщение "Ничего не найдено" и ссылка на каталог».

Чем больше сценариев, тем лучше. Нужно описать не только счастливый путь (всё работает), но и граничные случаи: что при пустом поле, что при ошибке сервера, что при слишком быстром клике. Хорошее ТЗ по функционалу занимает от двух до десяти страниц, но бывает и больше.

Нефункциональные требования: скорость, безопасность, нагрузка

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

Для большинства веб-проектов базовый набор выглядит так. Скорость: страницы должны загружаться не дольше двух секунд по 50-му процентилю при тестировании с 3G-соединения. Безопасность: передача данных только по HTTPS, хранение паролей с солевым хешированием (хотя бы SHA-256), защита от SQL-инъекций и XSS-атак. Надёжность: система должна работать без критических сбоев 99,9% времени в рабочие часы. Если проект предполагает всплески трафика (например, интернет-магазин перед чёрной пятницей), нужно указать пиковую нагрузку: сколько одновременных пользователей должен выдерживать сервер.

Плохая формулировка: «Сайт должен быть быстрым и защищённым». Хорошая формулировка: «Время ответа API для 95% запросов не превышает 300 мс. Аутентификация через JWT-токены с временем жизни 24 часа. Система должна выдерживать 5000 одновременных пользователей без падения производительности».

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

Критерии приёмки: как понять, что готово

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

Плохая формулировка: «Всё работает корректно». Хорошие формулировки: «При вводе валидного email и пароля (от 8 символов, включая цифру) пользователь попадает на главную страницу в течение трёх секунд». «При трёх неудачных попытках входа кнопка "Войти" блокируется на 15 минут, и появляется сообщение о превышении лимита». «Кнопка "Восстановить пароль" отправляет письмо на указанный email в течение пяти секунд, ссылка в письме ведёт на страницу с формой создания нового пароля».

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

Типичные ошибки и как их избежать

Первая ошибка — смешивать требования и реализацию. Не нужно писать «использовать библиотеку React и Redux», если вам не принципиально это. Лучше написать «интерфейс должен быть одностраничным приложением с быстрым переключением между разделами без перезагрузки страницы». Разработчик сам выберет инструменты.

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

Третья ошибка — использовать общие слова «удобно», «понятно», «красиво». В техническом задании место только измеримым критериям. Если важен дизайн, приложите макеты в Figma или хотя бы референсы.

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

Пример готовой структуры для небольшого ТЗ

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

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

Функциональные требования: в правом верхнем углу после имени пользователя появляется иконка текущего аватара (или дефолтная заглушка). При клике на иконку открывается выпадающий блок с кнопкой «Загрузить новое фото». Поддерживаются форматы JPEG, PNG, WebP. Максимальный размер — 5 МБ. После выбора файла система обрезает изображение до квадрата 200×200 пикселей с центрированием. Пользователь может подвигать рамку кадрирования. После подтверждения аватар сохраняется на сервере и заменяет старый. Весь процесс без перезагрузки страницы.

Нефункциональные требования: все загруженные изображения проверяются антивирусом на сервере. Скорость загрузки и обработки файла до 5 МБ не должна превышать трёх секунд на канале 10 Мбит/с. Аватары хранятся в отдельной папке с рандомизированными именами, доступ к папке через прямую ссылку закрыт.

Критерии приёмки: при успешной загрузке старый аватар заменяется новым во всех местах сайта (шапка, профиль, комментарии) без кэширования. Если выбран файл неверного формата, появляется сообщение «Поддерживаются только JPG, PNG, WebP». Если файл больше 5 МБ — сообщение о превышении размера. Если на сервере ошибка (например, закончилось место), пользователь видит «Не удалось загрузить аватар, попробуйте позже». После обновления страницы новый аватар остаётся. При удалении аватара через отдельный крестик восстанавливается дефолтная заглушка.

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