Архитектура как код: модель C4, DSL и навигация для ИИ-агентовЛонгрид · дайджест за 7 ноября
Изометрическая многоуровневая модель C4 из четырех парящих стеклянных платформ Context, Containers, Components и Code, вырастающих из файла Structurizr DSL.
Лонгрид6 разделов≈ 13 мин

Архитектура как код: модель C4, DSL и навигация для ИИ-агентов

Вспомни, как обычно выглядит обсуждение архитектуры в среднестатистической продуктовой команде. Кто-то открывает онлайн-доску в Miro или Confluence, где нарисовано полтора десятка разноцветных прямоугольников с подписями «Сервис авторизации», «Шина данных» и «Бэкенд». Стрелочки направлены во все стороны сразу: одни показывают сетевые вызовы, другие — поток данных, третьи — зависимость по деплою. На вопрос «А что внутри сервиса авторизации?» тимлид вздыхает и говорит: «Там легаси на Express, половину переписали на Go, в схеме этого нет, надо смотреть в прод».

Через три месяца проект расширяется, появляются новые микросервисы, а старая картинка превращается в никому не нужный исторический памятник. Разработчики перестают смотреть в документацию, потому что она врет, а архитектурные решения принимаются «на коленке» прямо в ветках репозитория.

В начале 2000-х годов с этой проблемой пытались бороться с помощью стандарта UML (Unified Modeling Language), созданного консорциумом OMG. Но академическая сложность UML с его четырнадцатью типами диаграмм и строгими нотациями стрелочек задохнулась в эпоху Agile: команды просто не успевали обновлять тяжеловесные документы. Британский архитектор Саймон Браун (Simon Brown) предложил гениальный по своей простоте выход — модель C4, вдохновленную принципом масштабирования географических карт Google Maps.

А сегодня этот подход переживает второе рождение благодаря парадигме Architecture as Code (AaC) и языку Structurizr DSL. В серии глубоких исследований и лекций украинский инженер Тимур Шемсединов показал, как C4 решает принципиально новую задачу 2026 года: превращается в структурированную систему координат для ИИ-агентов (Claude, Cursor, Copilot, Windsurf), спасая команды от взрывного расхода токенов и архитектурных галлюцинаций.

Давай разберем эту многослойную механику от фундаментальных абстракций до практического кода и интеграции с нейросетями.

От бюрократии UML к масштабу Google Maps: истоки модели C4

Чтобы оценить элегантность C4, нужно на секунду вернуться в эпоху RUP (Rational Unified Process) конца 1990-х. Инженерная парадигма тех лет требовала «проектировать все до первой строчки кода». Аналитики месяцами рисовали комплекты UML: Use Case Diagrams, Sequence Diagrams, Component Diagrams, Deployment Diagrams.

Но когда индустрия перешла на двухнедельные спринты, continuous delivery и микросервисы, в UML вскрылись три системных порока:

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

Саймон Браун обратил внимание на простую аналогию: как человек ориентируется в физическом мире? Ты открываешь Google Maps на смартфоне. На первом экране ты видишь континенты и страны. Это позволяет понять, где мы вообще находимся на глобусе. Приближаешь масштаб — появляются границы регионов, крупные города и магистрали. Еще зум — улицы, номера домов и повороты.

Модель C4 перенесла эту многоуровневую оптику в программную инженерию. Браун выделил четыре строгих уровня абстракции:

  • Context (Системный контекст);
  • Containers (Контейнеры);
  • Components (Компоненты);
  • Code (Код).

Каждый уровень отвечает на вопрос строго определенной аудитории и отсекает технический шум, ненужный на данном масштабе.

Четыре уровня абстракции C4: Context, Containers, Components, Code

Давай подробно препарируем каждый из четырех слоев модели.

1. Уровень 1: Системный контекст (System Context Diagram)

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

