Архитектура на виду: как ИИ-агенты делают скрытые связи «вайбкода» очевидными
Хайп вокруг ИИ-кодинга привел к созданию проектов, внешне аккуратных, но внутренне хаотичных. Автор статьи демонстрирует, что ИИ-агенты с подключенными инструментами анализа архитектуры способны выявить скрытые связи между репозиториями — проблемы, невидимые в изолированном коде. Использование таких инструментов превращает разрозненные файлы в понятную карту системы, позволяя избежать технических долгов и обеспечить правильный онбординг новых разработчиков.
# Архитектура на виду: как ИИ-агенты делают скрытые связи «вайбкода» очевидными
Быстрый темп разработки часто приводит к тому, что проекты создаются без глубокого продумывания архитектуры. Сначала появляется MVP, затем пользователи находят баги, и команда начинает чинить их, добавляя новые технические долги. В условиях, когда код пишется быстрее, чем успевает быть спроектированным, возникает сложная проблема: как понять, что происходит внутри системы, состоящей из множества разрозненных репозиториев?
Автор статьи описывает эксперимент: он собрал работающий SaaS-сервис для нарезки видео и подкастов из четырех репозиториев, каждый из которых на первый взгляд выглядит как чистый и правильный код. Затем он попросил ИИ-агента восстановить архитектуру этой системы. Результат стал неожиданным: агента удалось выявить скрытые прямые подключения к базе данных, незащищенные внутренние вебхуки и мертвый код, которые были невидимы при обычном изучении кода.
Ниже представлен детальный разбор эксперимента и объяснение того, как современные инструменты анализа архитектуры помогают решать проблемы «вайбкодинга» (быстрого прототипирования) в промышленных условиях.
Проблема скрытых зависимостей в модульных системах
Представим проект, состоящий из четырех отдельных репозиториев, собранных в единую систему с помощью Docker Compose. С виду это идеальная структура: * clipcast-web: Веб-интерфейс на React + TypeScript. * clipcast-api: Основной сервис на Java 21 + Spring Boot. * clipcast-transcriber: Воркер на Python для транскрибации. * clipcast-clipper: Воркер на Node.js для создания клипов.
Если открыть любой из этих репозиториев в отдельности, код кажется написанным по всем правилам. Есть типизация, четкое разделение слоев, стандартные шаблоны Spring Boot и аккуратный Python. Однако, когда мы объединяем их в работающую систему, на поверхность выходят проблемы, которые код одного репозитория описать не может.
Скрытые связи к базе данных. Интуитивно кажется, что единственный сервис, работающий с данными, — это clipcast-api. Однако анализ кода показывает, что воркер транскрибации (clipcast-transcriber) и воркер клиперов (clipcast-clipper) также содержат прямые подключения к той же базе данных Postgres. В коде это реализовано в виде небольших файлов конфигурации всего по несколько строк. Но на уровне архитектуры это означает, что три разных сервиса пишут в одну таблицу, обходя основной API. Это создает риски: если разработчик в Java-сервисе изменит структуру базы данных, это сломает работу Python и Node.js сервисов. В изолированном коде такая связь не очевидна.
Гибридная архитектура потока данных. Логика работы системы частично построена на событиях через брокер сообщений Redis, а частично — на прямых HTTP-вызовах. Например, процесс создания клипов должен начинаться с загрузки медиафайла, затем следует транскрибация и только потом нарезка. Путь данных описывается как цепочка событий: media.uploaded → транскрипция → transcript.ready → клипы. Но финальный этап завершения работы запускается прямым HTTP-запросом к внутреннему эндпоинту. В коде это выглядит как одна строчка запроса, но в архитектурной диаграмме такая связь нарушает общую логику событийной шины и создает точку отказа.
Вопросы безопасности и поддержки. При просмотре всех репозиториев легко упустить внутренние эндпоинты, не предназначенные для внешнего использования. В данном случае существует эндпоинт /internal/clips/ready, который не проверяет авторизацию и не удостоверяет принадлежность проекта. Любой, кто имеет доступ к этому порту, может пометить чужой проект как завершенный. Кроме того, в коде может оставаться «мертвый код» — например, устаревший эндпоинт для проверки здоровья системы, который больше не вызывается нигде, но его удаление может быть опасным без понимания контекста.
Эти проблемы не являются плохим качеством кода в вакууме. Каждая из них — разумное решение, принятое в моменте для ускорения разработки. Но когда их много, и они скрыты между репозиториями, система становится хрупкой и трудно поддерживаемой.
Инструменты реверс-инжиниринга с помощью ИИ
Чтобы систематизировать поиск таких проблем, можно использовать подход реверс-инжиниринга: попросить ИИ-агента проанализировать код и восстановить архитектуру. Однако просто передать код агента недостаточно. Агенты, работающие в изоляции, видят только код одного репозитория и могут упустить глобальные связи.
В качестве инструмента анализа используется платформа Viaduct, которая поддерживает расширение MCP (Model Context Protocol). Это позволяет подключить агента к внешней модели архитектуры.
1. Подготовка модели: В Viaduct создается модель, включающая схемы C4 (системы, контейнеры, компоненты), HTTP-контракты, схемы баз данных (ER-диаграммы) и последовательности PlantUML. 2. Подключение агента: Агенту предоставляется токен доступа, и он получает набор инструментов для чтения и написания в этой модели. Среди них инструменты для поиска по проекту, анализа элементов и документации потоков данных. 3. Процесс анализа: Агента просят просканировать все четыре репозитория проекта, выявить системы, эндпоинты, каналы брокера и связи между ними. Важно просить выделить скрытые связи отдельно.
Результатом работы становится не просто текст, а визуальная и структурная модель. Агента удается собрать данные о всех эндпоинтах, включая те, что скрыты в файлах db.py или db.js, описать потоки данных от загрузки медиа до готового клипа и составить карту всех таблиц базы данных.
Технические термины: * MCP (Model Context Protocol) — стандарт протокола, позволяющий ИИ-агентам обмениваться контекстом с внешними инструментами и базами знаний. * C4-модель — метод визуализации архитектуры программного обеспечения на разных уровнях детализации (от обзорной схемы системы до деталей компонентов). * Реверс-инжиниринг — процесс восстановления структуры или логики программы на основе исходного кода.
Практические результаты анализа
После того как агент задокументировал систему, на диаграммах стало очевидно, чего не видно в коде:
* Три стрелки в одну базу: Диаграмма четко показывает, что три сервиса (Java, Python, Node.js) напрямую подключены к Postgres, несмотря на наличие основного API-шлюза. * Нарушение архитектуры потока: Прямой HTTP-вызов, завершающий цепочку событий, выделен как аномалия, требующая переработки. * Безопасность: Эндпоинт без авторизации помечен как критический риск. * Мертвый код: Старый эндпоинт здоровья и жестко закодированные адреса в конфигурации фронта выявлены и помечены как подлежащие рефакторингу.
Такая карта системы становится invaluable для технических специалистов. Она позволяет: * Четко определять приоритеты рефакторинга: сначала убрать прямые подключения к базе, закрыть внутренние вебхуки, а затем переходить к другим улучшениям. * Давать контекст агентам: при задаче добавить новый функционал агент сначала видит, какой сервис отвечает за таблицу, и не создает дублирующую логику. * Ускорять онбординг: новые разработчики могут изучить систему, проигрывая потоки данных в визуальной модели, вместо того чтобы читать четыре разных репозитория.
Вывод: баланс скорости и качества
Эксперимент показывает, что в эпоху ускоренной разработки невозможно поддерживать архитектуру только в уме команды. «Вайбкодинг» — быстрый прототипирование на основе интуиции и готовых решений — необходим на старте, но он неизбежно создает скрытые технические долги.
Решение заключается не в отказе от скорости, а в автоматизации поддержания карты системы. Использование ИИ-агентов с подключенными инструментами анализа позволяет обновлять архитектуру в том же темпе, в котором пишется код. Это превращает хаотичный набор репозиториев в понятную, управляемую систему, где каждый элемент имеет свое место, а риски скрыты не за кодом, а открыты на диаграмме.
Экстраординарные времена требуют экстраординарных решений. Если мы генерируем код в десять раз быстрее, чем раньше, то и понимание этой системы должно происходить в том же ритме. Только так можно сохранить качество продукта, не уступая скорость.