Списки разрешённых команд для код-ассистентов в реальных репозиториях

Что идёт не так без чётких ограничений

Код-ассистент может часами выглядеть аккуратным и всё равно повредить репозиторию одним неверным действием. Риск — это не только плохой код. Это может быть запись не в тот файл, команда shell, которая заходит слишком далеко, или тихий вызов в сервис, который никто не одобрял.

Полезные изменения обычно небольшие и их легко проверить. Представьте одно обновление обработчика, один фикс теста или опечатку в комментарии к конфигу. Рискованные действия выглядят иначе. Ассистент переписывает env-файл, удаляет миграции, которые считает неиспользуемыми, запускает cleanup-команду не в той папке или меняет настройки деплоя, потому что они кажутся ему несогласованными.

Проблема в том, что сначала это может выглядеть нормально. Коммит проходит базовые проверки и всё равно скрывает ущерб, который проявится позже. Удалите lock-файл — и сборки начнут расходиться. Измените настройки Docker или CI — и production перестанет совпадать с локальным запуском. Поменяйте один API endpoint на другой — и код начнёт отправлять данные в сервис, который команда вообще не собиралась использовать.

Одного доверия недостаточно, чтобы защитить живой кодовая базу. Даже сильная модель не знает, какие файлы политически чувствительны, юридически чувствительны или хрупки из-за многолетней истории. В реальных репозиториях самые маленькие файлы иногда несут самый большой риск: настройки платежей, правила auth, задания по биллингу, маршруты alert-ов и backup-скрипты.

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

Что значит список разрешений по задачам

Список разрешений по задачам — это короткий набор правил, который говорит, что код-ассистент может делать для одного типа работы, а что не может. Это меню прав, а не знак особого доверия. Ассистент не получает широкий доступ только потому, что однажды вёл себя хорошо.

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

Такое разделение важно, потому что каждая область ломается по-своему. Плохая запись в файл может затронуть не тот конфиг. Команда shell может удалить сгенерированные файлы или переписать историю. Исходящий вызов может отправить код, секреты или внутренние названия на хост, который никто не одобрял.

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

Вот почему права на инструменты по задачам работают лучше, чем широкое разрешение на всё подряд. Вы сохраняете пользу ассистента, давая ему достаточно доступа, чтобы закончить работу, а потом не даёте выйти за эти рамки. Он по-прежнему может писать код, править одобренные файлы и запускать безопасные команды, но не может бродить по всему репозиторию или вести себя как аккаунт разработчика с полными правами.

Начинайте с типов задач, а не с названий инструментов

Безопасные правила проще, когда вы группируете работу по типу задачи, а не по названию команды. Проверка только на чтение требует поиска, открытия файлов и просмотра diff. Ей не нужны права на запись, установка пакетов или сетевые вызовы.

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

Держите список задач коротким и понятным. Проверка только на чтение может смотреть файлы, искать по коду, читать логи и сравнивать diff. Небольшой багфикс может менять несколько файлов и запускать самый маленький тест, который подтверждает исправление. Рефакторинг может затронуть несколько файлов, прогнать тесты и обновить соседнюю документацию. Задача по прогону тестов может выполнять тестовые команды и собирать вывод без редактирования кода. Подготовка релиза может обновлять версии, changelog и собирать артефакты, но должна проходить через более строгую проверку.

Каждая задача должна получать самый маленький набор прав, который позволяет её завершить. Если небольшой багфикс требует только правки файлов и одной тестовой команды, ограничьтесь этим. Не разрешайте ещё и широкий доступ к shell только потому, что он может пригодиться потом.

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

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

Команды, которые строят AI-first рабочие процессы разработки, часто выигрывают от таких простых маршрутов. Людям их легче соблюдать, проверять и быстро замечать расползание прав.

Как собрать первый список разрешений

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

Дайте ассистенту широкий доступ на чтение по всему репозиторию. Ему обычно нужно смотреть соседние файлы, тесты и конфиги, чтобы понять контекст. Доступ на запись оставьте узким. Если задача ограничена src/billing и его тестами, разрешите запись только там. Не пускайте его в общий конфиг, папки деплоя и файлы пакетов, если задача явно этого не требует.

Некоторые пути должны каждый раз останавливать процесс и требовать участия человека. Этот короткий шлюз согласования важнее длинного policy-файла, который никто не соблюдает. В большинстве репозиториев этого списка достаточно:

• секреты и env-файлы
• миграции и изменения схемы
• скрипты деплоя и инфраструктурные конфиги
• настройки auth, billing и прав доступа
• root build-файлы, которые влияют на весь репозиторий

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