Главное железное правило первого уровня: никаких технических деталей. Здесь строго запрещено писать «PostgreSQL», «Kafka», «gRPC», «Go» или «Linux». Только бизнес-роли и суть передаваемых данных: «Покупатель оформляет заказ», «Платежный сервис списывает средства». Эту диаграмму должен с первого взгляда понимать генеральный директор компании, инвестор и новый стажер в первый день онбординга.

2. Уровень 2: Контейнеры (Container Diagram)

Мы делаем первый шаг зума и «заглядываем внутрь» программной системы. И здесь важно не попасться в терминологическую ловушку: в модели C4 «контейнер» — это не Docker-контейнер и не Kubernetes Pod.

В понимании Саймона Брауна контейнер — это любая отдельно развертываемая или исполняемая единица программного обеспечения, которая хранит данные или исполняет код:

  • Клиентское Single Page Application в браузере (React, Vite);
  • Мобильное приложение (iOS / Android на Flutter);
  • Серверный API-микросервис (Go, Node.js или Java);
  • Реляционная база данных (PostgreSQL);
  • Распределенный брокер сообщений (Apache Kafka);
  • Объектное хранилище (MinIO / S3).

Диаграмма контейнеров — это любимая рабочая схема архитекторов, DevOps-инженеров и бэкендеров. Она показывает высокоуровневую топологию: какие сервисы существуют, за что отвечает каждый из них, на каких технологиях они построены (например, NestJS / TypeScript, PostgreSQL 16) и по каким протоколам они общаются (JSON/HTTPS, gRPC, Kafka Protocol).

3. Уровень 3: Компоненты (Component Diagram)

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

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

4. Уровень 4: Код (Code Diagram)

Это предельный уровень детализации: диаграммы классов UML или сущностей Entity-Relationship (ER), отображающие интерфейсы, методы и зависимости в коде.

Современный инженерный консенсус предельно однозначен: уровень 4 категорически не нужно моделировать вручную. Классы и сигнатуры функций меняются в каждом коммите. Ручное ведение кода в архитектурных схемах моментально устаревает. Если диаграмма классов действительно необходима, она должна автоматически генерироваться из AST-дерева компилятором или средствами IDE.

Architecture as Code: единый источник правды на базе Structurizr DSL

Когда команды начинают внедрять C4, первой ошибкой обычно становится попытка рисовать эти диаграммы в графических редакторах вроде Draw.io, Lucidchart или Visio. Это тупиковый путь.

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

Парадигма Architecture as Code (AaC) проводит фундаментальную границу между моделью системы и ее визуальными представлениями (views).

Язык Structurizr DSL, разработанный Саймоном Брауном, предлагает декларативный текстовый синтаксис:

  1. В корне объявляется блок workspace.
  2. Внутри блока model единожды создаются все акторы, системы, контейнеры и связи между ними.
  3. В блоке views декларируются диаграммы: systemContext, container, component. Команда include * сама выбирает нужные элементы из единой модели, а алгоритм autoLayout автоматически рассчитывает их экранные координаты.

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

Давай посмотрим на полноценный пример архитектурного манифеста интернет-магазина:

