Инструменты и ресурсы

Приёмочный пилот агентской среды разработки: протокол на одном репозитории

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

Редакция DeepMe
· Обновлено · 7 мин чтения
Три карточки, связанные лентой, рядом закрытый керамический кубик и отдельная стопка карточек.

Приёмочный пилот агентской среды разработки — это короткий воспроизводимый эксперимент на одном реальном репозитории, после которого команда принимает решение «внедряем / не внедряем». Вы фиксируете исходное состояние кода, прогоняете три сценария (багфикс, рефакторинг, тест), считаете заранее определённые метрики и сравниваете их с порогами. Всё остальное — обзоры платформ, выбор инструмента, регламент ревью PR — остаётся за границами протокола.

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

Зачем пилот, а не сравнение платформ

Сравнение инструментов отвечает на вопрос «что выбрать». Пилот отвечает на другой: «даёт ли эта среда на нашем коде результат, который мы готовы принять в работу». Разница принципиальная: обзор опирается на чужие демо и маркетинговые метрики, пилот — на ваш репозиторий, ваши тесты и ваши затраты.

Границы протокола стоит зафиксировать письменно до старта:

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

Если команда хочет за один пилот ещё и выбрать платформу, эксперимент теряет воспроизводимость: меняются сразу два фактора — среда и код. Поэтому пилот проводится на одной среде, а выбор между средами — отдельная задача.

Подготовка песочницы

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

Репозиторий и ветки

  1. Возьмите реальный репозиторий с работающими тестами. Репозиторий без тестов не подходит: тогда нечем измерить «зелёные тесты».
  2. Зафиксируйте исходное состояние: хеш коммита, версию зависимостей, команду запуска тестов и время её выполнения на чистом клоне.
  3. Создайте отдельную ветку под каждый сценарий. Один сценарий — одна ветка — одна сессия агента.
  4. Запретите агенту пушить в основную ветку и в удалённый репозиторий на уровне настроек доступа.

Изоляция секретов и внешних систем

Агентская среда выполняет команды в терминале и может обращаться к внешним сервисам. До запуска уберите из окружения боевые ключи, доступы к продакшен-базам и токены с широкими правами. Если среда поддерживает подключение внешних инструментов через протокол вроде MCP, проверьте список доступных инструментов и их права отдельно — для отладки таких подключений существует MCP Inspector.

Практическое правило: в песочнице должны быть только те доступы, без которых сценарий не выполняется. Всё остальное — вне окружения.

Старт среды

Порядок установки и первый запуск зависят от конкретного продукта. Для сред на базе Antigravity общий сценарий установки и знакомства с интерфейсом описан в официальном codelab. Не переносите оттуда настройки в пилот без проверки: доступные модели, квоты и состав продуктов меняются, поэтому фиксируйте версию и дату сверки в отчёте.

Три сценария на одном репозитории

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

Сценарий 1: багфикс

Что делаем: даём агенту описание воспроизводимой ошибки и просим исправить её минимальным изменением.

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

Сценарий 2: рефакторинг

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

Критерий готовности: публичное поведение не изменилось, тесты проходят, диф объясним построчно.

Сценарий 3: тест

Что делаем: просим написать тест на участок кода, который сейчас не покрыт.

Критерий готовности: тест падает на исходной версии кода (если проверяет исправление) или проходит и действительно проверяет заявленное поведение; тест не дублирует существующий.

Учебный пример: репозиторий-калькулятор

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

  • Багфикс: агенту дают шаги воспроизведения падения при делении на ноль. Готово, когда падение исчезает, а остальные тесты зелёные.
  • Рефакторинг: агенту дают функцию скидки и просят разбить её на именованные шаги. Готово, когда все существующие тесты проходят без правок в них.
  • Тест: агенту дают участок округления и просят покрыть его тестами. Готово, когда тест проверяет конкретные значения и проходит.

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

Метрики: определения и способ подсчёта

Метрики нужно определить до прогона. Иначе после пилота каждый посчитает их по-своему, и спор перейдёт из плоскости фактов в плоскость интерпретаций.

МетрикаОпределениеКак считать
Доля принятых правокДоля предложенных агентом изменений, которые вошли в итоговый диф без переработки человекомПринятые строки / предложенные строки; отдельно — доля принятых файлов
Итерации до зелёных тестовЧисло циклов «правка → запуск тестов» до первого полностью зелёного прогонаСчитается по журналу сессии; ручные запуски тестов человеком тоже входят
Вмешательства человекаЛюбое действие, меняющее ход работы: уточнение, отмена, ручная правка, перезапускСумма по сценарию; фиксируется тип вмешательства
ВремяОт постановки задачи до критерия готовности, включая ожидание и проверкуВ минутах, по каждому сценарию отдельно
Стоимость токеновРасход по тарифу среды или провайдера за сценарийПо данным биллинга; если тариф не позволяет разделить сценарии — фиксируется как ограничение

Учебная иллюстрация расчёта (числа вымышлены и приведены только для примера): если агент предложил 120 строк, а в итоговый диф вошло 90, доля принятых правок — 75%. Если до зелёных тестов потребовалось три цикла, метрика итераций — 3. Такие числа нельзя сравнивать с чужими результатами: они зависят от репозитория и постановки задачи.

Пороги решения «внедряем/нет»

Пороги — это редактируемые правила команды, а не универсальные нормативы. Ниже пример набора, который можно взять за основу и изменить под свои риски.

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

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

Безопасность пилота

Агентская среда выполняет команды и меняет файлы. Минимальные ограничения:

  • никаких боевых секретов и доступов к продакшену в окружении;
  • запрет на push в основную ветку и на изменение CI-конфигурации без отдельного согласования;
  • проверка диффа человеком до слияния — даже если тесты зелёные;
  • фиксация списка внешних инструментов, к которым у агента есть доступ.

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

Разбор ошибки: почему смешивание сценариев ломает сравнение

Типичная ошибка пилота — запускать багфикс, рефакторинг и тест подряд в одной сессии, «чтобы сэкономить время». Кажется, что так быстрее, но результат становится неинтерпретируемым: агент видит свои предыдущие изменения, и непонятно, помог ли он в конкретном сценарии или просто продолжил начатое. Метрики по сценариям смешиваются, а повторный прогон даёт другой результат.

Лечится это дисциплиной веток: чистая ветка от исходного коммита на каждый сценарий и отдельный журнал сессии. Тогда пилот можно повторить и получить сопоставимые данные.

Одностраничный отчёт: шаблон и пример

Отчёт должен помещаться на одну страницу и отвечать на вопрос «внедряем или нет». Поля шаблона:

  1. Репозиторий, хеш исходного коммита, дата прогона.
  2. Среда и версия, дата сверки сведений о ней.
  3. Таблица по трём сценариям: критерий готовности, результат, метрики.
  4. Согласованные пороги и итоговое решение.
  5. Ограничения и открытые вопросы.

Пример заполнения на учебном репозитории-калькуляторе (числа условные): багфикс — критерий достигнут, итераций 2, вмешательств 1; рефакторинг — критерий достигнут, итераций 3, вмешательств 2; тест — критерий достигнут, итераций 1, вмешательств 0. Решение: внедряем с ограничениями, рефакторинг требует ручной проверки. Ограничение: стоимость токенов по сценариям не разделяется в тарифе.

Чек-лист запуска пилота

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

Если после пилота остаются вопросы, на которые протокол не отвечает — например, как среда ведёт себя на большом монорепозитории, — это повод для отдельного пилота, а не для расширения текущего.