Design records и ADR: как записывать устройство и решения

Сцена · нарисуй, как у нас всё устроено

В команду выходит подрядчик, и тебя просят: нарисуй, как у нас всё устроено. Ты открываешь доску и зависаешь. Для продакта ты бы нарисовал три квадратика: фронт, бэк, база. Для нового бэкендера двадцать: сервисы, очереди, кэши. Для девопса вообще другую картину: кластеры, балансировщики, зоны доступности. Какой из рисунков «архитектура»?

Все три. Проблема не в рисунках, а в том, что у них нет общей шкалы зума. Каждый раз ты рисуешь заново, на доске, которая умрёт после созвона. А рядом вторая беда, знакомая по прошлому уроку: решения, стоящие за рисунком, нигде не записаны. Почему очередь, а не HTTP? Почему Postgres на двоих, а не база на сервис?

Этот урок про этаж design-документов: жанры, в которых записывают устройство системы, и главный из них, ADR, запись принятого решения.

Карта урока · что заберёшь

• Карту design-жанров: от C4-диаграмм до capacity model, что зачем.
• C4: четыре уровня зума и почему уровень это ответ «для кого рисунок».
• RFC: как предлагать изменение письменно и зачем.
• Анатомию ADR: какие поля делают запись полезной через год.
• Когда ADR писать, а когда хватит комментария в PR: one-way и two-way doors.
• Жизненный цикл ADR: почему записи не редактируют, а вытесняют новыми.

Карта design-жанров

Жанров на этом этаже много, но они собираются в шесть групп по вопросу, на который отвечают:

Группа	Жанры	Вопрос
Структура	C4, deployment diagram, context map, domain model, data model	из чего система состоит
Контракты	API specification, event catalog, command catalog	как части договорились
Безопасность	threat model	кто и как нас сломает
Решения	RFC, ADR, PoC report, prototype record	почему так, а не иначе
Переход	migration plan, transition architecture	как доехать из A в B
Деньги и нагрузка	capacity model, cost model	сколько выдержит и сколько стоит

Не пугайся списка: никто не заводит все жанры разом. Правило то же, что в прошлом уроке: у документа должен быть читатель. Маленькому проекту хватает C4 на два уровня, API-спеки и папки ADR. Threat model заводят, когда появляются данные, которые жалко. Capacity и cost model, когда счёт за облако начинает удивлять.

Два моста. Threat model как практику со STRIDE и деревом угроз разбираем в уроке про моделирование угроз. Migration plan тесно связан с вертикальными срезами: хороший план перехода это серия живых срезов, а не один большой рубильник.

C4 · четыре уровня зума

Вернёмся к сцене. Три разных рисунка для трёх людей это не баг, а суть: архитектуру рисуют на разных уровнях зума. C4 делает зум явным. Четыре уровня, каждый со своей аудиторией:

1. Context: система как один квадрат плюс внешний мир. Кто пользователи, с какими чужими системами говорим. Аудитория: все, включая продакта.
2. Container: из каких процессов система состоит. Веб-приложение, API, база, очередь, воркер. Аудитория: инженеры и девопс.
3. Component: из каких модулей состоит один контейнер. Аудитория: команда, которая в этом контейнере живёт.
4. Code: классы и функции. Этот уровень почти никогда не рисуют руками: он устаревает за день, его генерируют из кода, если вообще нужен.

Главная дисциплина C4 не в нотации, а в запрете смешивать уровни. Рисунок, где рядом живут «Пользователь», «Сервис заказов» и «класс OrderValidator», не читается ни одной из аудиторий.

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

ContextContainerComponentCode

Ментичеловекпользуется→BatSchoolнаша системаписьма со ссылками→Resendчужая системаclass MagicLinkуровень Code

Диаграммы храни как diagrams-as-code: текстовый исходник лежит в репозитории, диффается в ревью и доступен агентам. Доска хороша для спора, git для памяти.

RFC · предложение до решения

Из словаря прошлого урока: RFC пишется до решения, ADR после. Теперь подробнее про «до».

RFC это способ спорить письменно. Вместо созвона, где побеждает самый громкий, автор раскладывает мысль на странице: проблема, предлагаемое решение, альтернативы, открытые вопросы. Команда комментирует асинхронно. К моменту встречи (если она вообще понадобится) все возражения уже собраны и на большинство отвечено.

Письменная форма даёт три эффекта:

• Полнота. Расплывчатая идея не переживает изложения на бумаге: дыры становятся видны самому автору ещё до отправки.
• Асинхронность. Команда в трёх часовых поясах обсуждает предложение без поиска общего слота в календарях.
• След. Через год виден не только итог, но и весь спор: какие альтернативы рассматривали, кто что предсказывал.

В индустрии формат живёт под разными именами: RFC в IETF и у большинства продуктовых команд, RFD у Oxide, design doc в Google. Механика одна: предложение в письменном виде, открытые комментарии, явный статус (черновик, обсуждение, принято, отклонено).

Принятый RFC порождает решение. Решение фиксируется коротко, и это уже следующий жанр.