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