Сценарий 12: Технический долг

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

Содержание

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

# Выберите сценарий технического долга
/select 12

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

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

При получении запроса о техническом долге IntentDetector классифицирует его в один из четырёх типов по ключевым словам (поддержка английского и русского):

Интент Ключевые слова (EN) Ключевые слова (RU) Обработчик
debt_metrics debt score, calculate debt, debt summary показатель долга, рассчитать долг DebtScanHandler
quick_wins quick wins, easy fixes, low-hanging быстрые победы, лёгкие исправления QuickWinsHandler
prioritization prioritize, rank debt, impact vs effort приоритизация, ранжирование долга Полный конвейер
repayment_plan repayment plan, sprint plan, pay off debt план погашения, спринт-план Полный конвейер

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

Сценарий технического долга использует двухфазный конвейер обработки:

Запрос пользователя
    |
    v
[Фаза 1] На основе обработчиков (шаблонные ответы, без LLM)
    |-- IntentDetector        → классификация интента запроса
    |-- DebtScanHandler       → структурированный отчёт по метрикам
    |-- QuickWinsHandler      → структурированный отчёт по быстрым победам
    |
    v (если обработчик не может ответить)
[Фаза 2] Полный конвейер с LLM
    |-- DebtCalculator.detect_all_debt()
    |-- PrioritizationEngine.prioritize_debt()
    |-- RepaymentPlanner.create_plan()
    |-- LLM генерирует ответ на естественном языке

Фаза 1 (на основе обработчиков) предоставляет мгновенные структурированные ответы для интентов debt_metrics и quick_wins — без вызова LLM. Фаза 2 (резервная с LLM) обрабатывает интенты prioritization и repayment_plan, требующие синтеза данных от всех трёх агентов.

Три агента

Сценарий работает на трёх специализированных агентах из src/tech_debt/debt_agents.py:

Агент Назначение Ключевые методы
DebtCalculator Обнаружение элементов долга по 6 паттернам, расчёт метрик detect_all_debt(), calculate_metrics()
PrioritizationEngine Ранжирование долга по ROI, определение быстрых побед и стратегических элементов prioritize_debt(), get_quick_wins(), get_strategic_items()
RepaymentPlanner Генерация планов погашения по спринтам create_plan(velocity, max_sprints)

Обнаружение долга

6 паттернов долга

DebtCalculator выявляет технический долг по 6 специализированным паттернам, каждый с SQL-запросами, порогами и весами:

Паттерн Категория Описание
TODO_COMMENTS maintenance Комментарии TODO/FIXME/HACK/XXX в коде
DEPRECATED_API maintenance Использование устаревших API и функций
CODE_DUPLICATION code_quality Дублированные блоки кода, обнаруженные через AST
LONG_METHODS complexity Функции длиннее 50 строк
COMPLEX_METHODS complexity Функции с цикломатической сложностью > 10
DEAD_CODE unused_code Функции и переменные без ссылок

Каждый паттерн выполняет CPG-запрос к базе данных DuckDB и создаёт экземпляры DebtItem с серьёзностью, оценкой трудозатрат и рекомендациями по исправлению.

4 категории долга

Элементы долга классифицируются по четырём категориям:

Категория Паттерны Фокус
code_quality CODE_DUPLICATION Поддерживаемость и читаемость
maintenance TODO_COMMENTS, DEPRECATED_API Отложенная работа и устаревшие шаблоны
complexity LONG_METHODS, COMPLEX_METHODS Структурная сложность
unused_code DEAD_CODE Мёртвый груз в кодовой базе

Модель данных DebtItem

Каждый обнаруженный элемент долга представлен как DebtItem с 12 полями:

Поле Тип Описание
name str Имя функции или символа
file_path str Путь к исходному файлу
line_number int Номер строки в файле
pattern_type str Какой паттерн обнаружил
severity str critical / high / medium / low
effort_hours float Оценка трудозатрат в часах
description str Описание на естественном языке
category str Категория долга
confidence float Достоверность обнаружения (0.0–1.0)
impact_score float Влияние на кодовую базу (0.0–10.0)
fix_suggestion str Рекомендуемое исправление
metadata dict Дополнительные данные паттерна

Примеры сканирования

> Рассчитать показатель технического долга

╭─────────────── Сводка по техническому долгу ────────────────╮
│                                                              │
│  Общий показатель технического долга: 34/100 (умеренный)     │
│                                                              │
│  Распределение по категориям:                                │
│                                                              │
│  Сложность:      42%  ████████░░  (LONG_METHODS, COMPLEX)   │
│    - 23 функции превышают порог сложности                    │
│    - 5 функций длиннее 300 строк                             │
│                                                              │
│  Обслуживание:   28%  █████░░░░░  (TODO, DEPRECATED_API)    │
│    - 156 комментариев TODO/FIXME/HACK                        │
│    - 12 использований устаревших API                         │
│                                                              │
│  Качество кода:  18%  ████░░░░░░  (CODE_DUPLICATION)        │
│    - 15 кластеров клонов, ~450 дублированных строк           │
│                                                              │
│  Неисп. код:     12%  ██░░░░░░░░  (DEAD_CODE)               │
│    - 34 функции без ссылок                                   │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