Большинство команд расширяют такие правила маленькими шагами. Сначала докажите, что один workflow безопасен и полезен. Потом добавляйте следующий тип задачи, сохраняйте те же привычки ревью и подтягивайте любую папку или файл, из-за которых возникали сюрпризы.

Решите, что ассистент может писать

Доступ на запись должен следовать за задачей, а не за инструментом. Если ассистент исправляет баг в коде приложения, разрешите ему менять файлы, где этот баг и живёт. Если задача только посмотреть, объяснить или предложить, оставьте репозиторий только для чтения.

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

Хороший default — узкая запись для обычной разработки. В web-приложении это часто означает исходные папки, тесты и, возможно, документацию рядом с изменённым кодом. Если задача не просит менять код, вообще не разрешайте запись.

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

• секретные файлы и env-шаблоны
• lock-файлы и состояние package manager
• настройки CI, например pipeline и workflow-файлы
• инфраструктурные папки вроде Terraform, Docker и deploy-скриптов
• database migrations, которые меняют production-данные

Сгенерированные файлы требуют ещё более жёстких правил. Они могут засыпать pull request шумом, скрыть плохое изменение и замедлить ревью. Если генерация кода — часть задачи, ограничьте ассистента именованной папкой вывода и задайте максимум файлов, которые он может создать или переписать за один запуск.

Держите короткий список ручной проверки и считайте его фиксированным. Во многих репозиториях этого достаточно: CI-конфиг, папки деплоя, код auth или billing, миграции и seed-данные, а также любой файл, где лежат секреты или production-настройки.

Например, если ассистент исправляет баг в Next.js в стартап-продукте, он может изменить страницу, API handler и файл теста. Он не должен трогать GitLab CI, Terraform или lock-файл, если только кто-то отдельно не попросил это изменить и не одобрил. Вот так правила доступа к репозиторию остаются полезными и не превращаются в тихий ущерб.

Задайте лимиты для команд shell

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

Для большинства репозиториев хорошо работает простой набор правил. Разрешите низкорисковые локальные команды, которые проверяют или подтверждают работу: поиск, форматирование, lint, type check и точечные тесты. Запрашивайте approval перед любой командой, которая меняет среду или состояние проекта: установкой пакетов, генерацией кода, инструментами для базы данных, migration-скриптами, seed-скриптами и deploy-помощниками. Полностью блокируйте разрушительные команды, включая массовое удаление, force reset, широкие изменения прав, команды для завершения процессов и shell-циклы, которые переписывают сразу много файлов.

Держите область применения узкой. Если задача затрагивает один сервис, разрешайте ассистенту запускать тесты только для этого сервиса. Если нужны логи, пусть он читает локальные файлы, а не трогает production-инструменты. В репозиториях, где используются GitLab runners, Kubernetes, Terraform или database scripts, эта граница особенно важна. Локальный linting — это одно. Выполнить kubectl apply, terraform apply, psql или release-скрипт — совсем другое.

Правила согласования должны покрывать и команды, которые подтягивают новый код. Установка пакета может изменить lock-файл, добавить post-install scripts или сломать сборку так, что это будет трудно заметить на ревью. Database-команды несут похожий риск. Одна неосторожная migration может оставить такой беспорядок, который потом придётся разбирать часами.

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

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

Задайте лимиты для исходящих вызовов

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

Неизвестные endpoints должны быть заблокированы по умолчанию. Одно это правило сильно снижает риск. Оно не даёт инструменту отправить код, секреты или детали сборки на случайный хост из-за подсказки, плагина или плохого default-настройки.

Не считайте все внешние сервисы одной корзиной. Issue tracker, package registry и model API имеют разный уровень риска и разные причины существования. Задача по документации не должна обращаться ни к одному из них. Обновление зависимостей может потребовать один registry и ничего больше. Задача по triage багов может читать один проект в issue tracker, но не должна публиковать комментарии, если этого не требует задача.

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

Это особенно важно в AI coding guardrails, где в одном workflow могут смешиваться code review, тестовые прогоны и обращения к моделям. Это не значит, что все шаги должны делить один и тот же сетевой доступ. Разделяйте права по задачам, чтобы одна безобидная работа не превратилась незаметно в утечку данных.

Логируйте каждый исходящий вызов. Записывайте тип задачи, инструмент, адрес назначения, время и то, был ли вызов разрешён или заблокирован. Из этих логов команды обычно извлекают две полезные вещи: некоторые разрешённые вызовы вообще никогда не происходят, значит их можно убрать; а некоторые заблокированные вызовы случаются достаточно часто, чтобы сделать правило более строгим и понятным.

Если вы можете ответить на вопрос «какая задача вызвала какой сервис и зачем?», значит у вас есть набор правил, которому люди могут доверять.