workspace "Маркетплейс" "Архитектурная модель сервисов электронной коммерции" {

    model {
        customer = person "Покупатель" "Пользователь интернет-магазина, выбирающий товары"
        support = person "Оператор поддержки" "Сотрудник контакт-центра"

        ecommerce = softwareSystem "Платформа покупок" "Обеспечивает витрину, обработку корзины и учет заказов" {
            webApp = container "Web SPA" "Интерфейс в браузере клиента" "React, TypeScript"
            mobileApp = container "Мобильное приложение" "Клиент для iOS и Android" "Flutter"
            apiGateway = container "API Gateway" "Маршрутизация вызовов и аутентификация" "Envoy, Go"
            orderService = container "Сервис заказов" "Бизнес-логика оформления и смены статусов" "Node.js, NestJS"
            paymentService = container "Сервис платежей" "Взаимодействие с банками и фискализация" "Go, gRPC"
            orderDb = container "База данных заказов" "Хранение заказов и истории транзакций" "PostgreSQL 16"
            eventBus = container "Шина событий" "Асинхронная доставка доменных событий" "Apache Kafka"

            # Связи контейнеров внутри системы
            webApp -> apiGateway "Отправляет API-запросы" "JSON/HTTPS"
            mobileApp -> apiGateway "Отправляет API-запросы" "JSON/HTTPS"
            apiGateway -> orderService "Маршрутизирует вызовы заказов" "gRPC"
            apiGateway -> paymentService "Маршрутизирует платежи" "gRPC"
            orderService -> orderDb "Читает и пишет данные" "TCP/SQL"
            orderService -> eventBus "Публикует событие OrderCreated" "Kafka Protocol"
            paymentService -> eventBus "Подписан на события заказов" "Kafka Protocol"
        }

        bank = softwareSystem "Банковский шлюз" "Внешний процессинг банковских карт" "Внешняя система"

        # Внешние взаимодействия
        customer -> webApp "Просматривает каталог и покупает" "HTTPS"
        customer -> mobileApp "Пользуется приложением" "HTTPS"
        support -> webApp "Разбирает претензии по заказам" "HTTPS"
        paymentService -> bank "Инициирует безналичное списание" "REST/HTTPS"
    }

    views {
        systemContext ecommerce "SystemContext" "Диаграмма контекста платформы" {
            include *
            autoLayout lr
        }

        container ecommerce "Containers" "Топология контейнеров платформы" {
            include *
            autoLayout tb
        }

        styles {
            element "Person" {
                shape Person
                background #08427b
                color #ffffff
            }
            element "Software System" {
                background #1168bd
                color #ffffff
            }
            element "Container" {
                background #438dd5
                color #ffffff
            }
            element "Database" {
                shape Cylinder
            }
        }
    }
}

Этот файл хранится прямо в репозитории проекта по пути docs/architecture/workspace.dsl. Он проходит версионирование в Git, рецензируется через Pull Request, а любые изменения архитектуры видны в стандартном git diff.

Инструментальная экосистема: Structurizr Lite, экспорт в Mermaid и CI/CD

Текстовое описание в виде кода было бы бесполезным, если бы его нельзя было наглядно показать людям. Вокруг Structurizr DSL сформировалась зрелая экосистема утилит:

1. Structurizr Lite

Это компактный веб-сервер, распространяемый в виде Docker-контейнера. Он запускается на локальной машине разработчика буквально одной командой:

docker run -it --rm -p 8080:8080 -v $(pwd)/docs/architecture:/usr/local/structurizr structurizr/lite

Ты открываешь в браузере http://localhost:8080 и получаешь полноценную интерактивную карту системы. Можно приближать масштабы, кликать по контейнерам, подсвечивать связи и читать встроенную документацию. При сохранении файла workspace.dsl в IDE браузер мгновенно обновляет диаграммы на лету.

2. Structurizr CLI и мультивендорный экспорт

Если тебе нужно встроить схемы в проектную документацию на GitHub или в Confluence, консольная утилита structurizr-cli экспортирует единую модель в любой популярный графический синтаксис:

# Экспорт диаграмм в формат Mermaid для красивого рендеринга на GitHub
structurizr-cli export -w docs/architecture/workspace.dsl -f mermaid -o docs/images/

# Экспорт в C4-PlantUML для генерации растровых схем
structurizr-cli export -w docs/architecture/workspace.dsl -f plantuml -o docs/images/

Альтернативный вариант для команд, уже привыкших к PlantUML, — использование библиотеки C4-PlantUML, где схожая топология декларируется макросами:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_WITH_LEGEND()

Person(customer, "Покупатель", "Клиент маркетплейса")
System_Boundary(c1, "Платформа покупок") {
    Container(spa, "Web SPA", "React, TS", "Клиентский веб-интерфейс")
    Container(gateway, "API Gateway", "Go / Envoy", "Точка входа и аутентификация")
    Container(orders, "Сервис заказов", "NestJS", "Бизнес-логика заказов")
    ContainerDb(db, "База заказов", "PostgreSQL", "Реляционное хранилище")
}

