Модуль 2 · Качество · урок 9 из 17
Как ревьюить код, написанный агентом
/review и облачный ревьюер ловят многое, но решение о мерже принимает человек. Код агента читается иначе, чем код коллеги: он аккуратно оформлен, выглядит уверенно, а ошибки в нём другого рода. Ниже о том, на что смотреть и как не превратиться в штамп, который одобряет всё зелёное.
Чем код агента отличается
Код начинающего коллеги обычно выдаёт себя: неровное оформление, странные имена, вопросы в описании MR. Код агента гладкий. Имена разумные, комментарии на месте, описание уверенное. Эта гладкость и опасна, потому что ревьюер расслабляется.
Вот что стоит искать целенаправленно.
- Решена не та задача или решена шире, чем просили: «заодно» переписан соседний модуль.
- Свой велосипед. Новый хелпер форматирования телефона, хотя в проекте уже есть
PhoneFormatter. Так код и начинает расползаться, об этом OpenAI пишет в статье о harness engineering. - Выдуманные API: метод, которого нет в вашей версии фреймворка, или несуществующая опция конфига. Тесты могут пройти, если этот путь ими не покрыт.
- Проглоченные ошибки. Пустой
catch,?? []или@перед вызовом, и баг становится невидимым. - Тесты, которые ничего не проверяют: подогнанные ожидания, тотальные моки, проверка внутренних вызовов вместо результата. Подробно об этом в уроке про TDD.
- Безопасность. Конкатенация в SQL,
|rawв Twig, mass assignment без$fillable, отсутствие проверки прав в AJAX-обработчике, секреты или персональные данные в логах. - Лишние изменения: обновлённый lock-файл, переформатированные файлы, удалённые «неиспользуемые» строки.
Порядок чтения
Хуже всего читать дифф сверху вниз, по алфавиту файлов. Лучше в таком порядке.
- Задача и описание MR. Что должно было измениться? Если описание писал агент, сверьте его с карточкой, а не с диффом: описание может уверенно рассказывать о том, чего в коде нет.
- Список файлов:
git diff --stat main. Не затронуто ли то, что трогать не следовало? Есть ли изменения вtests/, конфигах, миграциях, lock-файлах? - Тесты. Они служат спецификацией. Отражают ли они требования? Упадут ли, если откатить реализацию?
- Реализация. Теперь, когда намерение понятно, читайте код и ищите проблемы из списка выше.
- Запуск. Изменения, которые видит пользователь, посмотрите сами. За пять минут на стенде или эмуляторе находится то, чего в диффе не видно.
Допросите автора
Агенту-автору можно задавать вопросы сколько угодно и без всякой неловкости. Делайте это в сессии, где писался код, или в новой, на этой же ветке:
Проведи меня по изменениям в этой ветке в логическом порядке, а не
по файлам: что и зачем. Для каждого решения — какие были альтернативы
и почему выбрано это.Саймон Уиллисон в 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 мимо него не пройдёт. Как превращать повторяющиеся проблемы в механические проверки, рассказывает урок «Архитектура через инварианты».
Попробуйте сами
10–15 мин на рабочем месте- Возьмите последний MR, написанный с помощью агента, и пройдите его в порядке из урока: задача → файлы → тесты → реализация → запуск. Запишите, что нашли на каждом шаге.
- Попросите агента провести вас по изменениям ветки в логическом порядке и назвать самые рискованные места. Сравните с вашим списком.
- Выберите замечание, которое вы писали больше одного раза, и превратите его в правило в AGENTS.md или в проверку в CI.
Коротко
- Код агента выглядит гладко, поэтому ищите проблемы целенаправленно: не та задача, велосипеды, выдуманные API, проглоченные ошибки, пустые тесты, безопасность.
- Порядок чтения: задача → список файлов → тесты → реализация → запуск.
- Автора-агента можно и нужно расспрашивать: проход по изменениям, риски, непокрытые случаи.
- MR должен читаться за один подход, механические изменения идут отдельно от логических.
- Чистое ревью от модели остаётся одним слоем защиты, одобряет человек.
- Повторяющиеся замечания записывайте в AGENTS.md, а то, что проверяется механически, отдавайте CI.