ТЗ (спецификация) нужно, чтобы между «что хотели» и «что сделали» не вклинился испорченный телефон. Хорошее ТЗ отвечает не только «что сделать», но и «зачем», и явно очерчивает границы — что в scope, а что нет. Минимальный костяк: контекст и цель, scope и out-of-scope, требования (FR и NFR), сценарии, контракты и данные, критерии приёмки, открытые вопросы. Главный принцип — писать так, чтобы нельзя было понять неправильно: вместо «быстро» — число, вместо «и т.д.» — полный список. И не надо романа на 50 страниц: его никто не дочитает, а значит он не работает.
ТЗ — это не бюрократия и не отчёт для галочки. Это инструмент против разрыва, про который я писал в записи о том, кто все эти люди в команде: информация идёт по цепочке заказчик → продакт → аналитик → разработчик и на каждом стыке искажается. Спека — это место, где вы фиксируете смысл письменно, чтобы его нельзя было расслышать иначе. Я видел проект, где разработчик две недели делал не то — не потому что плохой, а потому что в ТЗ было написано «реализовать фильтрацию», и каждый понял под этим своё.
И сразу оговорка: спека не отменяет живого разговора. Лучшие требования рождаются, когда вы обсуждаете задачу с разработчиками напрямую, а слишком большую задачу перед описанием дробите на куски. ТЗ фиксирует итог этих разговоров, а не заменяет их.
Зачем вообще спека
Устная договорённость живёт до первого «а я думал, ты имел в виду другое». Письменная спека делает три вещи. Во-первых, фиксирует смысл — к ней можно вернуться и сослаться. Во-вторых, вскрывает дыры: пока пишешь, обнаруживаешь вопросы, которые в разговоре проскочили («а что если товара нет на складе?»). В-третьих, синхронизирует всех — разработчик, тестировщик, продакт читают один документ, а не три пересказа.
Спека — это не про объём, а про однозначность
Цель ТЗ не «описать всё», а «убрать разночтения». Одна точная фраза с числом ценнее страницы общих слов. Если после прочтения у двух разработчиков получится одинаковая система — спека хорошая, сколько бы страниц в ней ни было.
Из чего состоит хорошее ТЗ
Жёсткого шаблона нет, но есть костяк, который закрывает большинство разночтений. Я держу его как чек-лист:
| Раздел | На какой вопрос отвечает |
|---|---|
| Контекст и цель | Зачем мы это делаем, какую проблему решаем |
| Scope | Что именно входит в эту задачу |
| Out-of-scope | Что НЕ входит — явно, чтобы не додумали |
| Требования (FR/NFR) | Что система делает и насколько хорошо |
| Сценарии | Как это происходит, включая ошибки и ветки |
| Контракты и данные | Какие поля, форматы, API, структуры |
| Критерии приёмки | Как понять, что готово |
| Открытые вопросы | Что ещё не решено и кто решает |
Два раздела недооценивают чаще всего. Первый — контекст и цель: без «зачем» разработчик не сможет принять ни одного разумного решения на развилке, которую вы не предусмотрели, — а такие развилки будут всегда. Второй — out-of-scope: то, что вы явно вынесли за рамки. «Авторизация через соцсети в этой задаче не делается» экономит неделю споров на приёмке, когда кто-то решит, что она «вроде как подразумевалась».
Про требования и критерии приёмки есть отдельные записи — функциональные и нефункциональные и user story, use case и критерии приёмки; здесь важно, что в спеке должны быть оба типа требований и проверяемые критерии готовности — а как эти критерии превращаются в проверки, разобрано в записи про тестирование для аналитика.
Принцип: пиши так, чтобы нельзя было понять неправильно
Это главный навык автора ТЗ. Разработчик не телепат — он реализует то, что прочитал, а не то, что вы имели в виду. Любая неоднозначность будет истолкована, и не обязательно так, как вам хотелось. Поэтому каждую формулировку проверяйте вопросом: «можно ли понять это иначе, чем я задумал?». Если да — переписывайте.
Плохо: Список должен быстро загружаться.
Хорошо: Список из 1000 строк отображается за < 1 секунды;
при большем количестве — постранично по 50.
Плохо: Поддержать основные форматы файлов.
Хорошо: Принимаются PNG, JPG, PDF; размер до 10 МБ;
прочие форматы — ошибка «формат не поддерживается».
Плохо: При ошибке показать сообщение.
Хорошо: При коде ответа 422 показать текст из поля error.message;
при 500 — «Что-то пошло не так, попробуйте позже».Заметьте паттерн: из плохих формулировок ушли слова «быстро», «основные», «и т.д.», «при ошибке». Каждое из них — это спрятанный вопрос, который вы перекладываете на разработчика. «Основные форматы» — это какие именно? «И т.д.» — это что конкретно? Хорошая спека не оставляет читателю работы по угадыванию.
Тест на однозначность
Дайте спеку человеку, который не участвовал в обсуждении, и спросите, что он понял. Расхождение с вашим замыслом — это и есть дыры. Я иногда прошу самого разработчика пересказать задачу своими словами до старта: пять минут разговора экономят дни переделок.
Чего не надо: роман, который не читают
Обратная крайность не менее вредна. ТЗ на 50 страниц с водой, вступлениями и «как мы все знаем» не читают — его пролистывают. А значит важное тонет в неважном, и эффект тот же, что от отсутствия спеки: каждый достроил своё. Объём не равен качеству. Качество — это полнота при минимуме слов.
- Не пересказывайте очевидное — пишите то, что неочевидно или может быть понято иначе.
- Не дублируйте: одно требование живёт в одном месте, иначе при правке разойдутся версии.
- Картинку (схему процесса, мокап) ставьте там, где она короче трёх абзацев текста.
- Открытые вопросы выносите явным списком, а не прячьте в прозе — так их видно и легко закрывать.
Спека стоит денег — и экономит их
Помните, что и ваше время на ТЗ, и время разработчика на чтение стоят денег (про это — в записи о том, зачем аналитику думать про деньги). Поэтому крайности обе дорогие: нет спеки — платим переделками; роман на 50 страниц — платим за написание и чтение того, что не работает. Цель — минимальный документ, после которого никто не переспрашивает.
Откуда это взялось
Идея «полного технического задания» родом из инженерных и государственных дисциплин — в СССР это формализовали ГОСТы серии 34 (на автоматизированные системы), где ТЗ был обязательным документом со строгой структурой. Это водопадная логика: всё спроектировать заранее, потом строить. Agile в 2000-х качнул маятник в другую сторону — к коротким user story и живому разговору вместо толстых документов. Сегодня большинство команд живёт посередине: лёгкая спека на фичу, которая фиксирует ровно то, что нельзя терять, без госто́вской тяжести. Понимать оба полюса полезно — чтобы осознанно выбирать, сколько формальности нужно конкретной задаче.
Частые вопросы
Как написать ТЗ для разработчика?
Соберите костяк: контекст и цель (зачем), scope и out-of-scope (что входит и что явно нет), требования функциональные и нефункциональные, сценарии с ветками и ошибками, контракты и форматы данных, критерии приёмки, открытые вопросы. Затем пройдитесь по каждой формулировке с вопросом «можно ли понять иначе?» и уберите слова «быстро», «основные», «и т.д.», заменив их числами и полными списками. Цель — чтобы два разных разработчика поняли одинаково.
Насколько подробным должно быть ТЗ?
Ровно настолько, чтобы убрать разночтения, — не больше и не меньше. Объём не равен качеству: роман на 50 страниц не читают, и важное тонет в воде. Хороший ориентир — после прочтения у двух разработчиков получится одинаковая система, и никто не переспрашивает. Очевидное не описывайте, неочевидное и спорное — обязательно.
Зачем в ТЗ раздел out-of-scope?
Чтобы явно зафиксировать, что НЕ входит в задачу, и не дать это додумать. Без него на приёмке всплывает «а я думал, авторизация через соцсети тоже здесь». Одна строка «в этой задаче не делаем X» снимает целый класс споров и защищает оценку сроков. Out-of-scope так же важен, как scope: вместе они очерчивают границу задачи с обеих сторон.