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

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

Содержание¶

• Быстрый старт
• Как это работает
• Классификация интентов
• Двухфазная архитектура
• Три архитектурных агента
• Анализ зависимостей
• Циклические зависимости
• God-модули и нестабильные зависимости
• Быстрый путь для зависимостей
• Анализ слоёв
• Иерархия слоёв
• Нарушения слоёв
• Связность и сцепление
• Fan-In и Fan-Out
• Нарушения SRP
• Специализированный анализ
• Скрытые зависимости
• Кандидаты для выделения
• Влияние изменений и метрики стабильности
• Использование CLI
• Примеры вопросов
• Связанные сценарии

Быстрый старт¶

# Выберите сценарий архитектуры
/select 11

Как это работает¶

Классификация интентов¶

ArchitectureIntentDetector классифицирует запросы по одному из 17 интентов (+ запасной вариант), отсортированных по приоритету (меньше = специфичнее = проверяется первым). Каждый интент имеет ключевые слова на EN и RU с морфологическим матчингом, а также доменные ключевые слова из активного плагина.

Если ни один интент не совпал, используется запасной general_architecture (confidence=0.5).

Детектор также извлекает: - target_component — имя подсистемы/модуля из запроса - severity_filter — critical / high / medium / low / all (EN + RU морфологический матчинг)

Двухфазная архитектура¶

S11 использует двухфазный подход для оптимальной производительности:

Фаза 1: На основе хендлеров (без LLM). Функция integrate_handlers() пробует 17 зарегистрированных шаблонных хендлеров. Каждый хендлер формирует структурированные отчёты из данных CPG через ArchitectureReportFormatter. Если хендлер совпадает с обнаруженным интентом и находит результаты, ответ возвращается без вызова LLM.

Фаза 2: Запасной вариант LLM. Если ни один хендлер не совпал или хендлер нашёл 0 результатов, запускается полный конвейер: DependencyAnalyzer обнаруживает нарушения, LayerValidator проверяет правила слоёв, CallGraphAnalyzer анализирует пути зависимостей, ArchitectureReporter формирует приоритизированный отчёт — затем LLM обогащает ответ.

Query -> ArchitectureIntentDetector -> integrate_handlers()
  |                                          |
  |  Фаза 1: Хендлер совпал?       Да -> Структурированный отчёт (без LLM)
  |                                 Нет -> Фаза 2: Полный конвейер
  |
  Фаза 2: DependencyAnalyzer -> LayerValidator
           -> CallGraphAnalyzer -> ArchitectureReporter -> LLM

17 хендлеров зарегистрированы в HandlerRegistry("architecture"):

Три архитектурных агента¶

Конвейер LLM-фазы использует три специализированных агента из src/architecture/agents/:

DependencyAnalyzer(cpg_service) — Агент 1. Обнаруживает нарушения зависимостей с помощью архитектурных шаблонов и CallGraphAnalyzer: - Циклические зависимости между модулями - God-модули (чрезмерный fan-out) - Нестабильные зависимости (стабильные модули, зависящие от нестабильных) - Feature envy (методы, чрезмерно обращающиеся к данным других модулей) - Inappropriate intimacy (двунаправленная тесная связность) - Методы: detect_all_violations(limit_per_pattern), calculate_dependency_metrics(), identify_architectural_chokepoints()

LayerValidator(cpg_service, layer_hierarchy=None) — Агент 2. Валидация архитектурных слоёв: - Вызовы нижних слоёв к верхним (нарушение) - Межслойные зависимости (пропуск слоя — запах) - 4-уровневая иерархия по умолчанию: system(0), storage/data(1), business/logic(2), presentation/interface(3) - Методы: validate_all_layers(limit), get_layering_violations()

ArchitectureReporter() — Агент 3. Генерация отчётов: - Структурированные отчёты о нарушениях с разбивкой по серьёзности (critical/high/medium/low) - Разбивка по категориям (dependency/layering/coupling/cohesion) - Рекомендации по исправлению через RemediationAction - Методы: generate_report(findings, dependency_analysis, layer_metrics), create_remediation_plan(findings)

Ключевые модели данных (src/architecture/agents/models.py): - ViolationFinding — обнаруженное нарушение (severity, category, description, affected_files) - DependencyAnalysis / DependencyMetrics — результаты анализа и метрики - ArchitectureReport — полный отчёт с находками и исправлениями - RemediationAction — рекомендуемое исправление с приоритетом

Анализ зависимостей¶

Циклические зависимости¶

> Найти циклические зависимости в кодовой базе

╭─────────────── Циклы зависимостей ────────────────────────────╮
│                                                                │
│  Обнаружено циклов: 3                                          │
│                                                                │
│  Цикл 1 (critical):                                           │
│    executor -> planner -> executor                             │
│    Файлы: execMain.c, planmain.c                               │
│    Влияние: 12 транзитивных зависимых                          │
│                                                                │
│  Цикл 2 (high):                                               │
│    storage -> catalog -> storage                               │
│    Файлы: bufmgr.c, pg_class.c                                 │
│    Влияние: 8 транзитивных зависимых                           │
│                                                                │
│  Цикл 3 (medium):                                             │
│    utils -> parser -> utils                                    │
│    Файлы: stringinfo.c, scansup.c                              │
│    Влияние: 3 транзитивных зависимых                           │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

DependencyCycleHandler использует CallGraphAnalyzer для обхода графа вызовов и обнаружения циклов, затем ранжирует их по серьёзности на основе транзитивного влияния.

