Введение: почему большим системам нужны маленькие рисунки

Большинство крупных программных систем разваливается не из‑за плохого кода. Они разваливаются потому, что больше никто не может увидеть, как их части сочетаются друг с другом.

Страницы в Confluence устаревают. Формальные архитектурные документы превращаются в пыль на полке. Диаграммы рисуют один раз для презентации — и забывают. Система продолжает эволюционировать, а визуальное понимание её устройства — нет.

Есть на удивление простое противоядие: крошечные, будто бы одноразовые бумажные схемы, к которым вы относитесь как раз не как к одноразовым.

Думайте об архитектуре как о саде. Если вы «благоустраиваете» его только на старте проекта и больше никогда не ухаживаете, там вырастают сорняки. Если же вы держите под рукой несколько небольших, легко изменяемых набросков, вы можете обрезать, пересаживать и перестраивать сад по мере роста системы.

В этом посте разберём, как на практике работает «липкий архитектурный сад»:

• Старт с нарисованных от руки бумажных диаграмм
• Превращение этих набросков в живые, отслеживаемые артефакты
• Связка диаграмм, решений и кода для улучшения ревью
• Использование стандартных языков моделирования (как UML) как общего визуального словаря
• Комбинация лёгких визуализаций с рефакторингом, паттернами и принципами SOLID
• Регулярное визуальное садоводство, чтобы диаграммы оставались синхронизированы с реальностью

Маленькие бумажные диаграммы: старт с минимальным трением

Сессии у доски кажутся продуктивными, потому что они быстрые и совместные. Бумажные диаграммы — то же самое, только портативные и постоянные.

Почему начинать на бумаге?

• Мало трения: не нужно устанавливать инструменты, спрашивать доступы, настраивать форматирование. Просто рисуете.
• Не страшно: люди, которые «ненавидят UML», всё равно готовы быстро чертить квадратики и стрелки.
• Высокий сигнал: ограниченность места заставляет фиксировать только самое важное.

Несколько полезных шаблонов маленьких диаграмм:

• Контекстный набросок (1 лист): кто пользуется системой? Какие внешние системы есть? Где главные границы?
• Ключевые компоненты (1–2 листа): основные сервисы, базы данных и потоки между ними.
• Одна фича — одна диаграмма: минимальная структура, необходимая для реализации нового функционала.

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

Фокус в том, что дальше вы не выбрасываете эти диаграммы.

От набросков к живым архитектурным артефактам

Большинство диаграмм умирает, потому что к ним относятся как к статичным deliverable’ам. Фича вышла — рисунок «закончен».

Вместо этого относитесь к каждой диаграмме как к живому артефакту:

• У неё есть чёткая цель (на какой вопрос она отвечает).
• У неё есть владельцы (кто обновляет её при изменениях).
• Её легко править (она не заперта в тяжёлом инструменте или громоздком формате).

Со временем это превращается в хлебные крошки архитектурного знания:

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

Поскольку диаграммы маленькие и сфокусированные, их реально поддерживать в актуальном состоянии:

• Появился новый endpoint? Обновляем диаграмму на уровне конкретной фичи.
• Появилась новая граница сервиса? Перерисовываем соответствующий кусок контекстной диаграммы.

Каждое обновление — это маленькое садовое действие: выдернуть сорняк, подстричь ветку, посадить новый куст. Сад остаётся здоровым, потому что уход за ним непрерывен и лёгок.

Делаем архитектуру отслеживаемой: диаграммы, решения и код

Архитектура становится по‑настоящему полезной, когда вы можете связать три вещи:

1. Как система выглядит (диаграммы)
2. Почему она так выглядит (решения)
3. Где это реально живёт (код)

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

Простая, но мощная практика:

• Каждое архитектурно значимое изменение сопровождается небольшой записью о решении (ADR или аналог):
  • Контекст: какую проблему решаем
  • Решение: что выбрали
  • Последствия: компромиссы, риски, влияние
• Каждое решение ссылается на конкретные диаграммы, которых оно касается.
• Каждая диаграмма ссылается на конкретные артефакты кода (модули, сервисы, репозитории).

Примеры связей:

• В ADR: «См. service-split-v2.png для новой границы сервиса».
• На диаграмме: «Реализует ADR‑017: отделение биллинга от управления заказами».
• В коде (например, в README или комментариях): «Этот модуль реализует “Billing Context” из диаграммы system-context-2025-01».

Это позволяет:

• Делать анализ влияния: «Если мы изменим API этого сервиса, какие диаграммы и решения заденем?»
• Проводить дизайн‑ревью: «Покажите диаграмму и ADR для этой новой шины событий».
• Проходить аудиты и оценки: «Как вы обеспечиваете разделение ответственности на этом уровне?»

Вместо разрозненных документов у вас появляется переплетённая ткань визуализаций, доводов и реализации.

Общий визуальный язык: от каракулей к UML (ненавязчиво)

