Разработка и внедрение моделей

Разработка и инфраструктура ИИ-агентов для кода: минимальный пилот за неделю

Как запустить кодового ИИ-агента в команде: топология исполнения, изоляция, права на репозиторий, секреты, лимиты, журнал и пилот на одном репозитории.

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

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

Короткий ответ: минимальная инфраструктура для ИИ-агентов разработки — это изолированный раннер, отдельная ветка без права push в main, отдельный токен с минимальными скоупами, набор предохранителей и журнал действий. Всё остальное — расширение.

Топология исполнения: локально, CI или выделенный раннер

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

КритерийЛокально у разработчикаCI-раннерВыделенный облачный раннер
Изоляция средыСлабая: агент видит рабочую машинуСредняя: эфемерная среда на запускВысокая: контролируемый образ и сеть
Доступ к секретамРиск утечки в локальные файлы и логиЧерез хранилище секретов платформыЧерез отдельное хранилище и короткоживущие токены
СтоимостьНулевая инфраструктурная, но оплачивается время инженераОплата минут раннераПостоянная оплата среды плюс вызовы модели
Скорость итерацииВысокаяСредняя: цикл через коммитСредняя или низкая: нужен деплой образа
Пригодность для командыИндивидуальные экспериментыПовторяемые задачи на репозиторииДолгие задачи, несколько репозиториев

Практическое правило для пилота: начинайте с той топологии, где проще всего ограничить ущерб от ошибки агента. Если команда не готова выдавать агенту доступ к репозиторию с правом записи, начните с read-only сценариев — исследования кода и подготовки предложений в виде диффа. Облачные агенты для кода оправданы, когда задачи долгие и их нужно изолировать от машины разработчика.

Изоляция среды и контрольная точка Git

Изоляция нужна не для защиты от «злого» агента, а для предсказуемости: агент не должен видеть чужие проекты, домашние каталоги с токенами и не должен менять состояние, которое команда не готова откатить.

  • Отдельный клон репозитория на каждый запуск — так рабочее дерево разработчика не смешивается с изменениями агента.
  • Контейнер с фиксированным образом — зависимости и версии инструментов совпадают между запусками.
  • Контрольная точка Git перед изменениями — коммит или ветка, к которой можно вернуться и с которой можно сравнить дифф.
  • Ограниченная сеть — агенту не нужен произвольный доступ в интернет для правки кода; исключения добавляйте осознанно.

В CI изоляция достигается тем, что каждый запуск получает чистую среду. При этом документация GitHub предупреждает: автоматическая редакция секретов не гарантирована, а недоверенный код из pull request нельзя выполнять в привилегированных workflow. Для агента это означает простое правило — не запускать его на форках и внешних вкладах в том же workflow, где доступны секреты и право записи.

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

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

РежимЧтениеЗаписьКогда подходит
Read-onlyРепозиторий и историяНетИсследование кода, анализ ошибок, предложения в виде текста
Отдельная веткаРепозиторийТолько ветка агентаПилот с реальными правками и диффом на проверку
CI-задачаРепозиторийВетка агента и артефакты запускаПовторяемые задачи: тесты, обновление документации

Запрет push в main стоит зафиксировать на уровне настроек репозитория, а не только в инструкции для агента: правила защиты ветки не зависят от того, насколько аккуратно модель следует текстовому описанию. Отдельно ограничьте силу токена: если агент пишет только в одну ветку, ему не нужен токен с правом администрирования репозитория.

Секреты и минимальные скоупы

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

  • Отдельный токен только для агента. Не переиспользуйте личный токен разработчика и токен релизного пайплайна.
  • Минимальные скоупы. Чтение репозитория и запись в одну ветку — типичный минимум для пилота; всё остальное добавляйте по конкретной необходимости.
  • Короткий срок жизни. Там, где платформа позволяет выдавать временные токены, предпочтите их долгоживущим.
  • Ротация и отзыв. Заранее определите, кто и как отзывает токен, если поведение агента вызвало вопросы.
  • Что нельзя отдавать. Ключи от продакшена, платёжные секреты, доступ к инфраструктуре и персональные данные — вне области пилота.

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