Метрики долга

Поля DebtMetrics

DebtCalculator.calculate_metrics() вычисляет количественные метрики из всех обнаруженных экземпляров DebtItem:

Поле Тип Описание
total_items int Общее количество обнаруженных элементов долга
total_effort_hours float Общие трудозатраты на исправление всего долга
debt_ratio float Отношение технического долга к общим трудозатратам кодовой базы
by_severity dict Распределение: critical / high / medium / low
by_category dict Распределение по 4 категориям
by_pattern dict Распределение по 6 паттернам
average_confidence float Средняя достоверность по всем элементам
estimated_cost float Оценка стоимости на основе трудозатрат × почасовая ставка

Пример метрик

> Показать метрики долга

  Всего элементов:    234
  Общие трудозатраты:  180 часов
  Коэффициент долга:  0.12 (12% трудозатрат кодовой базы)
  Оценка стоимости:   $18,000

  По серьёзности:
    critical:  12   high:  45   medium:  98   low:  79

  По категориям:
    complexity:    89   maintenance:  67
    code_quality:  44   unused_code:  34

Приоритизация

Оценка ROI

PrioritizationEngine.prioritize_debt() ранжирует каждый DebtItem по возврату на вложения:

ROI score = impact_score / effort_hours

Более высокий ROI означает больший эффект при меньших трудозатратах — эти элементы следует исправлять первыми.

Каждый результат PrioritizedDebt содержит:

Поле Тип Описание
item DebtItem Исходный элемент долга
priority_score float Составной приоритет (0.0–10.0)
roi_score float Соотношение влияния к трудозатратам
quick_win bool True, если соответствует критериям быстрой победы
strategic bool True, если соответствует критериям стратегического элемента
dependencies int Количество зависимых элементов
rationale str Обоснование присвоенного приоритета

Быстрые победы

PrioritizationEngine.get_quick_wins() определяет элементы, которые быстро исправить и надёжно обнаружить:

Критерии быстрой победы:
  effort_hours ≤ 2  AND  confidence ≥ 0.7

Быстрые победы идеальны для заполнения спринтов или задач онбординга — высокая достоверность означает низкий риск ложных срабатываний.

Стратегические элементы

PrioritizationEngine.get_strategic_items() определяет элементы с большим архитектурным влиянием:

Критерии стратегического элемента:
  impact_score ≥ 8  OR  dependencies ≥ 3

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

Пример приоритизации

> Приоритизировать элементы долга

  Приоритизированный долг (по ROI):
    1. [БЫСТРАЯ ПОБЕДА] Удалить мёртвую функцию old_format_help()
       ROI: 9.2  Трудозатраты: 0.5ч  Влияние: 4.6  Достоверность: 0.95

    2. [БЫСТРАЯ ПОБЕДА] Удалить блок TODO в pg_type.c:234
       ROI: 7.0  Трудозатраты: 1.0ч  Влияние: 7.0  Достоверность: 0.85

    3. [СТРАТЕГИЧЕСКИЙ] Разделить exec_simple_query() — сложность 47
       ROI: 3.1  Трудозатраты: 8.0ч  Влияние: 24.5  Зависимости: 5

    4. [СТРАТЕГИЧЕСКИЙ] Устранить дублирование процедур сканирования — 3 файла
       ROI: 2.8  Трудозатраты: 6.0ч  Влияние: 16.8  Зависимости: 3

  Быстрые победы: 45 элементов (всего ~30ч)
  Стратегические элементы: 12 элементов (всего ~96ч)

Планирование погашения

Планирование по спринтам

RepaymentPlanner.create_plan() распределяет приоритизированные элементы долга по спринтам:

  • team_velocity = 40 часов/спринт (настраиваемо)
  • max_sprints = 6 (настраиваемо)
  • Элементы назначаются на спринты в порядке приоритета до исчерпания ёмкости
  • Каждый спринт включает оценку рисков и рекомендации

Модель данных RepaymentPlan

Поле Тип Описание
sprints list Распределение элементов по спринтам с итогами трудозатрат
total_sprints int Количество спринтов в плане
total_effort float Общие часы по всем спринтам
items_addressed int Элементы, вошедшие в max_sprints
items_remaining int Элементы, не вошедшие в план
velocity float Часов на спринт
completion_percentage float % адресованного общего долга
risk_assessment str Общая оценка рисков
recommendations list Практические рекомендации
metadata dict Дополнительные данные планирования

