Как писать ТЗ для разработчика: структура, шаблоны и частые ошибки

Если вы хоть раз получали от разработчика сообщение «а как себя должна вести система, если пользователь нажмёт это два раза подряд?» — поздравляю, ваше техническое задание живёт собственной жизнью, отдельно от продукта. И это нормально. Это значит, что у ТЗ нашлись пробелы, которые в спокойной обстановке никто не заметил, а в ходе разработки они вылезли. Хуже бывает только тогда, когда никто ничего не спрашивает, но в продакшене происходит то, чего никто не ждал.

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

В этом посте разберём, как составить ТЗ для программиста так, чтобы по нему можно было реально работать. Без воды, без академизма, с практическими шаблонами. Часть тем — Use Case, ФТ и НФТ — мы уже подробно разбирали раньше: советую заглянуть в посты про функциональные требования с шаблонами и примерами и про User Story и Use Case для системного аналитика. Здесь мы соберём всё в один цельный документ.

Что такое ТЗ и зачем оно нужно

Начнём с определения, чтобы потом не путаться в терминах.

Техническое задание (ТЗ, technical specification, software requirements specification — SRS) — это структурированный документ, который описывает, что именно должна делать система, как она должна себя вести и при каких ограничениях. ТЗ — контракт между бизнесом и разработкой.

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

Кому и зачем нужно ТЗ

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

Структура хорошего ТЗ: десять обязательных блоков

Существует множество вариантов структуры ТЗ — от ГОСТ 34 до облегчённых product-style спецификаций. Но если выкинуть лишнее и оставить рабочий минимум, получится примерно такой набор разделов.

graph TD
  TZ["Техническое<br/>задание"]
  TZ --> CTX["1. Контекст<br/>и цели"]
  TZ --> TERMS["2. Глоссарий<br/>и роли"]
  TZ --> SCOPE["3. Границы<br/>проекта (in/out)"]
  TZ --> UC["4. Use Case<br/>и сценарии"]
  TZ --> FR["5. Функциональные<br/>требования"]
  TZ --> NFR["6. Нефункциональные<br/>требования"]
  TZ --> UI["7. Макеты<br/>и UI-схемы"]
  TZ --> INT["8. Интеграции<br/>и API"]
  TZ --> DATA["9. Модель<br/>данных"]
  TZ --> ACC["10. Критерии<br/>приёмки"]

  style TZ fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style CTX fill:#50c878,stroke:#3a9a5c,color:#fff
  style TERMS fill:#50c878,stroke:#3a9a5c,color:#fff
  style SCOPE fill:#50c878,stroke:#3a9a5c,color:#fff
  style UC fill:#f0a500,stroke:#c88400,color:#fff
  style FR fill:#f0a500,stroke:#c88400,color:#fff
  style NFR fill:#f0a500,stroke:#c88400,color:#fff
  style UI fill:#7b68ee,stroke:#5a4db2,color:#fff
  style INT fill:#7b68ee,stroke:#5a4db2,color:#fff
  style DATA fill:#7b68ee,stroke:#5a4db2,color:#fff
  style ACC fill:#e0e0e0,stroke:#999,color:#333

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

1. Контекст и цели

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

Пример. «В кофейне Coffee&Code сейчас принимают заказы только за стойкой. В часы пик очередь уходит за дверь, бариста не справляются, средний чек снижается. Цель: запустить мобильное предзаказ-приложение, чтобы клиент мог оформить заказ и оплатить до прихода. Метрика успеха: 30% заказов через приложение через 3 месяца после запуска.»

Что важно — есть конкретная цель и измеримая метрика. Без метрики через полгода никто не сможет ответить на вопрос «а проект-то получился?».

2. Глоссарий и роли

Список терминов и аббревиатур, которые вы используете в документе. Сюда же — описание ролей пользователей системы. Кажется лишним, но именно из-за разной трактовки терминов рождаются 80% переделок.

Важно прописывать определения именно на вашем проекте, а не копировать из википедии. У одних «заказ» — это позиция в корзине, у других — финализированная сущность после оплаты. Договоритесь.

3. Границы проекта (in scope / out of scope)

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

В рамках проекта:

• Мобильное приложение iOS/Android для клиентов
• Админка для бариста (web)
• Интеграция с платёжным шлюзом и кассой
• Push-уведомления о готовности заказа

Не входит в проект (out of scope):