Предохранители: токены, таймаут, максимальный diff, стоп-условия

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

limits:
  max_tokens_per_task: <значение>
  timeout_minutes: <значение>
  max_diff_lines: <значение>
  max_iterations: <значение>
  max_files_changed: <значение>
stop_conditions:
  - diff_exceeds_limit
  - tests_failed_twice
  - touched_protected_paths
  - secret_pattern_detected

Конкретные числа зависят от репозитория и задачи, поэтому подставляйте их осознанно и фиксируйте в документации пилота. Смысл в том, чтобы запуск останавливался сам, а не чтобы человек заметил проблему после факта. Полезные стоп-условия: превышение размера диффа, повторное падение тестов, изменение защищённых путей (миграции, конфигурация CI, инфраструктурные файлы) и срабатывание проверки на похожие на секреты строки.

Учебный, условный пример: для репозитория, где типичная правка занимает 40–80 строк, лимит max_diff_lines: 200 отсекает «переписывание модуля целиком», а max_iterations: 6 останавливает цикл, в котором агент не сходится к рабочему тесту. Эти числа вымышленные и служат только иллюстрацией логики настройки — их нельзя переносить в свой проект без проверки.

Ограничение: предохранители снижают риск, но не заменяют проверку диффа человеком. Изменения агента проходят тот же путь приёмки, что и изменения разработчика.

Журнал действий и учёт стоимости

Без журнала пилот невозможно ни оценить, ни расширить. Минимальный набор полей на одну задачу: идентификатор запуска, топология, ветка, число итераций, использованные токены, длительность, размер диффа, сработавшие стоп-условия и итог — принято, отклонено, доработано.

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

Для отладки интеграций полезен MCP Inspector: по документации протокола это инструмент для тестирования и отладки MCP-серверов с отдельными клиентами для браузера (--web), командной строки (--cli) и терминала (--tui), с просмотром обмена JSON-RPC. Это помогает проверить, какие инструменты агент реально вызывает, до того как разбирать последствия в репозитории.

Сквозной пилот на одном репозитории за неделю

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

  1. День 1 — топология. Выберите локальный, CI- или выделенный раннер по таблице выше. Зафиксируйте, где будут храниться секреты.
  2. День 2 — права и секреты. Создайте отдельный токен с минимальными скоупами, включите защиту main, заведите ветку агента.
  3. День 3 — предохранители. Задайте лимиты и стоп-условия, проверьте, что запуск останавливается при превышении диффа.
  4. День 4 — журнал. Настройте запись полей задачи и формулу стоимости. Прогоните пустую задачу, чтобы убедиться, что журнал пишется.
  5. День 5 — реальная задача. Возьмите одну небольшую задачу из бэклога: исправление воспроизводимой ошибки или обновление тестов. Агент работает в своей ветке, результат проверяется человеком.

Типовой порядок расширения прав выглядит так: сначала read-only режим, чтобы агент разбирал незнакомый модуль и предлагал план правок; затем запись в отдельную ветку — с лимитом на размер диффа и запретом менять конфигурацию CI. Переход между режимами оправдан, когда по журналу видно, какие файлы агент читает и сколько токенов на это уходит.

Критерии готовности и план расширения

Пилот можно считать рабочим, если выполнены все пункты:

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

Расширяйте пилот по одному измерению за раз: второй репозиторий, затем более широкие права, затем новые типы задач. Инфраструктура для ИИ-агентов разработки растёт предсказуемо только тогда, когда каждое расширение опирается на данные журнала, а не на ожидания. Если задача агента перестаёт помещаться в лимиты, сначала разберитесь, что именно растёт — контекст, число итераций или размер диффа.

Смежные темы: ИИ-агенты в разработке, ИИ-агенты и стандарты, ИИ-агенты для разработки встраиваемых систем.

Источники

  • MCP Inspector — назначение инструмента отладки MCP-серверов и режимы клиентов (--web, --cli, --tui).
  • GitHub Docs: Secure use reference — практики безопасности workflow, ограничения автоматической редакции секретов, риски привилегированных триггеров.