Пример плана погашения

> Составить план погашения технического долга

╭─────────────── План погашения ────────────────────────────╮
│                                                            │
│  Скорость: 40 часов/спринт                                 │
│  Спринты: 4 из 6 максимум                                  │
│  Завершение: 78% общего долга адресовано                    │
│                                                            │
│  Спринт 1 (38ч):                                           │
│    - 12 быстрых побед (очистка TODO, удаление мёртвого кода)│
│    - Риск: НИЗКИЙ                                          │
│                                                            │
│  Спринт 2 (40ч):                                           │
│    - Разделение exec_simple_query() (8ч)                    │
│    - Удаление вызовов устаревших API (6ч)                   │
│    - 8 быстрых побед (26ч)                                  │
│    - Риск: СРЕДНИЙ                                         │
│                                                            │
│  Спринт 3 (36ч):                                           │
│    - Устранение дублирования процедур сканирования (6ч)     │
│    - Снижение связанности в executor (12ч)                   │
│    - 6 быстрых побед (18ч)                                  │
│    - Риск: СРЕДНИЙ                                         │
│                                                            │
│  Спринт 4 (32ч):                                           │
│    - Оставшиеся элементы сложности                         │
│    - Риск: НИЗКИЙ                                          │
│                                                            │
│  Оставшиеся элементы: 52 (22% — запланировать в будущем)   │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Гигиена конфигурации

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

6 типов осиротевших параметров

Тип Код Описание
yaml_unused R1 Секция YAML не имеет @property и не используется в коде
code_orphan R3 Код обращается к cfg.X, но @property X отсутствует в схеме
orphaned_dataclass R5 Датакласс не имеет соответствующего @property
unused_default R6 Поле датакласса отсутствует в YAML и не используется в коде

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

# Полное сканирование (все уровни серьёзности)
python -m src.cli dogfood config-check

# Только ошибки (используется в CI)
python -m src.cli dogfood config-check --level error --format text

# Вывод в JSON с рекомендациями по исправлению
python -m src.cli dogfood config-check --format json --fix-suggestions

# Пользовательские пути (для других проектов)
python -m src.cli dogfood config-check --config my_config.yaml --schema my_schema.py --source src/ lib/

Интеграция с аудитом

Результаты обнаружения осиротевших параметров поступают в композитный аудит (измерения Q3 — избыточный код и Q9 — поддерживаемость). Обработчик OrphanConfigHandler в S12 обрабатывает интенты config_hygiene и orphan_config.

CLI и MCP

# Анализ долга по запросу
python -m src.cli query "Рассчитать показатель технического долга"

# Глубокий анализ с LLM
python -m src.cli exec --prompt "Составить план погашения технического долга"

# Обнаружение быстрых побед
python -m src.cli query "Найти быстрые победы в техническом долге"

# Приоритизация
python -m src.cli query "Приоритизировать элементы долга по ROI"

MCP-инструмент: codegraph_tech_debt — доступен в интеграциях IDE для интерактивного анализа технического долга.

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

Метрики долга: - «Рассчитать показатель технического долга» - «Показать сводку по метрикам долга» - «Каков коэффициент технического долга?»

Быстрые победы: - «Найти быстрые победы в техническом долге» - «Показать лёгкие исправления с высокой достоверностью» - «Что можно исправить менее чем за 2 часа?»

Приоритизация: - «Приоритизировать долг по влиянию и трудозатратам» - «Ранжировать элементы долга по ROI» - «Показать стратегические элементы долга»

Планирование погашения: - «Составить спринт-план для погашения долга» - «Сколько спринтов нужно для критического долга?» - «Сгенерировать план погашения со скоростью 30ч»

Гигиена конфигурации: - «Проверить конфигурацию на неиспользуемые параметры» - «Найти осиротевшие ключи конфигурации» - «Запустить проверку гигиены конфигурации»

По паттернам: - «Найти комментарии TODO/FIXME» - «Найти использование устаревших API» - «Найти длинные методы более 50 строк» - «Найти мёртвый код»

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

  • Рефакторинг (S05) — S05 фокусируется на рекомендациях по рефакторингу, используя TechnicalDebtDetector, ImpactAnalyzer и RefactoringPlanner из src/refactoring/. S12 фокусируется на количественной оценке долга и планировании погашения, используя DebtCalculator, PrioritizationEngine и RepaymentPlanner из src/tech_debt/. S05 отвечает на вопрос «что рефакторить»; S12 — «сколько долга и когда его погасить»
  • Производительность (S06) — Технический долг, связанный с производительностью
  • Соответствие стандартам (S08) — Долг, связанный с соответствием стандартам
  • Массовый рефакторинг (S13) — Снижение долга в крупном масштабе через автоматические миграции символов