Как ревьюить код, написанный агентом

/review и облачный ревьюер ловят многое, но решение о мерже принимает человек. Код агента читается иначе, чем код коллеги: он аккуратно оформлен и выглядит уверенно, а ошибки в нём другого рода. В уроке — на что смотреть и как не превратиться в штамп, который одобряет всё зелёное.

Чем код агента отличается

Код начинающего коллеги обычно выдаёт себя: неровное оформление, странные имена, вопросы в описании MR. Код агента гладкий: имена разумные, комментарии на месте, описание уверенное. Эта гладкость и опасна — она снижает внимание ревьюера.

Типичные проблемы, которые стоит искать целенаправленно:

• Решена не та задача — или решена шире, чем просили: «заодно» переписан соседний модуль.
• Свой велосипед. Новый хелпер форматирования телефона, хотя в проекте уже есть PhoneFormatter. Это прямой путь к дрейфу кода, о котором OpenAI пишет в статье о harness engineering.
• Выдуманные API. Метод, которого нет в вашей версии фреймворка, опция конфига, которой не существует. Тесты могут пройти, если этот путь ими не покрыт.
• Проглоченные ошибки. Пустой catch, ?? [] или @ перед вызовом — и баг становится невидимым.
• Тесты, которые ничего не проверяют. Подогнанные ожидания, тотальные моки, проверка внутренних вызовов вместо результата — подробно в уроке про TDD.
• Безопасность. Конкатенация в SQL, |raw в Twig, mass assignment без $fillable, нет проверки прав в AJAX-обработчике, секреты или персональные данные в логах.
• Лишние изменения. Обновлённый lock-файл, переформатированные файлы, удалённые «неиспользуемые» строки.

Порядок чтения

Читать дифф сверху вниз по алфавиту файлов — худший вариант. Лучше так:

1. Задача и описание MR. Что должно было измениться? Если описание писал агент, сверьте его с карточкой, а не с диффом: описание может уверенно рассказывать о том, чего в коде нет.
2. Список файлов. git diff --stat main. Затронуто ли то, что не должно? Есть ли изменения в tests/, конфигах, миграциях, lock-файлах?
3. Тесты. Они — спецификация. Отражают ли требования? Упадут ли, если откатить реализацию?
4. Реализация. Теперь, зная намерение, читайте код и ищите проблемы из списка выше.
5. Запуск. Для изменений, которые видит пользователь, посмотрите сами. Пять минут на стенде или эмуляторе находят то, что в диффе не видно.

Допросите автора

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

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

Такой последовательный проход по изменениям Саймон Уиллисон описывает в Agentic Engineering Patterns как отдельный приём (linear walkthrough). Ещё несколько полезных вопросов:

Какие места в этом диффе ты считаешь самыми рискованными?
Какие случаи не покрыты тестами?
Есть ли в проекте код, который уже делает то же самое?

Требуйте доказательств, а не уверенности: «покажи путь кода и тест для случая пустого списка; что покрыто, а что ещё нужно проверить». Похожий пример есть в документации Codex по ревью: просить показать код и тесты для конкретного случая и отдельно — что осталось непроверенным.

Размер имеет значение

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

• одна задача — один MR; попутные находки — отдельными задачами;
• механические изменения (переименование, форматирование, замена API по рецепту) — отдельным MR от логических, чтобы их можно было просмотреть быстро;
• крупная фича — серией MR, каждый с работающим состоянием.

Агенту такие требования выполнить легко — достаточно записать их в AGENTS.md.

Чистое ревью — не гарантия

Если /review или облачный ревьюер ничего не нашли, это не значит, что проблем нет. OpenAI в отчёте о масштабировании проверки кода прямо называет главный риск: команды начинают воспринимать чистое ревью от модели как гарантию безопасности, а не как один из слоёв защиты. И в документации Codex правила ревью сопровождаются оговоркой: они направляют ревьюера, но не заменяют тесты, защиту веток и обязательные одобрения.

Практические следствия:

• агент — дополнительный ревьюер, а не замена обязательного одобрения человеком;
• защита ветки main и обязательные одобрения в GitLab остаются как есть;
• автор MR — человек, который его открыл, и за код он отвечает так же, как за написанный руками.

Замечания — в правила

Если вы третий раз пишете одно и то же замечание к коду агента, проблема уже не в конкретном MR. Руководство OpenAI по лучшим практикам советует: когда Codex дважды повторяет ошибку, попросить его провести ретроспективу и обновить AGENTS.md.

На ревью дважды было одно замечание: ты пишешь свои хелперы вместо
существующих в app/Support/. Предложи короткое правило для AGENTS.md,
которое это предотвратит, и место, куда его поставить.

То, что можно проверить механически, лучше отдать линтеру или тесту: правило в AGENTS.md агент может упустить, упавший CI — нет. Как превращать повторяющиеся проблемы в механические проверки — в уроке «Архитектура через инварианты».