Рисованные от руки квадратики и стрелки — отличны, пока люди по‑разному их не трактуют.

Здесь помогает стандартный язык моделирования, такой как UML (или C4, SysML, ArchiMate и др.). Не для тяжёлого моделирования, а как общий визуальный словарь.

Вам не нужен весь спецификатор UML. Нужен минимально достаточный набор:

• Простые диаграммы классов или компонентов для структуры
• Диаграммы последовательностей для ключевых взаимодействий
• Возможно, диаграммы развертывания для того, где что крутится

Плюсы такой лёгкой стандартизации:

• Новые члены команды могут читать старые диаграммы без легенды.
• Команды могут дорабатывать и уточнять диаграммы друг друга без путаницы.
• Визуализации можно переносить между инструментами при необходимости.

Практичный подход:

1. Начинайте наброски на бумаге с UML‑подобных фигур: прямоугольники для компонентов, стрелки для вызовов, «человечки» для акторов.
2. Диаграммы, которые оказались долгоживущими или особенно полезными, оцифровывайте в лёгком инструменте.
3. Держите одностраничный «гайд по визуальному стилю»: что означает какой символ, правила именования и типичные уровни детализации.

Цель — не формальность. Цель — общий смысл.

Связь изменений в коде с архитектурным замыслом

Ваш архитектурный сад становится ещё сильнее, когда вы связываете его с привычными сущностями уровня кода:

• Рефакторинг: когда вы рефакторите модуль (например, выносите класс, вводите интерфейс), обновляйте соответствующую структурную диаграмму.
• Паттерны проектирования: применяете паттерн (например, Strategy, Adapter, CQRS) — покажите его явно на диаграмме.
• Принципы SOLID: используйте диаграммы, чтобы визуализировать, где расположены ответственности, куда направлены зависимости и где находятся абстракции.

Примеры:

• Перед крупным рефакторингом набросайте рядом текущий дизайн и целевой дизайн.
• При внедрении паттерна добавьте небольшую пометку: «Здесь используется Strategy для изоляции правил ценообразования».
• При соблюдении SOLID используйте диаграммы, чтобы подсветить нарушения (например, класс, в который «стреляют» стрелки отовсюду; сервис, владеющий несвязанными ответственностями).

Так возникает цикл обратной связи:

1. Высокоуровневый замысел зафиксирован визуально.
2. Вносятся изменения в код и выполняется рефакторинг.
3. Диаграммы обновляются, чтобы соответствовать реальности.

Разработчики начинают думать архитектурно, пока пишут код, потому что архитектура — это не что‑то эфемерное из редких «архитектурных встреч», а то, что они видят и формируют каждый день.

Визуальное садоводство: подрезать, рефакторить, переставлять

Метафора сада полезна ещё и тем, что архитектурная работа никогда не заканчивается. Главное — сделать её поддержание маленьким и регулярным.

Несколько практик «визуального садоводства»:

• Еженедельная обрезка: уделяйте 15–30 минут на командной встрече разбору 1–2 ключевых диаграмм.
  • Удаляйте устаревшие элементы.
  • Добавляйте отсутствующие компоненты.
  • Исправляйте вводящие в заблуждение или старые подписи.
• Рефакторьте диаграммы, когда они становятся перегруженными:
  • Разбейте расползшуюся диаграмму на две более сфокусированные.
  • Поменяйте компоновку, чтобы подчеркнуть основной поток и спрятать второстепенную сложность.
  • Вынесите повторяющиеся структуры в отдельный общий «паттерн‑набросок».
• Периодически пересобирайте набор диаграмм:
  • Архивируйте действительно устаревшие схемы в явно помеченную «историю».
  • Поднимайте часто используемые диаграммы на «первую страницу».
  • Добавляйте теги или папки по фичам, доменам или границам систем.

Задача — не быть идеально актуальными каждую секунду. Задача — быть достаточно близко к реальности, чтобы диаграммы были полезны:

• Для онбординга
• Для отладки сквозных проблем
• Для планирования крупных изменений или миграций

Если разработчики видят, что диаграммы в основном точны и легко правятся, они будут ими пользоваться и обновлять их.

И вот это и делает архитектуру липкой.

Как вырастить липкую архитектурную практику

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

Чтобы к этому прийти:

1. Начните с малого: по одной бумажной диаграмме на важную фичу или сервис.
2. Включите обновление диаграмм в Definition of Done для архитектурных изменений.
3. Фиксируйте решения в лёгком формате и связывайте их с диаграммами.
4. Примите минимальную общую нотацию, чтобы диаграммы были согласованными и читаемыми.
5. Запланируйте регулярное «садоводство» — короткие сессии, маленькие улучшения.

Вам не нужен огромный репозиторий моделей или отдельная «архитектурная команда», чтобы начать. Вам нужны:

• Ручка, немного бумаги или стикеров
• Общая папка или доска
• Немного дисциплины вокруг связки диаграмм, решений и кода

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

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