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

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

Выберите способ анализа

MCP-команда сводки принимает пустой объект аргументов и определяет активный проект из контекста runtime. Она возвращает счётчики графа и участки высокой сложности. config-check проверяет использование конфигурации. Для плана погашения с этапами работ запустите сценарий 12.

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

Подготовьте окружение Python и локальную конфигурацию по руководству CLI и программному интерфейсу. Для сценария 12 нужны принятая задача разработчика, актуальный CPG проекта, доступные сервисы графа и настроенная LLM. Выполняйте пример Python в этом окружении. Замените обозначения в контексте на принятый проект, namespace, задачу, ссылки на свидетельства и пути исходников.

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

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

Как выбрать первый этап

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

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

После изменения получите новую сводку и сравните метод с той же исходной ревизией. Снижение сложности покажет изменение структуры; результаты проверок покажут, что загрузка и восстановление работают. Так план связывает находку с проверяемым результатом для пользователей. Числа и методы здесь иллюстративные; для своего проекта используйте позиции из complexity_hotspots и историю работы команды.

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

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

request = RoleBoundScenarioInvocationRequest(
    query="Ранжируй долг в конвейере импорта и предложи ограниченные этапы погашения.",
    employee_id="codegraph_developer",
    scenario_id="scenario_12",
    event_type="implementation_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<revision-ref>", "<quality-evidence-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"])

Для отдельной агрегированной сводки вызовите dashboard MCP:

codegraph_quality_tech_debt_report_get()

Получите сводку технического долга через MCP

1. Подключитесь к CodeGraph через подключение рецензента для чтения с профилем codex:role:codegraph_reviewer:read. Порядок подключения описан в руководстве оператора MCP.
2. Выберите проект, для которого построен актуальный CPG.
3. Найдите codegraph_quality_tech_debt_report_get в каталоге инструментов клиента и вызовите его с пустым объектом аргументов {}.
4. Прочитайте JSON-сводку. Сохраните её вместе с ревизией проекта и временем запроса.
5. Откройте исходные позиции из complexity_hotspots, сопоставьте их с тестами и выберите участки для плана погашения долга.

Доля dead_method_ratio записана как число от 0 до 1. Например, при total_methods=102570 и dead_methods=6223 сводка возвращает dead_method_ratio=0.061: после округления это 6,1% методов графа. Умножьте долю на 100 для отображения в процентах. Используйте исходный счётчик dead_methods, чтобы оценить количество кандидатов для проверки.

Каждый элемент complexity_hotspots содержит name, full_name, file, line и complexity. Перейдите к указанному файлу и строке, чтобы изучить ветвления функции и подготовить тесты перед её изменением.

Если JSON содержит error, восстановите доступ к графу и повторите запрос: счётчики в таком ответе заполнены нулями из-за сбоя сбора данных. Ошибка определения контекста проекта возвращается текстом Error: ...; выберите доступный проект и повторите вызов.

Проверьте использование конфигурации

Выполните python -m src.cli dogfood config-check из корня рабочей копии CodeGraph в подготовленном окружении CLI. Команда читает config.yaml, схему настроек и исходники. В текстовом отчёте каждая находка содержит уровень, имя параметра и описание; для находок в исходниках также указан файл и строка. Итоговая строка Summary показывает число ошибок, предупреждений и информационных записей.

Код возврата 2 означает наличие ошибок, 1 — предупреждений без ошибок, 0 — отсутствие ошибок и предупреждений. При коде 0 отчёт может содержать информационные записи. Откройте указанные позиции и проверьте использование параметров, прежде чем включать изменение конфигурации в план. Форматы JSON/CSV, фильтрация по уровню и сохранение отчёта описаны в руководстве по догфудингу.

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

Для сценария 12 сохраните предложенные этапы, ссылки на исходники, допущения, риски и метаданные вызова. Для dashboard-сводки — время наблюдения и ревизию проекта. Для config-check — точную ревизию конфигурации и вывод команды.

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

Метаданные сценария содержат оценки трудоёмкости, серьёзности долга и длительности погашения. Это расчётные оценки, а не измеренное время поставки или утверждённый бюджет. MCP-команда сводки может вернуть текст Error: ... вместо JSON. Проверьте содержимое ответа до разбора или интерпретации чисел.

От плана к реализации

Сценарий, сводка дашборда и проверка конфигурации возвращают результаты анализа и сохраняют исходники без изменений. Ответственный человек одобряет область, план и продуктовый приоритет. Для каждого принятого этапа создайте задачу реализации с tests-first изменением, критериями приёмки и профильным ревью.

Разделяйте результаты разных ревизий. Данные дашборда позволяют оценить объём долга; при их отсутствии используйте исходники и целевые тесты.

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

• MCP вернул текст ошибки: проверьте контекст активного проекта и доступность CPG, затем повторите запрос сводки.
• Сценарий дал общий ответ: сузьте компонент, ссылки на свидетельства и вопрос решения.
• config-check нашёл ключ: подтвердите, что он действительно не используется, прежде чем удалять конфигурацию.
• Приоритет оспаривается: разделите продуктовые и эксплуатационные данные и повторите ревью решения.

Связанные материалы

• Каталог сценариев
• Сценарий 05: рефакторинг
• Сценарий 13: массовый рефакторинг
• Догфудинг