• Программа лояльности (отдельный проект, Q3)
• Доставка курьерами (рассматривается на следующем этапе)
• Интеграция с CRM-системой
• Оплата криптовалютой (нет, серьёзно — кто-то всегда спрашивает)

Раздел «out of scope» зачастую важнее, чем «in scope». Аналитик пишет это не для разработчика, а для заказчика, чтобы потом было на что сослаться.

4. Use Case и сценарии

Описание основных потоков взаимодействия пользователя с системой. Минимум — главный сценарий и основные альтернативы. Подробно про этот блок — в посте про User Story и Use Case, здесь покажу шаблон формулировки.

UC-001. Оформление заказа гостем

Актор: Гость Предусловия: В корзине минимум одна позиция Главный сценарий:

1. Гость нажимает «Оформить заказ»
2. Система запрашивает имя и номер телефона
3. Гость вводит данные и нажимает «Подтвердить»
4. Система отправляет SMS с кодом подтверждения
5. Гость вводит код
6. Система переводит на экран оплаты
7. Гость завершает оплату
8. Система фиксирует заказ и отправляет в очередь бариста

Постусловия: Заказ создан со статусом «Оплачен», гость видит экран ожидания

5. Функциональные требования

Конкретные правила и поведение системы. Каждое ФТ — атомарное, проверяемое утверждение. Не нужно превращать его в эссе, нужно — в строку, по которой пишется тест.

6. Нефункциональные требования

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

7. Макеты и UI-схемы

Ссылки на Figma/прототипы с пометками к ключевым экранам. Хорошее правило — рядом с каждым макетом писать, какое поведение реализуется и какие ошибки обрабатываются.

8. Интеграции и API

Описание всех внешних систем, с которыми взаимодействует ваша. Для каждой интеграции — endpoint, формат запроса/ответа, обработка ошибок, ретраи. Если у вас REST API — приложите Swagger/OpenAPI спецификацию (про это — в посте о документации API).

9. Модель данных

Базовые сущности, их атрибуты и связи. Не нужно расписывать ER-диаграмму на 50 таблиц — достаточно ключевых сущностей, по которым ясно, что и где хранится.

10. Критерии приёмки

Чек-лист, по которому заказчик принимает работу. Каждый пункт — измеримый: «можно сделать заказ через мобильное приложение и получить SMS» — это критерий. «Приложение должно быть удобным» — это пожелание, ему здесь не место.

Процесс согласования: кто, что и когда читает

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

sequenceDiagram
  participant B as Бизнес/<br/>Заказчик
  participant A as Аналитик
  participant D as Разработчик
  participant Q as QA
  participant PM as PM/Тимлид

  B->>A: Идея, проблема, желание
  A->>B: Уточняющие вопросы
  Note over A,B: Цели, метрики,<br/>границы (in/out scope)
  A->>A: Черновик ТЗ:<br/>контекст, Use Case, ФТ, НФТ
  A->>D: Ревью технической части
  D-->>A: Замечания по реализуемости
  A->>Q: Ревью критериев приёмки
  Q-->>A: Уточнения по тест-кейсам
  A->>B: Финальная версия ТЗ
  B->>PM: Согласование и подпись
  PM->>D: ТЗ в работу
  Note over D,Q: Реализация и проверка<br/>по критериям приёмки

На диаграмме видно главное: до того, как ТЗ попадёт в работу, его читают и комментируют минимум четыре роли. Разработчик ловит нереализуемые куски (например, «выводить отчёт за миллисекунду по 100 миллионам строк»), QA проверяет, можно ли по критериям приёмки написать тесты, заказчик подтверждает, что мы вообще решаем его проблему.

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

Шаблон ТЗ: готовая структура для копирования

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

1
# ТЗ: <название фичи/проекта>
2

3
## 1. Контекст и цели
4
- Проблема: ...
5
- Бизнес-цель: ...
6
- Метрика успеха: ...
7
- Сроки: ...
8

9
## 2. Глоссарий и роли
10
| Термин | Определение |
11
|--------|-------------|
12
| ... | ... |
13

14
## 3. Границы проекта
15
**In scope:**
16
- ...
17

18
**Out of scope:**
19
- ...
20

21
## 4. Use Case
22
### UC-001. <название>
23
- Актор: ...
24
- Предусловия: ...
25
- Главный сценарий: ...
26
- Альтернативы: ...
27
- Постусловия: ...
28

29
## 5. Функциональные требования
30
| ID | Формулировка |
31
|----|--------------|
32
| ФТ-01 | ... |
33

