Публикация AiManual

Автоматическая генерация архитектурной документации и диаграмм из .NET-кода с помощью Amazon Bedrock AgentCore и AWS CodePipeline

Практическое руководство по настройке пайплайна AWS для автоматической генерации архитектурных диаграмм и документации из .NET-кода. Разбираем связку Amazon Bed

13 мин чтения 02.09.2026

Коротко

Что будет в материале

01
Зачем автоматизировать архитектурную документацию?
02
Обзор архитектуры решения: как это работает
03
Пошаговая настройка пайплайна генерации документации
04
Как агент валидирует и исправляет диаграммы

Да, генерацию архитектурной документации можно встроить в CI/CD. Практичная схема выглядит так: AWS CodePipeline запускает анализ после изменения репозитория, инструменты извлекают структуру .NET-кода, Amazon Bedrock AgentCore управляет многошаговой работой агента, а готовые диаграммы и текстовые описания публикуются в Amazon S3.

Агент в этой схеме получает модель кода, вызывает инструменты анализа и рендеринга, проверяет результат, исправляет найденные ошибки и сохраняет артефакты вместе с хешем коммита. Amazon Bedrock Knowledge Bases превращает подготовленные описания, исходники диаграмм и метаданные в поисковую базу, где можно задавать вопросы вроде «какие сервисы используют PostgreSQL» или «какие компоненты зависят от очереди сообщений».

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

Зачем автоматизировать архитектурную документацию?

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

Ручное обновление откладывают до конца задачи, когда контекст уже потерян.
Диаграмма часто показывает логическую структуру, но не отражает реальные связи между проектами, очередями, базами данных и внешними API.
Новый инженер тратит время на сопоставление документации с исходным кодом.
Архитектурные решения сложно проверить после нескольких месяцев изменений.
Документы из разных команд используют разные уровни детализации и названия компонентов.

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

Проблема	Действие пайплайна	Результат
Изменился публичный интерфейс	Повторный анализ проекта и зависимостей	В документации появляется новая связь или endpoint
Диаграмма содержит ошибочную связь	Проверка графа и повторная генерация	Агент получает сообщение об ошибке и исправляет артефакт
Нужно найти компонент по смыслу	Индексация текста и метаданных в Knowledge Bases	Поиск возвращает связанные диаграммы и описания
Нужно сравнить архитектуру	Хранение артефактов по хешу коммита	Можно сопоставить две версии документации

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

Обзор архитектуры решения: как это работает

Минимальная архитектура состоит из источника кода, этапа сборки, анализатора .NET, агентного runtime, хранилища артефактов и поискового слоя.

Изменение в репозитории
        |
        v
AWS CodePipeline
        |
        v
Сборка и экспорт модели .NET-кода
        |
        v
Агент в Amazon Bedrock AgentCore
  |       |          |
  v       v          v
анализ  генерация  валидация
        диаграмм    и исправление
        |
        v
Amazon S3: SVG, Mermaid, Markdown, JSON metadata
        |
        v
Amazon Bedrock Knowledge Bases
        |
        v
Семантический поиск по архитектуре

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

Роль Amazon Bedrock AgentCore в агентном сценарии

В этой архитектуре AgentCore используется как среда для агентного цикла. Агент планирует последовательность действий, вызывает инструменты, получает их результаты и принимает решение о следующем шаге.

Полезный набор инструментов может выглядеть так:

scan_repository извлекает проекты, пространства имён, классы и точки входа;
build_dependency_graph собирает связи между проектами и внешними компонентами;
inspect_di_registration анализирует регистрацию зависимостей в контейнере .NET;
render_diagram создаёт SVG и исходник в Mermaid или PlantUML;
validate_diagram проверяет синтаксис и соответствие графа модели кода;
write_artifact сохраняет результат и метаданные в рабочий каталог.

Это логические контракты инструментов. Их можно связать с контейнером, Lambda-функцией или утилитой в build-среде. Не следует рассчитывать, что конкретный runtime автоматически знает, как анализировать .NET Solution или рисовать архитектурные графы.

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

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

Интеграция с AWS CodePipeline

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

Стадия	Что происходит	Основной артефакт
Source	Пайплайн получает новую ревизию из CodeCommit или подключённого GitHub-репозитория	Исходный код и идентификатор коммита
Build	Проект собирается, тестируется, экспортируется модель кода и запускается агент	Модель зависимостей и папка документации
Deploy	Проверенные файлы загружаются в S3 и передаются на синхронизацию с Knowledge Bases	Версионированные диаграммы, Markdown и metadata