Rel(customer, spa, "Оформляет заказ", "HTTPS")
Rel(spa, gateway, "API-запросы", "JSON/HTTPS")
Rel(gateway, orders, "Маршрутизация", "gRPC")
Rel(orders, db, "Чтение / запись", "SQL")
@enduml
3. Архитектурный линтинг в CI/CD

Самое приятное в подходе Architecture as Code — возможность превратить архитектурную документацию в обязательную часть пайплайна непрерывной интеграции. В GitHub Actions или GitLab CI добавляется шаг валидации:

structurizr-cli validate -w docs/architecture/workspace.dsl

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

Координатная сетка для ИИ-агентов: граф вместо слепого контекста

А теперь давай посмотрим на самое захватывающее применение моделей C4, о котором говорил Тимур Шемсединов. В 2026 году разработка программного обеспечения фундаментально трансформировалась: программисты больше не пишут весь код вручную, а делегируют реализацию фичей автономным ИИ-агентам (Claude 3.7 Sonnet, OpenAI Codex, Cursor, Windsurf).

Топологическая карта-схема Structurizr DSL, по которой ИИ-агент точно находит контейнеры orderService и orderDb в обход остального репозитория.

С ростом контекстных окон нейросетей до сотен тысяч и миллионов токенов у многих разработчиков возникла опасная иллюзия: «Зачем заморачиваться со структурированием? Давайте просто зальем в промпт весь монорепозиторий целиком — пусть нейросеть сама во всем разберется!»

На практике такой подход приводит к катастрофическим последствиям:

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

Архитектурный файл Structurizr DSL выступает для ИИ-агента топологической картой метрополитена.

Вместо сканирования гигабайтов исходников агент на первом шаге читает компактный DSL-файл размером всего 3–5 килобайт. За пару десятков миллисекунд модель получает полную ментальную модель проекта:

  • Какие сервисы существуют и каковы их четкие зоны ответственности;
  • Какие технологии и фреймворки используются в каждом контейнере;
  • По каким протоколам и с какими гарантиями взаимодействуют узлы.

Получив пользовательскую задачу (например, «Добавить скидочные купоны в оформление покупки»), агент по графу C4 Containers мгновенно вычисляет, что изменения затрагивают исключительно контейнеры orderService и orderDb. Агент целенаправленно открывает только каталог apps/order-service, не трогая миллионы строк в остальных частях монорепозитория. Это снижает расход токенов на 80–90% и гарантирует, что ИИ не сломает архитектурные соглашения команды.

Границы применимости, антипаттерны и защита от архитектурного дрейфа

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

  • Антипаттерн «Ручной микроменеджмент классов»: Попытка описывать компоненты до уровня мелких хелперов и DTO превращает DSL в неподъемную рутину. Держи модель на уровне крупных архитектурных модулей.
  • Антипаттерн «Картинки ради картинок»: Если команда рисует C4 в онлайн-досках без использования DSL, теряются все преимущества версионирования, рендеринга и интеграции с ИИ.
  • Проблема динамических процессов: Модель C4 великолепно передает статическую структуру систем, но слабо подходит для визуализации сложных временных распределенных саг, параллельных коллизий и гонок состояний. Для таких задач диаграммы последовательности (Sequence Diagrams) по-прежнему незаменимы и отлично дополняют C4 на уровне документации.
  • Борьба с архитектурным дрейфом (Architecture Drift): Чтобы код не расходился с моделью со временем, передовые команды подключают тесты архитектурной целостности (ArchUnit в мире JVM или ts-arch в TypeScript). Тесты парсят фактические импорты в репозитории и сверяют их с задекларированными стрелочками в workspace.dsl.

В результате Architecture as Code перестает быть скучной бюрократической повинностью. Это живой каркас, который позволяет людям и искусственному интеллекту говорить на одном понятном языке и строить надежные, масштабируемые цифровые системы.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 4