Представьте: команда несколько дней обсуждала архитектуру, разошлась довольная, а через месяц никто не помнит, что именно решили и почему. Новый коллега предлагает те же варианты, которые уже отвергли. В проде всплывает сценарий падения, который никто не рассматривал.
Именно поэтому дизайн нужно записывать и проводить через ревью. Дизайн, который не записан — это мнение одного человека. Ревью делает его общим решением, на которое можно опираться.
Что такое design doc
Design doc — это короткий инженерный документ, который фиксирует: что строим, почему именно так, и какие варианты отвергли. Не презентация руководству, не техническое задание — а рабочий документ для команды.
Типичная структура:
# Платформа уведомлений — design doc
Статус: на ревью | Автор: ... | Ревьюеры: ... | Дата: ...
1. Контекст и задача — зачем строим, что болит сейчас
2. Требования — функциональные, числа, анти-требования
3. Оценки — расчёт нагрузки, выводы из чисел
4. Предлагаемый дизайн — контракты, модель данных, схема, горячие точки
5. Отказы и деградация — таблица «что лежит → что видит пользователь»
6. Рассмотренные альтернативы — что отвергли и почему
7. Развилки → ADR — ссылки на записанные решения
8. План: первая версия и далее — что строим сейчас, что отложено
9. Открытые вопросы — честный список нерешённого
Три секции особенно важны:
- Альтернативы — без них ревьюеры предложат те же варианты заново. Через год их принесёт новый коллега.
- Отказы и деградация — дизайн без сценариев падения не дизайн.
- Открытые вопросы — если список пуст, документ либо гениален, либо авторы не думали. Второй вариант вероятнее.
Оптимальный объём — 3–6 страниц. Пятнадцатистраничные простыни не читает никто; деталям место в приложениях и ссылках. Документ живёт в git рядом с кодом — тогда его можно ревьюить как pull request, видеть историю и легко найти.
Диаграммы: модель C4
Главная ошибка при рисовании архитектурных схем — один рисунок обо всём: контейнеры, классы и сетевые зоны в одной каше. Разобраться невозможно.
Модель C4 решает это уровнями. Каждый уровень — своя диаграмма с чёткой аудиторией:
Context — самый верхний уровень. Показывает систему и её соседей: кто пользователь, какие внешние системы задействованы. Понятен всем, включая нетехнических участников.
Container — основная диаграмма для design doc. Показывает сервисы, базы данных, очереди и связи между ними. Для читателя важно понять: из чего состоит система и как части общаются.
Component — внутренности одного контейнера. Рисуется только для «горячих точек» — мест, где есть архитектурная сложность. Нет смысла делать это для каждого сервиса.
Code — не рисуется вручную. Либо генерируется из кода, либо не нужен вовсе.
Практические правила для любого уровня:
- Каждую стрелку подписать: что передаётся и как (синхронно/асинхронно).
- Каждый элемент называть терминами из домена — не «Backend» и «Service 2», а «Сервис уведомлений» и «Очередь доставки».
- Хранить диаграммы как код (mermaid или PlantUML в git) — иначе они устареют к третьему ревью и никто не знает, актуальны ли они.
ADR: фиксируем важные развилки
В процессе проектирования возникают развилки — моменты, когда можно пойти двумя разными путями. Например: «Kafka или SQS?», «Лента в PostgreSQL или в MongoDB?».
Design doc описывает итоговое решение целиком. Но каждую существенную развилку имеет смысл фиксировать отдельно — в формате ADR (Architecture Decision Record).
Почему отдельно? Дизайн-документ читают один раз при ревью. ADR находят годами при вопросе «а почему здесь именно так?» — через полгода, при онбординге нового инженера, при аудите. Design doc ссылается на ADR-ы; ADR-ы переживают сам документ.
Подробнее о формате — в статье ADR.
Как проводить ревью дизайна
Ревью дизайна — это не формальность. Это поиск дыр до того, как написан код. Найденная проблема на ревью — экономия недель работы.
Рабочий процесс:
1. Документ — заранее. Минимум за два дня до встречи, чтобы участники успели прочитать и написать комментарии. Встреча, на которой документ видят впервые — это чтение вслух, а не ревью.
2. Встреча — по спорным местам. Не пересказ документа, а разбор собранных комментариев и открытых вопросов. 60–90 минут — разумный максимум.
3. Правильные ревьюеры. Хватит 2–4 человек. Обязательно должны быть: кто-то от эксплуатации этой системы и кто-то от потребителей её API. Ревью только архитекторами пропускает ровно те проблемы, которые всплывут в продакшене и у клиентов.
4. Итог — письменно. Решение (принято / принято с правками / переработать), список обязательных изменений, новые ADR. Без письменного итога через месяц никто не помнит, что решили.
Полезные вопросы для ревьюера:
- Какие числа? Откуда они? Что происходит на пике?
- Что видит пользователь при отказе компонента X?
- Зачем этот блок — какое требование его позвало?
- Где идемпотентность при ретраях?
- Как мигрируем или откатываемся?
- Что входит в первую версию, что отложено?
Вопрос, на который у автора нет ответа — нормальный результат ревью. Он уходит в открытые вопросы, а не закрывается уверенным тоном.
Типичные ошибки при защите дизайна
Дизайн как презентация. Красивые слайды вместо документа: нечего комментировать построчно, нечего вернуть через год. Слайды показывают, документ исследуют.
Автор защищается вместо того, чтобы слушать. Вопросы воспринимаются как атака, а не как помощь. Ревью — поиск дыр до продакшена; найденная дыра — выигрыш автора, не его поражение.
Ревью после начала разработки. Когда написана половина кода, ревью не способно ничего изменить — оно легализует сделанное. Дизайн ревьюится до спринта.
Бесконечное согласование. Пять раундов правок у пяти участников. Решается таймбоксом и явным владельцем решения: ревьюеры советуют, решает один человек — и записывает это.
«Все согласны» молчанием. Отсутствие комментариев — не согласие, а непрочитанный документ. Просить явный ответ от каждого ревьюера.
Коротко
- Design doc — 3–6 страниц: контекст, требования, оценки, дизайн, отказы, альтернативы, ADR, план, открытые вопросы.
- Секции «Альтернативы», «Отказы» и «Открытые вопросы» делают документ честным инженерным артефактом.
- Модель C4 делит диаграммы на уровни: Context (для всех), Container (главная для design doc), Component (только горячие точки).
- Диаграммы как код в git — иначе они устаревают и никто не знает, актуальны ли они.
- ADR фиксирует каждую важную развилку отдельно — их находят годами, design doc читают один раз.
- Документ отправляется минимум за два дня; встреча — по спорным местам, не пересказ.
- Ревью — поиск дыр до написания кода, не формальность после.
- Итог ревью всегда фиксируется письменно.
Что почитать дальше
- Метод системного дизайна — содержание, которое этот документ оформляет.
- Модель C4 — уровни диаграмм подробно.
- ADR — формат записи важных решений.
- Что делает архитектор — чья работа довести дизайн до решения.