Сценарий 06: исследование проблемы производительности

Используйте этот сценарий, когда есть измеренная проблема задержки, пропускной способности, CPU, памяти, ввода-вывода или конкуренции и нужно сузить ответственный участок кода. CodeGraph ранжирует структурных кандидатов и показывает вызывающий код, однако статический анализ создаёт static hypothesis, а не заключение о производительности среды исполнения.

Сначала определите измерение

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

{
  "measurement_environment": "<оборудование, runtime, конфигурация, данные>",
  "baseline_measurement": "<метрика, значение, число выборок>",
  "candidate_measurement": "<та же метрика после изменения>"
}

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

Типизированный запрос на исследование

Используйте ролевой сценарий разработчика с принятой задачей:

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

request = RoleBoundScenarioInvocationRequest(
    query="Ранжируй пути кода, которые могут объяснить измеренную регрессию задержки запроса.",
    employee_id="codegraph_developer",
    scenario_id="scenario_06",
    event_type="implementation_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<profile-or-trace-ref>", "<benchmark-ref>"],
        "file_paths": ["<bounded-source-path>"],
    },
)

result = invoke_role_bound_scenario_request(request)

При отсутствии project_key, namespace или task_id контракт закрывается с ошибкой role_bound_scenario_contract_missing. Для codegraph_developer сценарий условный, поэтому запрос должен называть реальный симптом производительности.

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

Для выбранного символа используйте текущую команду impact:

python -m src.cli impact <symbol> --db PATH --format json

Считайте вызывающий код, затронутые методы, глубину и impact score навигационными свидетельствами. Пустой результат означает, что символ не найден в выбранном графе, а не безопасность его изменения.

Цикл оптимизации от теста

Воспроизведите проблему с зафиксированной нагрузкой и сохраните baseline_measurement.
Свяжите симптом с одним ограниченным путём кода по профилю, трассе или счётчикам.
Проверьте в CodeGraph вызывающий код, зависимости и риски этого пути.
Добавьте регрессионный тест корректности и, если измерение достаточно устойчиво, пороговый или сравнительный тест производительности.
Внесите одно небольшое изменение без несвязанной чистки.
Запустите тесты корректности, тот же benchmark и ту же конфигурацию профилировщика.
Сохраните candidate_measurement, разброс и регрессии; оставьте изменение только при воспроизводимом улучшении.

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

Условия остановки

Остановитесь, если измерение не воспроизводится, изменились среда или данные, кандидат пересекает несогласованную границу API, авторизации или хранения либо выигрыш требует ослабить корректность или безопасность. Верните гипотезу и недостающие свидетельства вместо заявления об успехе.

Поддерживаемые источники контракта

CLI анализа влияния: src/cli/analysis_commands/impact_commands.py
Маршрутизация типизированного сценария: src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py
Политика производительности разработчика: src/digital_employees/runtime/scenarios/employee_scenario_invocation.py

Для carrier реализации используйте разработку функции, а для привязанного к ревизии ревью — проверку кода.