Простой пример из живого репозитория

Во многих небольших SaaS-репозиториях код приложения, логика billing и файлы деплоя лежат рядом. У вас может быть app/ для продукта, billing/ для invoice и payment flows, а также deploy/ или CI-файлы, которые могут отправить изменения в production.

Теперь возьмём обычный support ticket. Пользователь меняет часовой пояс на странице аккаунта, но API продолжает сохранять старое значение. Ассистент получает набор прав для bugfix, а не полный доступ к репозиторию.

Он может прочитать репозиторий, чтобы проследить, как поле проходит от UI к API и базе данных. Он может изменить форму аккаунта, API handler и один общий файл валидации. Он может запустить lint для изменённых файлов, прогнать тест настроек пользователя и один небольшой integration test, а затем посмотреть git diff, чтобы объяснить свой patch.

Этого достаточно для задачи. Этого недостаточно, чтобы бродить где попало.

Если ассистент пытается править billing/.env, менять webhook-настройки или трогать файлы в deploy/, правила записи его остановят. Если он пытается запустить kubectl apply, deploy-скрипт или команду Terraform, shell-политика тоже это заблокирует. Баг не связан ни с секретами, ни с шагами релиза, значит эти пути остаются закрытыми.

Вот где права по задачам действительно меняют ситуацию. Ассистент по-прежнему делает полезную работу, но не может превратить маленький UI-фикс в billing-инцидент или случайный rollout.

В этом примере ассистент находит старую привязку поля, обновляет три файла и выводит тесты в зелёный статус. Затем разработчик просматривает небольшой diff, проверяет вывод тестов и даёт финальное одобрение перед merge.

Последний шаг проходит быстро, потому что правила сохранили изменение узким. Команда всё ещё получает помощь от автоматизации, но человек решает, когда код затрагивает что-то вне задачи.

Ошибки, которые создают ложную безопасность

Плохой список разрешений может выглядеть строгим на бумаге и всё равно оставлять репозиторий открытым. Самая частая ошибка — один огромный набор правил на все задачи. Если ассистенту можно редактировать app-код, migration-файлы, скрипты деплоя и настройки CI в одном профиле, то маленькая задача по документации получает тот же радиус действия, что и запланированный рефакторинг. Так безобидная автоматизация превращается в тихий ущерб.

Команды также иногда перегибают в другую сторону. Они блокируют так много команд и путей записи, что обычная работа становится раздражающей. Тогда люди добавляют временные исключения, делятся широкими bypass-аккаунтами или просто отключают защитные правила, когда поджимают сроки. Правило, которое люди ненавидят, долго не живёт.

Правила по папкам помогают, но не решают проблему полностью. Путь в репозитории не говорит, что сделает команда shell. Ассистент может оставаться в разрешённой папке и всё равно сбросить состояние git, установить небезопасные пакеты, переписать сгенерированные файлы или открыть туннель во внешний сервис. Сеть создаёт ту же дыру. Узкое правило на запись всё равно может привести к утечке кода или секретов, если исходящие вызовы оставить открытыми.

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

Быстрая проверка на запах помогает. У вас, скорее всего, проблема, если одна политика покрывает все задачи, разработчики постоянно просят ручные обходы, правила упоминают только папки и игнорируют shell или сеть, или сам репозиторий уже изменился, а файл политики — нет.

Проверяйте правила каждый раз, когда добавляете package manager, deploy-скрипт или новый внешний API. Эта маленькая привычка ловит больше реального риска, чем длинный policy-файл, который никто не обновляет.

Короткая проверка перед запуском

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

Небольшая проверка перед запуском помогает:

• Назначьте владельца для каждого типа задачи.
• Поставьте approval перед рискованной записью и рискованными командами.
• Сделайте логи простыми для чтения.
• Оставьте путь обхода коротким и понятным.
• Протестируйте несколько маленьких задач до более широкого использования.

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

Логи важнее, чем многим кажется. Когда что-то идёт не так, понятные записи экономят время. Вы должны уметь за минуту ответить на три простых вопроса: что изменилось, кто это одобрил и что ассистент пытался сделать до блокировки.

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

Что делать дальше

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

Соберите первый список разрешений только вокруг этой задачи. Разрешите ассистенту читать то, что нужно, писать только там, где живёт задача, запускать короткий набор shell-команд и не делать исходящих вызовов, если задача по-настоящему от них не зависит. Малый scope легче доверять и легче исправлять.

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

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

Команды, которым нужна внешняя помощь с таким сетапом, иногда работают с Oleg Sotnikov через oleg.is. Его advisory-работа сфокусирована на практической AI-augmented development, защитных правилах для репозиториев и Fractional CTO support для стартапов и небольших команд.

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