Бенчмарк пилота — Документация CodeGraph

Это руководство помогает сравнить небольшой согласованный набор задач заказчика с базовой линией. Команда формирует пакет для решения; выполнение задач, получение недостающих измерений и приёмку проводит заказчик.

На какой вопрос отвечает бенчмарк

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

scale, если выполнены все заданные критерии;
adjust, если данных не хватает или хотя бы один критерий не выполнен.

Выбирайте задачи, характерные для будущей эксплуатации. Не объединяйте в одном сравнении несвязанные прототипы, учебные упражнения и измерения, полученные в несопоставимых условиях.

Подготовка манифеста

Манифест фиксирует набор задач, базовую линию и критерии успеха до интерпретации результатов. Минимальная структура:

{
  "pilot_id": "customer-pilot-01",
  "success_criteria": {
    "min_acceptance_rate": 0.8,
    "max_high_risk_count": 0,
    "min_average_quality_delta": 0
  },
  "tasks": [
    {
      "task_id": "TASK-001",
      "case_id": "CASE-001",
      "baseline": {
        "elapsed_minutes": 120,
        "people_effort_minutes": 60,
        "quality_score": 0.7
      }
    }
  ]
}

Повторите объект задачи, чтобы в манифесте было 5–10 задач. Меньший или больший набор будет отклонён. Поля min_acceptance_rate и max_high_risk_count обязательны. min_average_quality_delta по умолчанию равен нулю, но явное значение упрощает проверку правила принятия решения.

Подготовка результатов

Передайте JSON-массив с одной записью кандидата на каждый task_id:

[
  {
    "task_id": "TASK-001",
    "accepted": true,
    "elapsed_minutes": 90,
    "human_review_minutes": 30,
    "quality_score": 0.8,
    "token_count": 42000,
    "token_cost": 2.5,
    "high_security_risk_count": 0,
    "evidence_refs": ["evidence://TASK-001/run-1"]
  }
]

Ссылка evidence должна вести на неизменяемый запуск, результат теста, ревью или другой проверяемый артефакт. Отсутствующая запись не считается нулевым результатом: отчёт добавит missing_data_present и выдаст рекомендацию adjust.

Формирование отчёта

Запустите команду из репозитория CodeGraph или установленного окружения с тем же CLI:

python -m src.cli pilot benchmark --manifest <pilot-manifest.json> --runs <pilot-runs.json> --format markdown

Для машинной обработки не указывайте --format markdown либо выберите --format json. Команда пишет результат в стандартный вывод. Для сохранения в файл используйте перенаправление оболочки:

python -m src.cli pilot benchmark --manifest <pilot-manifest.json> --runs <pilot-runs.json> --format json > pilot-report.json

Команда завершится с ненулевым кодом, если файл недоступен, JSON некорректен, нет обязательного поля или число задач выходит за пределы 5–10.

Чтение результата

JSON использует схему pilot-benchmark.v1 и содержит:

comparisons — решение и отклонения от базовой линии по каждой задаче;
totals — долю приёмки, суммарный риск безопасности, среднее изменение качества, число пропусков, количество и стоимость токенов;
recommendation.decision — scale или adjust;
recommendation.blocking_gaps — стабильные коды причин;
snapshot_id — детерминированный digest очищенного материала решения.

Возможные блокеры: acceptance_rate_below_threshold, security_risk_above_threshold, quality_delta_below_threshold и missing_data_present. Положительная рекомендация означает только выполнение численных критериев конкретного манифеста. Эксплуатационная готовность, проверка безопасности, развёртывание и коммерческое решение оцениваются отдельно.

Обращение с данными

Из отчёта удаляется верхнеуровневое поле raw_customer_context, а в задачах редактируются поля raw_customer_context и customer_private_notes. Флаг JSON raw_customer_content_included всегда равен false.

Такая фильтрация по именам полей дополняет DLP. Передавайте только одобренные минимальные измерения и нечувствительные идентификаторы доказательств. Перед передачей отчёта за границу контура заказчика проверьте готовый файл.

Чек-лист воспроизводимости

Согласуйте задачи, метод базовой оценки и пороги до запуска кандидата.
Выполняйте все 5–10 задач в сопоставимой инфраструктуре и по единым правилам ревью.
Для каждого результата запишите неизменяемые evidence refs.
Считайте отсутствующую запись пробелом, а не нулём.
Храните манифест, результаты, отчёт и точную ревизию CodeGraph вместе.
Фиксируйте человеческое решение отдельно от автоматически сформированной рекомендации.

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

src/exports/pilot_benchmark.py определяет схему, расчёты, правила рекомендации и очистку данных.
src/cli/governance_suite/pilot_commands.py определяет поддерживаемый CLI и обязательные аргументы.

Если статья расходится с этими файлами, авторитетны текущий исходный код и вывод справки CLI.