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

Кодовый агент уже выбран — дальше начинается инженерия. Задача этой инструкции: за неделю довести пилот на одном репозитории до состояния, когда агент выполняет реальные задачи, а команда понимает, где он работает, что ему разрешено, сколько он тратит и как проверить его действия. Сравнение инструментов, промты и регламент ревью 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 — топология. Выберите локальный, CI- или выделенный раннер по таблице выше. Зафиксируйте, где будут храниться секреты.
- День 2 — права и секреты. Создайте отдельный токен с минимальными скоупами, включите защиту main, заведите ветку агента.
- День 3 — предохранители. Задайте лимиты и стоп-условия, проверьте, что запуск останавливается при превышении диффа.
- День 4 — журнал. Настройте запись полей задачи и формулу стоимости. Прогоните пустую задачу, чтобы убедиться, что журнал пишется.
- День 5 — реальная задача. Возьмите одну небольшую задачу из бэклога: исправление воспроизводимой ошибки или обновление тестов. Агент работает в своей ветке, результат проверяется человеком.
Типовой порядок расширения прав выглядит так: сначала read-only режим, чтобы агент разбирал незнакомый модуль и предлагал план правок; затем запись в отдельную ветку — с лимитом на размер диффа и запретом менять конфигурацию CI. Переход между режимами оправдан, когда по журналу видно, какие файлы агент читает и сколько токенов на это уходит.
Критерии готовности и план расширения
Пилот можно считать рабочим, если выполнены все пункты:
- агент запускается воспроизводимо в выбранной топологии;
- push в main технически невозможен, изменения появляются только в ветке агента;
- токен агента отдельный, скоупы минимальны, процедура отзыва описана;
- стоп-условия срабатывают в тестовом прогоне;
- журнал позволяет посчитать стоимость одной задачи;
- хотя бы одна реальная задача прошла путь от запуска до проверки человеком.
Расширяйте пилот по одному измерению за раз: второй репозиторий, затем более широкие права, затем новые типы задач. Инфраструктура для ИИ-агентов разработки растёт предсказуемо только тогда, когда каждое расширение опирается на данные журнала, а не на ожидания. Если задача агента перестаёт помещаться в лимиты, сначала разберитесь, что именно растёт — контекст, число итераций или размер диффа.
Смежные темы: ИИ-агенты в разработке, ИИ-агенты и стандарты, ИИ-агенты для разработки встраиваемых систем.
Источники
- MCP Inspector — назначение инструмента отладки MCP-серверов и режимы клиентов (
--web,--cli,--tui). - GitHub Docs: Secure use reference — практики безопасности workflow, ограничения автоматической редакции секретов, риски привилегированных триггеров.