34
## 6. Нефункциональные требования
35
| Категория | Требование |
36
|-----------|------------|
37
| ... | ... |
38

39
## 7. Макеты
40
- Figma: <ссылка>
41
- Описание ключевых экранов: ...
42

43
## 8. Интеграции и API
44
- Внешние системы: ...
45
- Endpoints: ...
46
- Обработка ошибок: ...
47

48
## 9. Модель данных
49
- Сущности: ...
50
- Связи: ...
51

52
## 10. Критерии приёмки
53
- [ ] ...
54
- [ ] ...
55

56
## Приложения
57
- Swagger/OpenAPI
58
- Архитектурная схема
59
- Диаграммы состояний

Шаблон — отправная точка, а не священная корова. На небольшую фичу можно ужать до 4–5 разделов. На критичную интеграцию с банковским ядром — расширить ещё на безопасность, регуляторные требования и план миграции данных. Главное — сохранять смысловую полноту: контекст, поведение, границы, приёмка.

Типичные ошибки в ТЗ

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

Ошибка 1. Нет границ проекта

Раздел «in/out of scope» либо отсутствует, либо написан в виде «все стандартные фичи системы». В результате через месяц заказчик говорит «а я думал, что и история заказов туда тоже входит». Лечится одним подзаголовком: «Что не входит в проект».

Ошибка 2. ФТ написаны как пожелания

«Система должна быть удобной для пользователя» — это не функциональное требование, это лозунг. Стоит проверять каждое ФТ на проверяемость: можно ли по нему написать тест? Если нельзя — это не требование.

Ошибка 3. Все НФТ — словами «быстро», «надёжно», «безопасно»

«Система должна работать быстро» — кому быстро? при какой нагрузке? на каком процентиле? Без чисел НФТ — это сочинение на тему. Нужно: «p95 времени отклика API ≤ 300 мс при 1000 RPS». Если цифр нет — садитесь с разработчиком и придумывайте, иначе после релиза этих цифр всё равно никто не назовёт.

Ошибка 4. Нет описания обработки ошибок

В ТЗ красиво расписан happy path и ни слова о том, что делать, если внешний платёжный шлюз отвечает 500. А ведь именно этот случай попадёт в продакшн на третий день после релиза. Каждый сценарий должен иметь хотя бы один альтернативный поток.

Ошибка 5. ТЗ не согласовано с разработчиком до подписи

Аналитик пишет в одиночку, согласует с заказчиком, отправляет в работу — а на дейли разработчик говорит «это так не работает, тут нужен брокер сообщений и две недели ресёрча». Привет, переделка ТЗ задним числом.

Ошибка 6. Версионирование отсутствует

В ТЗ через два месяца внесли пять правок, а отследить, что изменилось — невозможно. Заведите changelog в начале документа: дата, автор, что изменилось. Это занимает 30 секунд и спасает часы споров.

Ошибка 7. Отсутствие критериев приёмки

«Когда поймём, что готово?» — «Ну, когда работать будет». Так не пойдёт. Чек-лист приёмки делает финал проекта детерминированным, а не зависящим от настроения заказчика в день демо.

Чеклист перед отправкой ТЗ на согласование

Прежде чем нажать «Отправить» в Confluence, пройдитесь по списку. Если хоть один пункт «нет» — возвращайтесь дописывать.

• Указаны бизнес-цель и измеримая метрика успеха
• Заполнены глоссарий и роли пользователей
• Явно прописаны границы проекта (in/out of scope)
• Описаны минимум главный Use Case + ключевые альтернативы
• ФТ атомарны, проверяемы, имеют ID
• НФТ содержат конкретные числовые значения
• Есть ссылки на макеты и описание ключевых экранов
• Описаны все интеграции и обработка ошибок
• Прописана модель данных и ключевые сущности
• Есть критерии приёмки в виде чек-листа
• Документ прошёл ревью разработчика и QA
• Заведён changelog с датой и автором изменений

Заключение

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

Я не верю в идеальные ТЗ. Любой документ устаревает уже на стадии разработки — появляются новые ограничения, меняются приоритеты, прилетают форс-мажоры. Но это не повод отказываться от ТЗ, это повод сделать его живым: с changelog, регулярными ревью, обновлениями на каждой итерации. Документ-источник правды, который ленятся обновлять, превращается в документ-источник лжи. И тогда уж лучше его вообще не было.

PS. Если в вашем проекте ТЗ начинается со слов «работает — не трогай», поздравляю — у вас не ТЗ, у вас фольклор. Перепишите.