Бенчмарк пилота

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

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

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

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

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

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

Сначала договоритесь, что измеряете. Запишите длительность задачи от начала до готового результата, время участия человека и шкалу качества. Для сравнения трудозатрат отчёт сопоставляет baseline.people_effort_minutes с human_review_minutes результата пилота. Укажите, какие действия входят в каждое из этих измерений: выполнение, ревью или оба этапа. Так команда сможет объяснить полученную разницу и выбрать задачи для следующего этапа.

Манифест фиксирует набор задач, базовую линию и критерии успеха до интерпретации результатов. Полный учебный пример ниже содержит пять задач. Числа и ссылки вымышлены: это демонстрация формата, а не результаты заказчика. Сохраните его в pilot-manifest.json:

{
  "pilot_id": "illustrative-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
      }
    },
    {
      "task_id": "TASK-002",
      "case_id": "CASE-002",
      "baseline": {
        "elapsed_minutes": 120,
        "people_effort_minutes": 60,
        "quality_score": 0.7
      }
    },
    {
      "task_id": "TASK-003",
      "case_id": "CASE-003",
      "baseline": {
        "elapsed_minutes": 120,
        "people_effort_minutes": 60,
        "quality_score": 0.7
      }
    },
    {
      "task_id": "TASK-004",
      "case_id": "CASE-004",
      "baseline": {
        "elapsed_minutes": 120,
        "people_effort_minutes": 60,
        "quality_score": 0.7
      }
    },
    {
      "task_id": "TASK-005",
      "case_id": "CASE-005",
      "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 по умолчанию равен нулю, но явное значение упрощает проверку правила принятия решения.

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

Сохраните соответствующие учебные записи в pilot-runs.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": ["illustrative://TASK-001/run-1"]},
  {"task_id": "TASK-002", "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": ["illustrative://TASK-002/run-1"]},
  {"task_id": "TASK-003", "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": ["illustrative://TASK-003/run-1"]},
  {"task_id": "TASK-004", "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": ["illustrative://TASK-004/run-1"]},
  {"task_id": "TASK-005", "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": ["illustrative://TASK-005/run-1"]}
]

Ссылка на свидетельство должна вести на неизменяемый запуск, результат теста, ревью или другой проверяемый артефакт. Для отсутствующей записи отчёт выставляет decision: missing_data, добавляет missing_data_present и выдаёт рекомендацию adjust. При расчёте численных разниц он использует нулевые значения отсутствующей записи; пример ниже показывает, как это влияет на итог.

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

Запустите команду из репозитория CodeGraph или установленного окружения с тем же CLI. Подготовьте окружение Python и локальную конфигурацию по руководству CLI. Примеры используют PowerShell из корня репозитория CodeGraph. Замените обозначения файлов в кавычках на пути к двум сохранённым файлам:

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.

Команда возвращает 0, если отчёт создан, в том числе при рекомендации adjust. Проверяйте recommendation.decision и blocking_gaps: код возврата не подтверждает приёмку пилота. Учебные входы дают пять сравнений, долю приёмки 1, суммарно 210000 токенов, стоимость 12.5 и решение scale.

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

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

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

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

Разницы в comparisons вычисляются как результат пилота минус базовая оценка. Для учебных входов:

Число принятых задач делится на общее число задач; в примере это 5 / 5 = 1. Стоимость суммируется в той валюте, в которой вы записали token_cost.

Возможные блокеры: acceptance_rate_below_threshold, security_risk_above_threshold, quality_delta_below_threshold и missing_data_present. При adjust откройте указанные причины, дополните измерения или измените процесс и повторите сравнение. При scale используйте выполненные критерии и результаты задач для согласования следующего этапа пилота.

Пример: восстановление пропущенной записи

Скопируйте pilot-runs.json в pilot-missing-runs.json. Удалите из копии только запись с task_id: TASK-005; оставьте четыре остальные записи и корректный JSON-массив. Сохраните файл в UTF-8 без BOM. Манифест из учебного примера содержит все пять задач.

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

В отчёте задача TASK-005 получает decision: missing_data и missing_data: ["run_record"]. Её разницы равны 0 − 120 = −120 минут, 0 − 60 = −60 минут и 0 − 0.7 = −0.7 по шкале качества. Эти значения участвуют в общих итогах:

Причины adjust — quality_delta_below_threshold и missing_data_present. Команда возвращает 0: отчёт создан и содержит причины решения.

Восстановите исходную запись TASK-005 в pilot-missing-runs.json и повторите ту же команду. Проверьте правый столбец таблицы и пустой список recommendation.blocking_gaps.

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

В экспортируемом манифесте удаляется верхнеуровневое поле raw_customer_context. В записях manifest.tasks значения полей raw_customer_context и customer_private_notes заменяются на [redacted]. В отчёт входят вычисленные сравнения задач и их evidence_refs. Поле JSON raw_customer_content_included имеет значение false.

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

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

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

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

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