Сценарий 11: анализ архитектуры

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

Когда применять

Хороший вопрос называет ограниченный компонент и решение:

какие модули зависят от платёжного адаптера;
создаёт ли изменение новый цикл зависимостей;
какие нарушения слоёв относятся к предлагаемой границе;
каков радиус влияния при выделении компонента.

Для нескольких репозиториев используйте сценарий 10, для ревью конкретной ревизии — сценарий 09.

Предварительные условия и область

Откройте принятую задачу на ревью, привяжите её к ревизии проекта и ограничьте file_paths проверяемым компонентом. CPG должен соответствовать этой ревизии. Устаревший CPG сначала обновите. Порядок подготовки проекта и проверки графа описан в руководстве по CPG-аудиту.

Подготовьте окружение Python и конфигурацию по руководству CLI и программному интерфейсу. Проверьте доступность нужных сервисов графа. Настройте LLM для ветвей workflow, которые её используют. При запуске CodeGraph проверяет роль рецензента, задачу и готовность сценария.

Архитектурная проекция в CPG

Модель архитектуры объединяет файлы и символы CPG в компоненты: например, веб-слой, сервисы и хранилище. Она задаёт вложенность компонентов и связывает их зависимости с проверяемой ревизией. Стабильный идентификатор компонента позволяет сопоставлять результаты после изменения его названия.

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

Например, при полном покрытии каждый объект проверяемой области должен получить компонент; если код в src/payments/** не подходит ни под одно правило выбора компонента, отчёт покажет этот пробел.

При построении графа зависимостей каждый участвующий объект должен принадлежать одному компоненту.

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

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

Для C, C++, JavaScript и TypeScript профиль языка определяет доступные виды связей. Проверка правила сопоставляет необходимые связи с этим профилем; например, правило запрета импортов использует сведения об импортах и принадлежности файлов компонентам.

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

Запуск типизированного сценария

Сохраните пример в файл Python в рабочей копии CodeGraph. Активируйте окружение с установленными зависимостями и запускайте файл из корня репозитория. Замените проект, namespace, задачу, ссылки на свидетельства и пути на принятую область. Уточните вопрос для проверяемого компонента.

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Найди циклы зависимостей и нарушения слоёв вокруг платёжного адаптера.",
    employee_id="codegraph_reviewer",
    scenario_id="scenario_11",
    event_type="review_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<revision-ref>", "<architecture-rule-ref>"],
        "file_paths": ["<bounded-source-path>"],
    },
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
    raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])

Один запуск должен отвечать на один вопрос. Узкий запрос проще воспроизвести и проверить, чем просьбу «проанализировать всю архитектуру».

Как читать результат

Сохраните:

answer — сводное объяснение;
evidence и cpg_results — сведения о зависимостях и подтверждающие места;
metadata.role_bound_scenario_invocation — рецензента, событие, workflow и статус preflight;
ревизию и архитектурное правило из задачи.

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

Например, вы выделяете платёжный адаптер и хотите сохранить границу между веб-слоем и хранилищем. Задайте вопрос о вызовах из веб-слоя, затем сопоставьте найденные пути с разрешённой цепочкой «веб-слой → сервис → хранилище». Прямой вызов хранилища из веб-слоя станет предметом ревью: перенести вызов в сервис или оформить обоснованное отклонение в ADR. Это пример постановки вопроса; конкретные пути даёт анализ вашего проекта.

В metadata.architecture_adoption поле source указывает источник результата, canonical — использование канонического запуска, а gate_eligible — пригодность для проверки выпуска.

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

Сопоставьте project_key и commit_hash с проверяемым проектом и ревизией, а model_hash и rules_hash — с выбранной моделью и правилами.

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

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

Как оформить архитектурное решение

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

В ADR зафиксируйте решение, рассмотренные альтернативы, принятые риски, владельцев, тесты и условия отката. После реализации проверьте изменённую ревизию и сопоставьте результат с выбранными границами компонентов.

Архитектурные изменения оформляйте по процессу поставки проекта; этот сценарий даёт свидетельства для их ревью.

Ошибки и восстановление

Пустой результат: проверьте имя компонента, ревизию, свежесть CPG и охват правил.
Резервный handler: пометьте ответ как гипотезу и сохраните сигнал ошибки или fallback.
Запуски противоречат друг другу: сначала сравните ревизию, область и правила.
Подозревается зависимость только времени выполнения: дополните статический анализ runtime- или deployment-свидетельством.