Когда бизнесу нужна только архитектура — и как передать её другой команде

Передаю в работу. Архитектура готова, документация собрана, схема данных нарисована, backlog разложен — дальше команда разработки должна подхватить и довести систему до production. На практике этот момент оказывается одним из самых рискованных во всём проекте: не потому что архитектура плохая, а потому что передача устроена хуже, чем сама архитектура. Разберём, что именно должно лежать в коробке с надписью «handoff» и как не потерять по дороге смысл решений.

Что вообще заказывает бизнес, когда заказывает архитектуру

Начну с того, что сам заказ часто сформулирован криво. «Нам нужна архитектура» — это как «нам нужен план». План чего? На какой срок? С какой точностью? Первое, что приходится делать архитектору, — переводить расплывчатый запрос в конкретный результат этапа. И здесь важно понимать: бизнес редко покупает схемы и диаграммы. Бизнес покупает снятие неопределённости. Он платит за то, чтобы перестать гадать: выдержит ли система нагрузку, сколько будет стоить эксплуатация, где узкие места, какие решения придётся принять сейчас, а какие можно отложить.

Значит, результат архитектурного этапа — не папка документов, а набор артефактов, каждый из которых закрывает конкретный риск. Их обычно семь: границы системы, модель данных, интеграции, backlog, реестр рисков, критерии приёмки и сам handoff. Пропустишь любой — и команда, которой передают работу, начнёт додумывать. А додумывание в архитектуре стоит дорого.

Границы: где система начинается и где заканчивается

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

Границы описываются в трёх разрезах. Функциональные: какие возможности внутри, какие вне. Технические: какие сервисы наши, какие чужие, где API, где вебхуки, где батчи. Организационные: какая команда за что отвечает, кто владелец каждого модуля, кто принимает решения по изменениям.

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

Модель данных: главный артефакт, который чаще всего недооценивают

Если бы меня попросили выбрать один артефакт, который определяет судьбу проекта сильнее всех остальных, я бы выбрал модель данных. Не архитектуру сервисов, не выбор стека, не схему деплоя. Именно данные. Потому что сервисы можно переписать, стек заменить, деплой перенастроить. А миграцию данных в проде делают один раз и с болью.

На архитектурном этапе модель данных описывается на трёх уровнях. Концептуальном — какие сущности существуют и как связаны. Логическом — какие поля, типы, ограничения, ключи. Физическом — где хранится, как шардируется, как индексируется, что денормализуется. Все три нужны в handoff, потому что команда разработки начнёт с логического уровня, но упрётся в физический на второй неделе.

Отдельно — вопрос версионирования. Как меняются записи? Кто и когда может их править? Что происходит со старыми версиями? Если на эти вопросы нет ответа в документации, разработчик придумает свой — и почти наверняка не тот, который нужен бизнесу.

Интеграции: карта связей с внешним миром

Интеграции — второй по частоте источник сюрпризов. Каждая внешняя система — это отдельный характер: свои лимиты, свои форматы ошибок, свои расписания, свои причуды. Архитектурный этап должен зафиксировать карту этих связей: что с чем общается, в каком направлении, с какой частотой, что происходит при сбое.

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

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

Backlog: не список задач, а карта решений

Backlog на выходе архитектурного этапа — это не «что делать разработчикам». Это карта решений: какие архитектурные выборы уже сделаны и почему, какие оставлены открытыми и до какого момента, какие зависят от внешних факторов. Разница принципиальная. Список задач команда перепишет под себя, и это нормально. Карта решений — то, что нельзя переписать без потери смысла.

В backlog стоит фиксировать три типа записей. Обязательные к реализации — то, без чего система не заработает. Условные — то, что делается при определённых условиях: превышении нагрузки, изменении требований, появлении новой интеграции. Отложенные — то, что осознанно не делается сейчас, с указанием причины.

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

Риски: реестр, а не страшилка

Реестр рисков на архитектурном этапе — это не «список всего плохого, что может случиться». Это рабочий инструмент: для каждого риска указана вероятность, влияние, владелец и план реакции. Без владельца риск превращается в ритуальную запись, которую все игнорируют.

Риски удобно делить на четыре класса. Технические — связанные с выбором технологий, производительностью, надёжностью. Организационные — зависящие от команды, сроков, компетенций. Внешние — провайдеры, регуляторы, рынок. Продуктовые — изменения в требованиях, конкуренция, поведение пользователей.

Для каждого — план: принять, снизить, переложить или избежать. Если план — «принять», это тоже решение, но оно должно быть осознанным и подписанным, а не результатом того, что про риск просто забыли.

