К содержимому
Блог

Автоматическое code review с LLM: конвейер для pull request

Автоматическое code review с LLM: конвейер для pull request

Автоматическое code review с LLM приносит пользу, когда бот ищет проверяемые гипотезы, а не выносит вердикт по pull request. Его задача, заметить подозрительный участок, назвать риск и показать путь проверки. Решение о слиянии остаётся у человека и обычных проверок CI.

Коротко

  • Начинайте с малого: diff, правила репозитория и результат CI важнее полного снимка монорепозитория.

  • Комментарий бота должен ссылаться на строку, условие сбоя и способ проверки.

  • Для автоматизации выпускайте отдельный ключ с ограничениями и проверяйте расход в журнале.

Схема потока автоматического ревью: diff, проверки и правила формируют контекст, модель готовит сигнал, а решение принимает ревьюер.

Где конвейер даёт сигнал

У pull request есть удобная точка входа: автор уже сузил область изменения, а CI показывает, какие проверки запущены. Бот получает diff, список изменённых файлов, описание задачи и результаты обязательных джобов. Потом он отвечает не на вопрос «хорош ли код», а на несколько узких вопросов:

  • меняется ли граница доступа, денег или внешнего API;

  • есть ли ветка, которую не покрывает добавленный тест;

  • расходится ли код с локальными правилами репозитория;

  • выглядит ли изменение шире заявленной задачи.

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

Первый фильтр в таком конвейере должен быть детерминированным. Линтеры, тесты, проверка типов и анализ зависимостей возвращают факты. LLM получает их вместе с diff и ищет смысловую дыру между зелёными галочками. Не подменяйте один слой другим. Тест может пройти, хотя автор забыл сценарий повторного запроса. Модель может заметить этот сценарий, но не докажет, что его нет без кода и воспроизведения.

Соберите контекст без свалки файлов

Самая частая причина плохих комментариев, бот читает слишком много. В большой базе он тратит контекст на несвязанные файлы, а затем уверенно объясняет прошлую архитектуру вместо текущего diff. Контекст стоит собирать по слоям.

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

Начните с ограниченного размера diff. Крупный pull request лучше разрезать по независимым каталогам или коммитам. Для каждого фрагмента бот получает одну задачу: найти нарушение инварианта, недостающий тест или опасное побочное действие. В конце отдельный проход сверяет выводы и удаляет дубли.

Секреты, токены, дампы запросов и рабочие ключи в контекст не попадают. Если тестовый лог содержит секрет, его сначала маскирует шаг CI. Ключ для проверки создают отдельно от локальных ключей разработчиков: в Relay для него можно задать разрешённые модели, предел запросов в минуту, срок действия и ограничения расхода в кабинете ключей. Для выбора класса модели под задачу пригодится разбор как выбрать модель для кода.

Разделите роль модели и роль правил

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

Полезно выдать модели строгий формат ответа. Например: массив объектов с файлом, диапазоном строк, условием сбоя, последствием, способом воспроизведения и уровнем уверенности. Поле «предположение» нужно отдельно. Оно не превращается в комментарий без проверки.

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

Как не засорить pull request

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

  1. Модель формирует черновики замечаний и прикладывает фрагмент diff.

  2. Скрипт отбрасывает черновики без файла, строки или воспроизводимого условия.

  3. Второй проход модели пытается опровергнуть оставшиеся замечания по тому же контексту.

  4. Бот публикует только выводы, пережившие опровержение, остальные оставляет в сводке.

  5. Ревьюер решает, блокирует ли находка слияние.

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

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

Свяжите комментарий с CI

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

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

Повторные запросы к API тоже требуют дисциплины. При временной ошибке Relay ориентируйтесь на x-should-retry и Retry-After, а число повторов держите ограниченным. Правила описаны в документации по лимитам и справочнике ошибок. Бесконечный повтор в CI способен задержать очередь и съесть лимит ключа.

Что измерять после запуска

Первые две недели не пытайтесь оценить бота по числу комментариев. Полезнее собрать четыре показателя: долю замечаний, которые ревьюер подтвердил; долю отклонённых как шум; среднее время ответа; расход отдельного ключа на один pull request. В Relay детали вызовов ищутся по времени, ключу, модели и идентификатору запроса в журнале запросов.

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

Что делать с чувствительным контекстом

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

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

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

Как настроить первые правила

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

Потом проведите несколько pull request через закрытый режим. Бот формирует сводку, но не пишет в обсуждение. Ревьюер помечает находки как подтверждённые, шумные или недостаточно доказанные. Этот набор меток помогает поменять контекст и фильтры без давления на автора PR.

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

Сделайте договор с автором pull request

Автору нужно заранее знать, что бот будет смотреть и чего не сделает. Опишите это в шаблоне pull request: бот анализирует изменённые строки, не даёт архитектурных решений за пределами diff, не публикует замечание без условия сбоя. Такой договор убирает ожидание, что автоматизация «поймает всё».

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

Должен ли бот блокировать слияние pull request?

Нет. Блокировать слияние могут проверка, правило репозитория или ревьюер. Бот даёт аргумент для проверки, а не вердикт. Для простого детерминированного правила лучше написать отдельную проверку без модели: её результат проще воспроизвести и объяснить автору изменения.

Как узнать, какой запрос сделал комментарий?

Сохраняйте идентификатор запроса в логе джоба и рядом с черновиком замечания. В кабинете Relay запись находится по идентификатору запроса и времени. Полный ключ для диагностики не нужен, а в комментарий pull request стоит вынести только ссылку на job.

Нужно ли отправлять модели весь репозиторий?

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

Создать аккаунт для автоматизации

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.