MR от ИИ-агента: три правила
Какие рамки нужны агенту, чтобы его MR можно было прочитать и принять: границы задачи, нарезка до кода и ревью агентом перед MR. И что мы ввели в команде сразу.
Агент ускоряет одного, а тормозит остальных: автор пишет код быстрее, чем команда успевает его прочитать.
Как это выглядит
Симптомы повторяются:
- MR огромные: автор принимает любые правки агента, даже не по задаче;
- описание не спасает: агент пишет неплохо, но текста много и он оторван от задачи;
- автор не читает: результат агента сразу уходит в MR;
- ревью встаёт.
Диагноз: проблема не в агенте, а в том, что у него нет рамок. Нет ни границ задачи, ни приёмки до MR.
Ответственность за MR при этом на разработчике. Отговорка «мало ли что написал ИИ» не принимается.
Правило 1: строго по задаче
Агент работает строго по постановке и только над ней. Что бы агент ни предлагал «заодно поправить», в этом MR не делаем. Замеченную проблему агент описывает в отчёте отдельным пунктом, а человек заводит отдельную задачу в бэклог. Рефакторинг решаем на груминге, а не молча в MR.
Почему это критично. На высоком уровне рассуждений агент начинает «улучшать» весь код вокруг. Лечится двумя строками в файле инструкций агента в репозитории (AGENTS.md или CLAUDE.md): работай только над задачей, ключ которой в имени ветки; изменения вне задачи не делай, а опиши в отчёте.
Человек на ревью делает то же самое: комментирует и лишнее, и недоделанное.
Правило 2: задача маленькая ещё до кода
Сырая постановка идёт не сразу в код. Сначала разработчик просит агента разбить её на минимальные задачи: одна задача -- одно поведение. Задачи заводятся в трекере, и на каждую -- свой маленький MR.
Агент позволяет сделать гораздо больше за одну задачу. Для систем в проде это риск, поэтому задачу формулируют жёстче и уже. И MR должен быть читаем для коллеги, который сам с агентом не работает.
Правило 3: до MR ревьюит агент, отчёт читает человек
Перед MR агент в отдельной сессии проверяет ветку:
- Ребейз на основную ветку и дифф.
- Текст задачи из трекера по ключу из имени ветки.
- Три направления ревью параллельно, только чтение.
- Находки в две категории: важные и мелкие.
- Все важные исправляются, мелкие -- по решению автора.
- Локально прогоняется быстрый набор тестов.
- Отчёт и MR создаются только по явному «да» автора.
Цикл повторяется, пока остаются важные находки: правки сами порождают находки.
Три направления ревью:
- архитектура: сверка с документами о сервисе и проход по пути вызова;
- релевантность в обе стороны: каждый критерий задачи закрыт, и всё сверх задачи считается находкой;
- тесты: на каждый изменённый путь есть тест, который его реально исполняет.
В описании MR обязателен раздел «Ревью агентом»: дата прогона и база, итог по находкам, команда тестов и результат, ссылка на полный отчёт. MR, написанный с агентом, без этого раздела уходит на доработку.
Документы, которые читают и люди, и агенты
В каждом репозитории три опоры. REVIEW.md -- что здесь важно и что проверять всегда. architecture.md -- как устроен сервис, границы ответственности, известные дефекты. Файл инструкций агента -- как ему работать в этом репозитории.
Правила для них простые: сервисное «важное» пишется один раз в REVIEW.md, остальное ссылается на него. Изменение, которое делает документ неверным, правит документ в том же MR. Первичное заполнение тоже можно поручить агенту: он проходит по сервису и описывает его по скелету.
Что делаем сразу
Рамки задачи в инструкциях агента и нарезка задач до старта разработки ничего не стоят, их делаем сразу. Документы и pre-MR ревью -- пилот на одном сервисе. Итоги пилота подводим на ретро, и этот пост я после него дополню.
Сначала рамки, потом агент