God-модули и нестабильные зависимости¶

DependencyAnalyzer обнаруживает дополнительные типы нарушений: - God-модули — модули с чрезмерным fan-out (слишком много зависимостей) - Нестабильные зависимости — когда стабильный модуль зависит от нестабильного (нарушение принципа стабильных зависимостей) - Feature envy — методы, чрезмерно обращающиеся к данным других модулей - Inappropriate intimacy — двунаправленная тесная связность между модулями

Быстрый путь для зависимостей¶

Для простых запросов о зависимостях («От чего зависит X?», «Кто включает X?») S11 использует быстрый путь, минуя полный конвейер агентов:

• detect_architecture_query_type() классифицирует запрос: who_imports_x, what_x_depends_on или external_deps
• Запрашивает таблицу nodes_import напрямую для связей #include / import
• Извлекает target_module из запроса с помощью регулярных выражений (EN + RU)
• Возвращает результаты без участия LLM

Анализ слоёв¶

Иерархия слоёв¶

LayerValidator применяет настраиваемую иерархию слоёв. Модель по умолчанию из 4 уровней:

Правила: Верхние слои могут зависеть от нижних. Нижние слои НЕ МОГУТ зависеть от верхних. Зависимости с пропуском слоя (например, presentation -> storage) отмечаются как запах.

Нарушения слоёв¶

> Найти нарушения архитектурных слоёв

╭─────────────── Нарушения слоёв ───────────────────────────────╮
│                                                                │
│  Обнаружено нарушений: 5                                       │
│                                                                │
│  1. storage -> presentation (critical)                         │
│     bufmgr.c вызывает format_output()                          │
│     Правило: Слой storage не может вызывать presentation       │
│                                                                │
│  2. data -> interface (high)                                   │
│     catalog.c ссылается на client_auth()                       │
│     Правило: Слой data не может ссылаться на interface          │
│                                                                │
│  Исправление:                                                  │
│    - Ввести абстрактный слой между нарушающими модулями        │
│    - Использовать инъекцию зависимостей для инверсии           │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

Связность и сцепление¶

Fan-In и Fan-Out¶

CouplingHandler анализирует связность модулей по метрикам fan-in/fan-out:

• Fan-out — количество модулей, от которых зависит данный модуль (высокий = потенциальный god-модуль)
• Fan-in — количество модулей, зависящих от данного модуля (высокий = критическая инфраструктура)
• Оценка связности — комбинированная метрика тесноты связей модуля

Нарушения SRP¶

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

Специализированный анализ¶

Скрытые зависимости¶

HiddenDepsHandler обнаруживает зависимости, невидимые через импорты: - Доступ к глобальным переменным из разных модулей - Неявные зависимости через разделяемое состояние - Побочные эффекты, создающие связность без явных импортов

Кандидаты для выделения¶

ExtractionCandidatesHandler определяет модули, подходящие для выделения в отдельные библиотеки: - Высокая связность (самодостаточность) - Низкое сцепление с остальной системой - Чёткие границы интерфейсов

Влияние изменений и метрики стабильности¶

Влияние изменений (ChangeImpactHandler): Анализирует радиус поражения при изменении конкретного модуля — сколько других модулей будет затронуто, используя анализ транзитивных зависимостей CallGraphAnalyzer.

Метрики стабильности (StabilityMetricsHandler): Рассчитывает метрики принципа стабильных зависимостей: - Нестабильность = fan-out / (fan-in + fan-out) - Стабильные модули (I близко к 0) не должны зависеть от нестабильных модулей (I близко к 1)

Использование CLI¶

# Найти циклические зависимости
python -m src.cli query "Find circular dependencies in the codebase"

# Анализ зависимостей модуля
python -m src.cli query "What does the executor module depend on?"

# Обнаружение нарушений слоёв
python -m src.cli query "Find architecture layer violations"

# Анализ связности
python -m src.cli query "Show coupling analysis with fan-in fan-out"

# Влияние изменений
python -m src.cli query "What is the impact of changing the buffer manager?"

# Полный архитектурный аудит (через audit composite)
python -m src.cli audit --db path/to/project.duckdb

Примеры вопросов¶

• «Найди циклические зависимости в кодовой базе»
• «От чего зависит модуль [module]?»
• «Покажи нарушения архитектурных слоёв»
• «Проанализируй связность и сцепление [подсистемы]»
• «Найди god-модули с чрезмерными зависимостями»
• «Каково влияние изменения [модуля]?»
• «Покажи метрики стабильности для всех модулей»
• «Найди скрытые зависимости через глобальные переменные»
• «Какие модули подходят для выделения в библиотеку?»
• «Обнаружь нарушения SRP»
• «Покажи общие зависимости между [модуль1] и [модуль2]»
• «Найди транзитивные зависимости от главной точки входа»

Связанные сценарии¶

• Ознакомление — Основы изучения кодовой базы
• Документация — Генерация архитектурной документации
• Межрепозиториевые изменения — Многорепозиториевая архитектура
• Разработка функционала — Поиск точек интеграции

S11 и аудит: S11 предоставляет интерактивный анализ архитектуры по запросу. Составной аудит использует S11 для 4 из 12 измерений качества: здоровье зависимостей, оценка модульности, соответствие архитектуре и анализ связности. S05 (рефакторинг) и S12 (технический долг) фокусируются на улучшении кода, тогда как S11 фокусируется на структурном анализе и обнаружении нарушений.