Технические документы: как писать

Технический документ (tech doc, design doc, RFC) — структурированный текст, описывающий техническое решение, его контекст, варианты и обоснование для получения обратной связи от команды до начала реализации.

Зачем нужно

Написание технического документа до начала кода заставляет думать о решении системно: находишь противоречия, пропущенные edge cases и лучшие альтернативы — ещё в тексте, а не в середине разработки. Для Senior и Tech Lead это основной способ коммуникации архитектурных решений.

Где используется

  • Крупные фичи — прежде чем тратить 2+ недели на реализацию
  • Архитектурные изменения — выбор технологии, паттерна
  • API контракты — договорённость между frontend и backend
  • RFC (Request for Comments) — в open source проектах

Структура Design Doc

# [Название: что делаем]

## Статус
Draft / In Review / Approved / Deprecated

## Автор(ы)
@username | Дата: 2026-04-10

## Контекст и проблема
Почему эта задача возникла? Что не работает сейчас?

Пример:
"Авторизация сейчас хранит токен в localStorage.
Уязвимо к XSS-атакам: скрипт может украсть токен.
Нужно безопасное хранение сессии."

## Цели
- Что должна решить эта реализация?
- Измеримые критерии успеха

## Нецели (Out of Scope)
- Что явно не входит в эту задачу

## Варианты решения

### Вариант A: HttpOnly Cookies
Плюсы: недоступно JS, защита от XSS
Минусы: CSRF уязвимость, сложнее с мобильными клиентами

### Вариант B: sessionStorage вместо localStorage
Плюсы: не переживает перезагрузку (меньше риск)
Минусы: всё ещё доступно JS, всё ещё XSS

## Выбранное решение
HttpOnly Cookies + CSRF-токен в заголовке.
Обоснование: [объяснение trade-offs]

## Детали реализации
Схема работы, последовательность действий,
примеры кода если нужны.

## Влияние
- Что изменится для пользователей?
- Что изменится для разработчиков?
- Зависимости: какие команды/сервисы затронуты?

## Риски
| Риск | Вероятность | Митигация |
|------|-------------|-----------|
| CSRF атака | Средняя | CSRF-токен в заголовке |

## Открытые вопросы
-  Как обновлять токен для мобильных приложений?
-  Нужна ли поддержка SSO?

Принципы хорошего tech doc

Чёткость важнее полноты:
  Лучше короткий понятный документ,
  чем длинный, который никто не прочитает

Целевая аудитория:
  Кто будет читать? Технари? PO? Инфра?
  Адаптируй уровень детализации

Конкретные примеры:
  Абстрактное описание → конкретный пример

Версионирование статуса:
  Draft → In Review → Approved → Deprecated
  Дата последнего обновления

Процесс: Write → Review → Decide

1. Напиши черновик (1–2 часа)
2. Поделись с коллегами: "Дайте комментарии до X"
3. Проведи sync-встречу для спорных вопросов
4. Обнови документ с принятым решением
5. Меняй статус на Approved
6. Коммить в репозиторий (docs/design/)

Частые ошибки

Ошибка Проблема Решение
Писать после реализации Документ не влияет на решение Писать ДО начала кодирования
Только одно решение без альтернатив Нет понимания trade-offs Минимум 2 варианта с их оценкой
Слишком длинный (30+ страниц) Никто не читает Цель: 1–3 страницы, детали в приложении
Нет статуса / автора / даты Непонятно актуален ли документ Всегда указывать мета-данные

Связанные темы

Ресурсы