Amiga
Оглавление курса · урок 9 из 17

Модуль 2 · Качество · урок 9 из 17

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

/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. Запуск. Изменения, которые видит пользователь, посмотрите сами. За пять минут на стенде или эмуляторе находится то, чего в диффе не видно.

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

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

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

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

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

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

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

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

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

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

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

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

Из этого следует несколько практических вещей:

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

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

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

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

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

Попробуйте сами

10–15 мин на рабочем месте
  1. Возьмите последний MR, написанный с помощью агента, и пройдите его в порядке из урока: задача → файлы → тесты → реализация → запуск. Запишите, что нашли на каждом шаге.
  2. Попросите агента провести вас по изменениям ветки в логическом порядке и назвать самые рискованные места. Сравните с вашим списком.
  3. Выберите замечание, которое вы писали больше одного раза, и превратите его в правило в AGENTS.md или в проверку в CI.

Коротко

  • Код агента выглядит гладко, поэтому ищите проблемы целенаправленно: не та задача, велосипеды, выдуманные API, проглоченные ошибки, пустые тесты, безопасность.
  • Порядок чтения: задача → список файлов → тесты → реализация → запуск.
  • Автора-агента можно и нужно расспрашивать: проход по изменениям, риски, непокрытые случаи.
  • MR должен читаться за один подход, механические изменения идут отдельно от логических.
  • Чистое ревью от модели остаётся одним слоем защиты, одобряет человек.
  • Повторяющиеся замечания записывайте в AGENTS.md, а то, что проверяется механически, отдавайте CI.
Отметка хранится только в вашем браузере
Хотите связаться с владельцем
компании напрямую?
Дмитрий Тарасов
Дмитрий Тарасов
СЕО

НАПИСАТЬ

Написать в MAX