Приёмочный пилот агентской среды разработки: протокол на одном репозитории
Как провести приёмочный пилот агентской среды разработки на одном репозитории: песочница, три сценария, метрики, пороги внедрения и шаблон отчёта.

Приёмочный пилот агентской среды разработки — это короткий воспроизводимый эксперимент на одном реальном репозитории, после которого команда принимает решение «внедряем / не внедряем». Вы фиксируете исходное состояние кода, прогоняете три сценария (багфикс, рефакторинг, тест), считаете заранее определённые метрики и сравниваете их с порогами. Всё остальное — обзоры платформ, выбор инструмента, регламент ревью PR — остаётся за границами протокола.
Ниже — методика, которую можно провести за один рабочий цикл и повторить на другом репозитории. Числа в учебном примере помечены как учебные: это не результаты исследования, а иллюстрация расчётов.
Зачем пилот, а не сравнение платформ
Сравнение инструментов отвечает на вопрос «что выбрать». Пилот отвечает на другой: «даёт ли эта среда на нашем коде результат, который мы готовы принять в работу». Разница принципиальная: обзор опирается на чужие демо и маркетинговые метрики, пилот — на ваш репозиторий, ваши тесты и ваши затраты.
Границы протокола стоит зафиксировать письменно до старта:
- Внутри: один репозиторий, три сценария, набор метрик, пороги решения, требования к песочнице, одностраничный отчёт.
- Снаружи: сравнение нескольких платформ между собой, разработка собственных агентов и их инструментов, регламент ревью PR, инфраструктура запуска агента в продакшене.
Если команда хочет за один пилот ещё и выбрать платформу, эксперимент теряет воспроизводимость: меняются сразу два фактора — среда и код. Поэтому пилот проводится на одной среде, а выбор между средами — отдельная задача.
Подготовка песочницы
Песочница — это изолированная копия репозитория, в которой агент может менять код, запускать команды и не влиять на основную ветку. Подготовка занимает больше времени, чем сам прогон, и именно она определяет, можно ли доверять результатам.
Репозиторий и ветки
- Возьмите реальный репозиторий с работающими тестами. Репозиторий без тестов не подходит: тогда нечем измерить «зелёные тесты».
- Зафиксируйте исходное состояние: хеш коммита, версию зависимостей, команду запуска тестов и время её выполнения на чистом клоне.
- Создайте отдельную ветку под каждый сценарий. Один сценарий — одна ветка — одна сессия агента.
- Запретите агенту пушить в основную ветку и в удалённый репозиторий на уровне настроек доступа.
Изоляция секретов и внешних систем
Агентская среда выполняет команды в терминале и может обращаться к внешним сервисам. До запуска уберите из окружения боевые ключи, доступы к продакшен-базам и токены с широкими правами. Если среда поддерживает подключение внешних инструментов через протокол вроде MCP, проверьте список доступных инструментов и их права отдельно — для отладки таких подключений существует MCP Inspector.
Практическое правило: в песочнице должны быть только те доступы, без которых сценарий не выполняется. Всё остальное — вне окружения.
Старт среды
Порядок установки и первый запуск зависят от конкретного продукта. Для сред на базе Antigravity общий сценарий установки и знакомства с интерфейсом описан в официальном codelab. Не переносите оттуда настройки в пилот без проверки: доступные модели, квоты и состав продуктов меняются, поэтому фиксируйте версию и дату сверки в отчёте.
Три сценария на одном репозитории
Сценарии подобраны так, чтобы покрыть разные типы работы: точечное исправление, изменение структуры и создание нового кода. Каждый сценарий должен иметь однозначный критерий готовности — иначе оценка превращается в вкусовую.
Сценарий 1: багфикс
Что делаем: даём агенту описание воспроизводимой ошибки и просим исправить её минимальным изменением.
Критерий готовности: ошибка воспроизводится до правки и не воспроизводится после; существующие тесты проходят; диф ограничен областью бага.
Сценарий 2: рефакторинг
Что делаем: выбираем функцию с известными проблемами читаемости и просим переработать её без изменения поведения.
Критерий готовности: публичное поведение не изменилось, тесты проходят, диф объясним построчно.
Сценарий 3: тест
Что делаем: просим написать тест на участок кода, который сейчас не покрыт.
Критерий готовности: тест падает на исходной версии кода (если проверяет исправление) или проходит и действительно проверяет заявленное поведение; тест не дублирует существующий.
Учебный пример: репозиторий-калькулятор
Возьмём небольшой репозиторий с калькулятором. В нём есть функция деления, которая падает при делении на ноль; функция расчёта скидки с длинным телом и вложенными условиями; и участок округления без тестов. Это учебная конструкция, а не описание реального проекта.
- Багфикс: агенту дают шаги воспроизведения падения при делении на ноль. Готово, когда падение исчезает, а остальные тесты зелёные.
- Рефакторинг: агенту дают функцию скидки и просят разбить её на именованные шаги. Готово, когда все существующие тесты проходят без правок в них.
- Тест: агенту дают участок округления и просят покрыть его тестами. Готово, когда тест проверяет конкретные значения и проходит.
Важно: каждый сценарий запускается в чистой ветке от исходного коммита. Если запускать их подряд в одной сессии, агент будет опираться на собственные предыдущие правки, и сравнение потеряет смысл.
Метрики: определения и способ подсчёта
Метрики нужно определить до прогона. Иначе после пилота каждый посчитает их по-своему, и спор перейдёт из плоскости фактов в плоскость интерпретаций.
| Метрика | Определение | Как считать |
|---|---|---|
| Доля принятых правок | Доля предложенных агентом изменений, которые вошли в итоговый диф без переработки человеком | Принятые строки / предложенные строки; отдельно — доля принятых файлов |
| Итерации до зелёных тестов | Число циклов «правка → запуск тестов» до первого полностью зелёного прогона | Считается по журналу сессии; ручные запуски тестов человеком тоже входят |
| Вмешательства человека | Любое действие, меняющее ход работы: уточнение, отмена, ручная правка, перезапуск | Сумма по сценарию; фиксируется тип вмешательства |
| Время | От постановки задачи до критерия готовности, включая ожидание и проверку | В минутах, по каждому сценарию отдельно |
| Стоимость токенов | Расход по тарифу среды или провайдера за сценарий | По данным биллинга; если тариф не позволяет разделить сценарии — фиксируется как ограничение |
Учебная иллюстрация расчёта (числа вымышлены и приведены только для примера): если агент предложил 120 строк, а в итоговый диф вошло 90, доля принятых правок — 75%. Если до зелёных тестов потребовалось три цикла, метрика итераций — 3. Такие числа нельзя сравнивать с чужими результатами: они зависят от репозитория и постановки задачи.
Пороги решения «внедряем/нет»
Пороги — это редактируемые правила команды, а не универсальные нормативы. Ниже пример набора, который можно взять за основу и изменить под свои риски.
- Внедряем, если по всем трём сценариям критерий готовности достигнут, доля принятых правок не ниже согласованного минимума, а вмешательства человека не требуют переписывать результат с нуля.
- Внедряем с ограничениями, если сценарии выполнены, но, например, рефакторинг стабильно требует ручной доводки — тогда среда допускается к задачам определённого типа.
- Не внедряем, если хотя бы один сценарий не достигает критерия готовности или результат нельзя проверить тестами.
Пороги стоит согласовать до прогона и записать в отчёт вместе с обоснованием: почему именно такой минимум принятых правок и такое число вмешательств команда считает приемлемым.
Безопасность пилота
Агентская среда выполняет команды и меняет файлы. Минимальные ограничения:
- никаких боевых секретов и доступов к продакшену в окружении;
- запрет на push в основную ветку и на изменение CI-конфигурации без отдельного согласования;
- проверка диффа человеком до слияния — даже если тесты зелёные;
- фиксация списка внешних инструментов, к которым у агента есть доступ.
Проверка результата не сводится к «тесты прошли». Нужно посмотреть, что именно изменилось, нет ли побочных правок в несвязанных файлах и не отключены ли тесты ради зелёного прогона.
Разбор ошибки: почему смешивание сценариев ломает сравнение
Типичная ошибка пилота — запускать багфикс, рефакторинг и тест подряд в одной сессии, «чтобы сэкономить время». Кажется, что так быстрее, но результат становится неинтерпретируемым: агент видит свои предыдущие изменения, и непонятно, помог ли он в конкретном сценарии или просто продолжил начатое. Метрики по сценариям смешиваются, а повторный прогон даёт другой результат.
Лечится это дисциплиной веток: чистая ветка от исходного коммита на каждый сценарий и отдельный журнал сессии. Тогда пилот можно повторить и получить сопоставимые данные.
Одностраничный отчёт: шаблон и пример
Отчёт должен помещаться на одну страницу и отвечать на вопрос «внедряем или нет». Поля шаблона:
- Репозиторий, хеш исходного коммита, дата прогона.
- Среда и версия, дата сверки сведений о ней.
- Таблица по трём сценариям: критерий готовности, результат, метрики.
- Согласованные пороги и итоговое решение.
- Ограничения и открытые вопросы.
Пример заполнения на учебном репозитории-калькуляторе (числа условные): багфикс — критерий достигнут, итераций 2, вмешательств 1; рефакторинг — критерий достигнут, итераций 3, вмешательств 2; тест — критерий достигнут, итераций 1, вмешательств 0. Решение: внедряем с ограничениями, рефакторинг требует ручной проверки. Ограничение: стоимость токенов по сценариям не разделяется в тарифе.
Чек-лист запуска пилота
- Репозиторий с работающими тестами выбран, исходный коммит зафиксирован.
- Секреты и продакшен-доступы вынесены из окружения.
- Для каждого сценария создана отдельная ветка и записан критерий готовности.
- Метрики и пороги согласованы до прогона.
- Список внешних инструментов агента проверен.
- Дифф проверяется человеком до слияния.
- Отчёт заполнен по шаблону и содержит ограничения.
Если после пилота остаются вопросы, на которые протокол не отвечает — например, как среда ведёт себя на большом монорепозитории, — это повод для отдельного пилота, а не для расширения текущего.