Триггером может служить push в основную ветку, изменение каталога конкретного сервиса или ручной запуск после крупного рефакторинга. Для pull request лучше использовать отдельный режим: агент создаёт preview-документацию и показывает diff, а публикация канонической версии происходит после слияния.

Хранение и поиск: Amazon Bedrock Knowledge Bases

Amazon S3 хранит исходную версию артефактов, а Knowledge Bases добавляет слой семантического поиска. В базу передают текстовые описания диаграмм, исходники графов и метаданные. Из этих материалов создаются поисковые представления, по которым система сопоставляет запрос с архитектурным контекстом.

Изображение SVG или PNG само по себе не всегда подходит для текстового поиска. Поэтому рядом с каждой диаграммой стоит хранить Markdown или JSON с узлами, связями, назначением компонентов, путями к исходникам и хешем коммита. Изображение остаётся удобным форматом для человека, а текстовая модель становится основой поиска.

Архитектуру Managed Knowledge Base, варианты загрузки из S3 и способы подключения к агентному поиску можно сопоставить с практическим разбором Amazon Bedrock Managed Knowledge Base.

Пошаговая настройка пайплайна генерации документации

Подготовка .NET-кодовой базы

Сначала нужно определить границы анализа. Агенту не требуется получать весь репозиторий в одном запросе. Лучше создать компактную модель, которую можно пересобирать на каждом коммите.

repository/
  src/
    Orders.Api/
    Orders.Application/
    Orders.Infrastructure/
  tests/
  architecture/
    prompts/
    schemas/
  tools/
    export_code_model.py
    run_agent.py
    validate_graph.py

Для извлечения структуры .NET-кода подойдёт анализатор на базе Roslyn. Он может собрать:

список проектов и их ссылки в Solution;
пространства имён, классы, интерфейсы и публичные методы;
вызовы между проектами и ключевыми слоями;
регистрацию зависимостей через IServiceCollection;
контроллеры, minimal API, обработчики команд и событий;
клиенты баз данных, очередей, HTTP API и файловых хранилищ;
атрибуты, конфигурационные ключи и сгенерированные исходники, если они участвуют в сборке.

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

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

Создание агента в Amazon Bedrock AgentCore

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

Ты анализируешь модель .NET-кода, а не делаешь предположения о системе.
1. Найди компоненты и связи в переданном JSON.
2. Для каждого существенного утверждения укажи source_paths.
3. Создай граф в согласованной схеме.
4. Передай граф в render_diagram и validate_diagram.
5. При ошибке используй сообщение валидатора и исправь исходные данные или граф.
6. Повтори проверку не более 3 раз.
7. Сохрани Markdown, исходник диаграммы, SVG и metadata.
8. Если доказательств недостаточно, пометь связь как unknown.

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

Выход агента стоит ограничить схемой. Например, объект результата может содержать поля diagram_type, nodes, edges, source_paths, validation, commit и warnings. Схема упрощает автоматическую проверку и снижает риск публикации свободного текста вместо артефакта.

Настройка AWS CodePipeline

На build-этапе выполняются обычная сборка .NET, экспорт модели и обёртка, которая вызывает настроенный агентный runtime. Команда запуска агента ниже условная: это скрипт проекта, а не универсальная команда AWS.

version: 0.2
phases:
  build:
    commands:
      - dotnet restore
      - dotnet build --no-restore
      - dotnet test --no-build
      - python tools/export_code_model.py --output build/code-model.json
      - python tools/run_agent.py --commit ${CODEBUILD_RESOLVED_SOURCE_VERSION} --input build/code-model.json --output build/docs
      - python tools/validate_graph.py --input build/docs --fail-on-critical
artifacts:
  files:
    - '**/*'
  base-directory: build/docs

Переменные окружения могут хранить имя проекта, путь к модели, типы диаграмм и режим публикации. Секреты нельзя передавать в промпте или записывать в артефакты. Для доступа к репозиторию, S3 и агентному runtime используют отдельные IAM-роли с минимальным набором действий.

Сборка должна завершаться ошибкой, если отсутствует обязательный артефакт, не проходит синтаксическая проверка или результат не содержит хеш коммита. Такой gate защищает S3 от публикации неполной документации.

Публикация в S3 и настройка Knowledge Bases

В S3 удобно разделить артефакты по проекту, типу диаграммы и ревизии:

docs-bucket/
  orders/
    commits/7f3a1c2/manifest.json
    diagrams/7f3a1c2/context.svg
    diagrams/7f3a1c2/context.mmd
    text/7f3a1c2/context.md
    metadata/7f3a1c2/context.json
  latest/

