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

Сценарий помогает исследовать зависимости, циклы, нарушения слоёв, связанность и структурные риски внутри одного проекта. Он превращает вопрос для ревью в привязанный к исходникам dependency evidence. Архитектурное решение принимает ответственный рецензент.

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

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

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

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

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

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

Не переносите внутренние пороги реализации в архитектурное решение. Приоритеты handlers, лимиты запросов и эвристики могут меняться без изменения пользовательского контракта.

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

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

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

Профили возможностей для C, C++, JavaScript и TypeScript независимы. Поддержка или ограничение одного языка не распространяется автоматически на соседний.

Этот фундамент делает модель детерминированной и проверяемой. Применение правил, управление контрактами, release gates, контроль внедрения и готовые presets относятся к отдельным пользовательским историям. Само наличие архитектурной проекции не включает эти контроли в сценарии 11 автоматически.

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

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)

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

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

Сохраните:

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

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

Границы безопасности и полномочий

Сценарий 11 анализирует проект и выдаёт рекомендации. Он не является архитектурным одобрением: отдельное решение принимает отклонение, обновляет ADR, одобряет merge и подтверждает соответствие поведения системы целевой архитектуре.

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

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

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

Контракт с исходным кодом

Статья привязана к следующим источникам:

src/workflow/scenarios/architecture_core/architecture.py — workflow и evidence;
src/workflow/scenarios/architecture_handlers/workflow.py — специализированные handlers зависимостей;
src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py — типизированная маршрутизация;
src/digital_employees/runtime/scenarios/employee_scenario_invocation.py — владелец-рецензент и обязательное событие.
gocpg/pkg/architecture — классификация компонентов, типизированный граф зависимостей и профили возможностей языков;
gocpg/pkg/storage/duckdb/schema.go — хранилище архитектурной проекции в рамках запуска.