Критерии приёмки: как понять, что архитектура сдана

Здесь начинается область, где архитектурный этап чаще всего провисает. Как понять, что архитектура готова? Кто это решает? По каким критериям?

Плохой ответ: «когда архитектор сказал, что готово». Хороший — набор проверяемых условий. Границы описаны и согласованы. Модель данных покрывает все сценарии использования. Карта интеграций полная, с контрактами и сценариями деградации. Backlog содержит обязательные, условные и отложенные записи. Реестр рисков заполнен и подписан. Handoff-пакет собран и проверен на другой команде — например, на одном разработчике, который не участвовал в проектировании.

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

Анатомия handoff-пакета

Теперь соберём всё вместе. Handoff-пакет — это не папка с документами, а структура, где каждый элемент отвечает на конкретный вопрос команды разработки.

Что строим и зачем — краткое описание продукта и целей. Где границы — схема контуров и ответственности. Какие данные — модель данных на трёх уровнях с примерами. С кем общаемся — карта интеграций с контрактами. Что делаем — backlog с картой решений. Чего боимся — реестр рисков. Как понять, что готово — критерии приёмки.

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

Мнение автора

Кульминация: что на самом деле передаётся

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

Хороший признак — когда через месяц после передачи команда задаёт вопросы не про архитектуру, а про детали реализации. Значит, основа усвоена. Плохой признак — когда через месяц всплывают вопросы, ответы на которые были в документах, но их никто не прочитал. Значит, handoff был формальностью.

И ещё одно. Архитектурный этап редко заканчивается по расписанию. Обычно он заканчивается тогда, когда бизнес говорит «достаточно, начинаем строить». Это нормально, но означает, что в handoff-пакете всегда будет что-то незакрытое. Задача архитектора — не сделать всё, а честно обозначить, что осталось открытым, и оставить механизм для закрытия по ходу разработки.

Архитектура — это не финальная точка, а точка ветвления. И качество этой точки определяет, насколько дорого обойдётся вся остальная дорога.

Глоссарий терминов

• Handoff — процесс передачи архитектуры, документации и решений от архитектора к команде разработки. Результат этапа, а не бюрократическая формальность.
• Артефакт — материальный результат работы: документ, схема, реестр, набор тестов. То, что можно передать, проверить и переиспользовать.
• Границы системы — описание того, что входит в продукт, что остаётся снаружи и где проходит контур ответственности команды.
• Модель данных — формальное описание сущностей, их связей, полей и правил хранения. Существует на трёх уровнях: концептуальном, логическом, физическом.
• Концептуальная модель — верхний уровень описания данных: какие сущности есть и как они связаны, без привязки к технологиям.
• Логическая модель — средний уровень: конкретные поля, типы, ограничения, ключи. То, с чем работает команда разработки.
• Физическая модель — нижний уровень: где и как данные лежат физически — шардирование, индексы, денормализация.
• Шардирование — разбиение данных на части (шарды) для распределения нагрузки и упрощения масштабирования.
• Денормализация — сознательное дублирование данных для ускорения чтения. Обратная сторона — сложность поддержания консистентности.
• Интеграция — связь системы с внешним сервисом или другой системой. Описывается контрактом и сценариями поведения при сбоях.
• Контракт — формальное описание взаимодействия: форматы данных, коды ошибок, правила вызова.
• Вебхук — механизм, при котором внешняя система сама отправляет уведомление о событии на ваш сервис. Часто дублируется при повторных попытках.
• Идемпотентность — свойство операции давать один и тот же результат при повторном выполнении. Критично для вебхуков и платежей.
• Сценарий деградации — заранее описанное поведение системы при недоступности или сбое внешнего компонента.
• Backlog — в контексте архитектуры: карта решений и задач, зафиксированных на этапе проектирования. Три типа записей: обязательные, условные, отложенные.
• Реестр рисков — таблица рисков с указанием вероятности, влияния, владельца и плана реакции. Рабочий инструмент, а не отчёт.
• Критерии приёмки — проверяемые условия, при которых архитектурный этап считается завершённым.
• Журнал решений — документ, фиксирующий архитектурные выборы: что выбрали, какие альтернативы рассматривали, почему отказались.
• API — программный интерфейс для взаимодействия между системами.
• Батч — пакетная обработка данных: несколько операций выполняются группой, а не по одной.
• Production (прод) — рабочая среда, в которой система используется реальными пользователями.
• Миграция данных — перенос или преобразование данных при изменении структуры хранения. Одна из самых рискованных операций в проде.