Каталог latest удобен для сайта или внутреннего портала, но канонической версией лучше считать путь с хешем коммита. При таком подходе можно восстановить состояние документации на любой сохранённой ревизии.

Пример metadata:

{
  "project": "Orders",
  "commit": "7f3a1c2",
  "diagram_type": "container",
  "components": ["Orders.Api", "Orders.Application", "PostgreSQL"],
  "source_paths": ["src/Orders.Api", "src/Orders.Infrastructure"],
  "generated_at": "2026-09-02T12:00:00Z",
  "validation_status": "passed",
  "warnings": []
}

В Knowledge Bases передают Markdown с описанием диаграммы и JSON с метаданными. После загрузки запускают синхронизацию источника и проверяют несколько запросов вручную. Если в вашей конфигурации база подключена к агенту, нужно отдельно проверить маршрутизацию запроса и фильтрацию по проекту или версии.

Как агент валидирует и исправляет диаграммы

Инструменты валидации

Генерация без проверки даёт красивый, но потенциально ложный результат. Надёжнее разделить контроль на несколько уровней.

Проверка модели кода. Сборка и Roslyn-экспорт подтверждают, что исходные данные относятся к конкретной версии проекта.
Проверка схемы. У каждого узла должен быть идентификатор и тип, у каждой связи, источник и назначение.
Проверка графа. Связь не может указывать на отсутствующий компонент. Дубликаты узлов и циклы проверяются по правилам конкретной диаграммы.
Проверка рендера. Mermaid, PlantUML или другой генератор должны собрать исходник без синтаксической ошибки.
Проверка политики. Из результата удаляются секреты, токены, внутренние адреса и поля, которые нельзя публиковать.

Валидатор может сообщить, что узел Payments.Api указан на диаграмме, но отсутствует в модели коммита. Другой пример, связь Orders.Application -> RabbitMQ заявлена агентом, хотя анализатор нашёл только зависимость на абстракцию без фактической регистрации клиента. Такие случаи нужно помечать отдельно, а не превращать в утверждение.

Обработка ошибок и повторные итерации

Самокоррекция должна получать структурированный отчёт об ошибке. Формулировка «диаграмма неправильная» мало помогает. Полезнее передать код ошибки, узел, связь и ожидаемое условие.

attempt = 0
result = generate(model)

while attempt < 3 and result.validation.has_critical_errors:
    feedback = result.validation.errors
    result = repair(model, result.graph, feedback)
    result.validation = validate(result.graph, model)
    attempt += 1

if result.validation.has_critical_errors:
    fail_pipeline(result.validation.errors)
else:
    publish(result.artifacts)

Лимит в 2-3 итерации помогает остановить бесконечный цикл и контролировать расходы. Если ошибка повторяется, пайплайн должен завершаться с понятным отчётом. Ручная проверка нужна для спорных связей, неоднозначных границ сервисов и решений, которые нельзя вывести из исходников.

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

Семантический поиск по документации с Amazon Bedrock Knowledge Bases

Индексация диаграмм и метаданных

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

Файл	Назначение	Что ищет система
`context.md`	Человеческое описание архитектуры	Назначение сервисов и потоков данных
`context.mmd`	Исходник графа	Названия узлов и направленные связи
`context.json`	Структурированные метаданные	Фильтры по проекту, версии и типу диаграммы
`context.svg`	Визуальный просмотр	Результат для человека, а не единственный источник поиска

В Markdown можно включить короткую карточку:

# Orders: контейнерная диаграмма

Компонент Orders.Api принимает HTTP-запросы и передаёт команды в Orders.Application.
Orders.Application обращается к PostgreSQL через инфраструктурный слой.
Обнаруженные исходные пути: src/Orders.Api, src/Orders.Application, src/Orders.Infrastructure.
Коммит: 7f3a1c2.
Статус проверки: passed.

Такой формат помогает связать естественный язык с конкретными элементами графа. Если нужен поиск по самому внешнему виду изображения, потребуется отдельный этап, который создаёт подпись или структурное описание изображения. Одной загрузки PNG в S3 недостаточно, чтобы получить полноценный поиск по визуальным связям.

Примеры поисковых запросов

