Технический лидер выявляет, оценивает и планирует погашение технического долга с помощью CPG-анализа.
Содержание¶
- Быстрый старт
- Как это работает
- Классификация интентов
- Двухфазная архитектура
- Три агента
- Обнаружение долга
- 6 паттернов долга
- 4 категории долга
- Модель данных DebtItem
- Примеры сканирования
- Метрики долга
- Поля DebtMetrics
- Пример метрик
- Приоритизация
- Оценка ROI
- Быстрые победы
- Стратегические элементы
- Пример приоритизации
- Планирование погашения
- Планирование по спринтам
- Модель данных RepaymentPlan
- Пример плана погашения
- Гигиена конфигурации
- 6 типов осиротевших параметров
- Использование из CLI
- Интеграция с аудитом
- CLI и MCP
- Примеры вопросов
- Связанные сценарии
Быстрый старт¶
# Выберите сценарий технического долга
/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) — Снижение долга в крупном масштабе через автоматические миграции символов