Виталий СоколовСайт под управлением LLM с авторским контентом
блог / ии

MR от ИИ-агента: три правила

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

Виталий Соколовопубликовано 15 сентября 20263 мин чтения

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

Как это выглядит

Симптомы повторяются:

  • MR огромные: автор принимает любые правки агента, даже не по задаче;
  • описание не спасает: агент пишет неплохо, но текста много и он оторван от задачи;
  • автор не читает: результат агента сразу уходит в MR;
  • ревью встаёт.

Диагноз: проблема не в агенте, а в том, что у него нет рамок. Нет ни границ задачи, ни приёмки до MR.

Ответственность за MR при этом на разработчике. Отговорка «мало ли что написал ИИ» не принимается.

Правило 1: строго по задаче

Агент работает строго по постановке и только над ней. Что бы агент ни предлагал «заодно поправить», в этом MR не делаем. Замеченную проблему агент описывает в отчёте отдельным пунктом, а человек заводит отдельную задачу в бэклог. Рефакторинг решаем на груминге, а не молча в MR.

Почему это критично. На высоком уровне рассуждений агент начинает «улучшать» весь код вокруг. Лечится двумя строками в файле инструкций агента в репозитории (AGENTS.md или CLAUDE.md): работай только над задачей, ключ которой в имени ветки; изменения вне задачи не делай, а опиши в отчёте.

Человек на ревью делает то же самое: комментирует и лишнее, и недоделанное.

Правило 2: задача маленькая ещё до кода

Сырая постановка идёт не сразу в код. Сначала разработчик просит агента разбить её на минимальные задачи: одна задача -- одно поведение. Задачи заводятся в трекере, и на каждую -- свой маленький MR.

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

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

Правило 3: до MR ревьюит агент, отчёт читает человек

Перед MR агент в отдельной сессии проверяет ветку:

  1. Ребейз на основную ветку и дифф.
  2. Текст задачи из трекера по ключу из имени ветки.
  3. Три направления ревью параллельно, только чтение.
  4. Находки в две категории: важные и мелкие.
  5. Все важные исправляются, мелкие -- по решению автора.
  6. Локально прогоняется быстрый набор тестов.
  7. Отчёт и MR создаются только по явному «да» автора.

Цикл повторяется, пока остаются важные находки: правки сами порождают находки.

Три направления ревью:

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

В описании MR обязателен раздел «Ревью агентом»: дата прогона и база, итог по находкам, команда тестов и результат, ссылка на полный отчёт. MR, написанный с агентом, без этого раздела уходит на доработку.

Документы, которые читают и люди, и агенты

В каждом репозитории три опоры. REVIEW.md -- что здесь важно и что проверять всегда. architecture.md -- как устроен сервис, границы ответственности, известные дефекты. Файл инструкций агента -- как ему работать в этом репозитории.

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

Что делаем сразу

Рамки задачи в инструкциях агента и нарезка задач до старта разработки ничего не стоят, их делаем сразу. Документы и pre-MR ревью -- пилот на одном сервисе. Итоги пилота подводим на ретро, и этот пост я после него дополню.

Сначала рамки, потом агент

Ещё в блоге

Без ТЗ результат ХЗии, 2 минP85 вместо среднегосроки, 3 минМетрика без владельца: мусорметрики, 3 минПринёс новое: убери своёсроки, 2 мин