Запрос	Какие поля нужны	Ожидаемый результат
Какие сервисы используют PostgreSQL?	Компоненты, тип ресурса, связи	Список сервисов и исходные пути
Какие компоненты зависят от RabbitMQ?	Очереди, publishers, consumers	Связанные сервисы и направления обмена
Где обрабатывается команда CreateOrder?	Методы, handlers, маршруты	Проект, класс, endpoint и связанные компоненты
Что изменилось в архитектуре Orders после коммита?	Хеши версий и manifest	Разница между двумя наборами артефактов

Семантический поиск находит близкие по смыслу описания, но точные фильтры лучше оставлять за metadata. Запрос по проекту, ветке, окружению или версии нельзя полагать только на близость эмбеддингов.

Если нужно маршрутизировать запросы между документацией нескольких продуктов, пригодится отдельный слой agentic retrieval. Подход с несколькими базами, фильтрами, цитированием и наблюдаемостью разобран в статье про агентный поиск в Amazon Bedrock Managed Knowledge Base.

Ограничения и подводные камни

Точность и надежность генерации

Модель видит переданный контекст, а не всю реальность системы. В .NET-проектах архитектура может зависеть от reflection, генераторов кода, конфигурации окружения, динамической регистрации зависимостей, внешней инфраструктуры и ручных операций.

Типичные ошибки:

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

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

Стоимость и ресурсы

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

Снизить расходы помогают конкретные правила:

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

Сложность внедрения и поддержки

Пайплайн требует компетенций в .NET, AWS, IAM, CI/CD и обработке результатов LLM. Поддерживать придётся несколько контрактов: схему модели кода, формат диаграмм, инструкции агента, валидаторы и структуру metadata.

Изменение формата JSON может сломать инструмент генерации. Перенос проекта в другой репозиторий может сделать старые пути бесполезными. Обновление промпта способно изменить вид диаграммы без изменения исходников. Поэтому версии схем, промптов и валидаторов нужно хранить рядом с кодом.

Риск	Защита
В S3 попала непроверенная диаграмма	Отдельная проверка и запрет публикации при critical errors
Агент получил лишние права	Раздельные IAM-роли для чтения, генерации и публикации
Поиск возвращает старую версию	Фильтр по commit и явное поле актуальности
Секрет оказался в Markdown	Сканирование артефактов перед загрузкой в S3
Цикл исправлений расходует бюджет	Лимит итераций, таймаут и завершение с отчётом

Альтернативные подходы к генерации документации

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

Подход	Сильные стороны	Ограничения
Ручные документы и ADR	Хорошо передают решения, причины и компромиссы	Быстро устаревают без процесса обновления
Roslyn и статические анализаторы	Детерминированно извлекают структуру кода	Плохо описывают смысл связи и архитектурные компромиссы
Шаблоны Mermaid или PlantUML	Простое хранение в Git и понятный diff	Требуют отдельного источника фактов
AI-генерация без валидатора	Быстро создаёт черновик описания	Риск правдоподобных, но неверных связей
AgentCore с инструментами и проверками	Объединяет анализ, генерацию, исправление и публикацию	Требует AWS-инфраструктуры, контроля прав и поддержки схем

На практике разумен гибрид: Roslyn формирует фактическую модель, шаблоны задают формат графа, агент пишет пояснения и обрабатывает неоднозначные случаи, а валидатор блокирует критичные ошибки. Похожий принцип автоматической подготовки документации для интеграционных workflow разобран в материале про AI-агента для документации интеграций.

Заключение: стоит ли внедрять?

Связка AWS CodePipeline, Amazon Bedrock AgentCore, S3 и Knowledge Bases подходит для .NET-систем, где код меняется регулярно, архитектура состоит из нескольких сервисов, а поиск по документации занимает заметное время. Главная польза появляется не на этапе красивого рендера, а при связывании каждого утверждения с моделью кода и конкретным коммитом.

Начинайте с одного сервиса и двух типов диаграмм, например контекстной и контейнерной. Зафиксируйте схему JSON, добавьте Roslyn-экспорт, настройте проверку графа и публикуйте preview после pull request. После нескольких стабильных запусков подключайте S3-версии и семантический поиск.

Сборка должна падать при критичных ошибках валидации.
Каждый артефакт должен содержать хеш исходного коммита.
Не подтверждённые связи нужно маркировать как unknown.
Изображение диаграммы следует хранить вместе с текстовым описанием и metadata.
Для production-документации нужен ручной gate хотя бы на первом этапе.

Если команда готова поддерживать анализатор, валидаторы и AWS-права, генерация документации становится повторяемой частью CI/CD. Если таких ресурсов нет, начните со статической модели и шаблонов, а AgentCore подключайте после проверки качества исходных данных.

Подписаться на канал