Проблема: документация архитектуры – это ад, который все ненавидят
Представьте: вы потратили три недели на проектирование новой микросервисной системы. Провели десять встреч, нарисовали двадцать схем в Draw.io, получили сто правок от security, compliance и тимлидов. И вот вы открываете Confluence – а там диаграмма, которая устарела ещё до того, как вы её загрузили.
Потому что разработка уже ушла вперёд, а обновлять картинки вручную – это как переписывать документацию от руки каждый раз, когда меняется строка кода.
На 08.03.2026 проблема не исчезла. Скорее, усугубилась: архитектуры стали сложнее, а циклы разработки – короче. Ручное документирование просто не успевает.
Решение: если код можно версионировать, то почему архитектуру – нет?
Architecture as Code (AaC) – это не модный термин. Это способ выжить. Суть проста: вы описываете компоненты, связи и контейнеры в виде кода (например, YAML или DSL). Этот код кладёте в Git. При изменениях – делаете коммит, запускаете CI/CD, который генерирует актуальные диаграммы и документацию.
Но есть загвоздка: написание этого кода вручную – та ещё рутина. Вот здесь на сцену выходят LLM.
Инструменты 2026 года: что реально работает
Не все инструменты пережили хайп 2024-2025. Вот что осталось в арсенале практиков:
- Structurizr версии 2.3 (релиз январь 2026). Главное изменение – нативная поддержка генерации диаграмм из LLM-описаний через GraphQL API. Раньше нужно было парсить JSON, теперь – просто отправить запрос.
- Claude Code (локальная версия Claude для разработчиков). Не путать с облачным Claude. Это инструмент, который работает с вашим кодом напрямую, без отправки данных в облако. Идеально для enterprise, где код за пределами firewall – это смертный грех. Подробно о настройке мы писали в гайде по Claude Code.
- GitHub Actions или GitLab CI – для автоматизации. Ничего нового, но без них никуда.
Важный нюанс: многие пытаются использовать общие LLM вроде GPT-5 для анализа кода. Но они часто галлюцинируют, особенно с корпоративными специфичными библиотеками. Claude Code, обученный на codebase, даёт более точные результаты. Если интересно, как заставить LLM не врать, посмотрите эту статью.
Пошаговый план: от хаоса к автоматизированному порядку
1 Готовим код и выбираем LLM
Сначала склонируйте репозиторий вашего проекта. Установите Claude Code (инструкция – в гайде для продакт-менеджеров, но для разработчиков всё то же самое).
Важно: не пытайтесь скормить LLM весь код разом. Разбейте его на логические модули. Claude Code умеет работать с контекстом до 200K токенов, но даже это не всегда достаточно для монолита.
# Устанавливаем Claude Code (версия 2026.03)
pip install claude-code --upgrade
# Инициализируем проект
claude-code init --project-type architecture-analyzer2 Пишем промпт для анализа архитектуры
Здесь многие ошибаются. Нельзя просто сказать "проанализируй код и напиши документацию". Нужно конкретное задание на выход в определённом формате.
Как НЕ надо делать: "Опиши архитектуру нашего приложения". LLM начнёт писать эссе, а не структурированные данные.
Вот промпт, который работает на 08.03.2026 с Claude 4.1:
Ты – архитектор предприятия. Проанализируй предоставленный код и создай описание архитектуры в формате Structurizr DSL (версия 2.3).
Строго придерживайся формата:
1. Определи систему (softwareSystem) – это наше основное приложение.
2. Выдели контейнеры (container) – веб-приложение, API, базы данных, очереди.
3. Внутри контейнеров перечисли компоненты (component).
4. Опиши связи между элементами: кто кого вызывает, протокол, данные.
Используй только факты из кода. Не придумывай.
Выведи результат в виде готового YAML-файла для Structurizr.Этот промпт использует технику structured prompting, о которой подробно в статье про Structured Outputs.
3 Запускаем анализ и получаем DSL
Запускаем Claude Code с промптом и указанием пути к коду:
claude-code analyze --prompt-file architecture.prompt --code-path ./src --output arch.dsl.ymlНа выходе получим YAML-файл примерно такого содержания:
workspace:
name: "E-Commerce Platform"
model:
softwareSystems:
- name: "E-Commerce System"
description: "Основная система онлайн-торговли"
containers:
- name: "Web Frontend"
type: "React Application"
components:
- name: "ProductCatalogUI"
description: "React-компонент для отображения каталога"
- name: "API Gateway"
type: "Spring Boot Application"
components:
- name: "AuthFilter"
description: "Фильтр аутентификации"
relationships:
- source: "Web Frontend"
destination: "API Gateway"
description: "Отправляет HTTP-запросы"
technology: "REST/JSON"4 Генерируем диаграммы через Structurizr
Устанавливаем Structurizr CLI (последняя версия – 2026.1):
# Скачиваем CLI (пример для Linux)
curl -O https://structurizr.com/download/structurizr-cli-2026.1.zip
unzip structurizr-cli-2026.1.zip
# Генерируем диаграммы
java -jar structurizr-cli-2026.1.jar generate -i arch.dsl.yml -o ./diagrams -f plantumlТеперь у вас есть PNG-файлы со всеми диаграммами. Но это только начало.
5 Интегрируем в CI/CD и Confluence
Пишем GitHub Actions workflow, который при каждом коммите в main:
- Запускает Claude Code для анализа изменённого кода.
- Генерирует обновлённый DSL.
- Создаёт новые диаграммы.
- Загружает их в Confluence через REST API (или любой другой wiki).
Весь процесс занимает 10-15 минут вместо двух недель ручного обновления.
Ошибки, которые убьют ваш проект Architecture as Code
| Ошибка | Почему это плохо | Как исправить |
|---|---|---|
| Доверять LLM на 100% без проверки | Claude может пропустить важную зависимость или придумать несуществующий компонент. Особенно с устаревшими или кастомными фреймворками. | Внедрите этап ревью. Используйте LLM для код-ревью самого DSL. Или проверяйте ключевые связи вручную. |
| Хранить сгенерированные диаграммы в Git | Зачем хранить бинарные PNG, если у вас есть код, который их генерирует? Это дублирование. | Генерируйте диаграммы на лету в CI/CD. Храните только DSL-файлы. В Confluence загружайте через API. |
| Игнорировать эволюцию архитектуры | Architecture as Code – не разовая акция. Если вы не обновляете DSL при изменении кода, вся затея бессмысленна. | Настройте хуки в Git, которые запускают анализ при каждом пуше. Сделайте это обязательным шагом в pipeline. |
FAQ: вопросы, которые вы хотели задать, но боялись
Что делать, если LLM не понимает наш корпоративный фреймворк?
Добавьте контекст. Создайте файл с документацией по фреймворку и передайте его Claude Code вместе с кодом. Или используйте техники из статьи про контекстуализацию LLM. В крайнем случае – дообучите модель на своих данных, но это дорого.
PlantUML или Mermaid? Что лучше для диаграмм?
На 08.03.2026 PlantUML всё ещё жив и хорошо поддерживается Structurizr. Mermaid набирает популярность, но у него меньше возможностей для сложных enterprise-диаграмм. Совет: используйте то, что уже работает в вашей компании. Главное – автоматизация.
Как убедить руководство внедрить Architecture as Code?
Цифры. Измерьте, сколько часов тратят архитекторы и разработчики на обновление документации. Посчитайте стоимость этих часов. Покажите, что с автоматизацией цикл согласования сокращается с 3 недель до 2 дней. Руководство понимает язык денег.
Что будет дальше? Прогноз на 2027
Architecture as Code станет таким же обязательным, как Infrastructure as Code. Появятся специализированные LLM, обученные только на анализе архитектуры (возможно, на основе архитектур типа LoopCoder).
Но главное изменение: документация перестанет быть отдельным артефактом. Она будет живым слоем, который генерируется из кода и изменяется вместе с ним. И те, кто не автоматизируют этот процесс, просто не выживут в гонке за скорость.
Начните сегодня. С одного сервиса. С одной диаграммы. Потом масштабируйтесь. И помните: лучшая документация – та, которую не нужно писать вручную.
