Как ревьюить код агента: шесть проверок до слияния
Ревью AI-кода начинается с того же вопроса, что и ревью любого другого изменения: что именно меняется для пользователя и где это доказано? У агента есть особенность, он способен написать связное объяснение даже там, где тест не запускался, а контракт не прочитан. Поэтому доверяйте трассе проверки, а не тону отчёта.
Коротко
Сначала сопоставьте diff с задачей и публичными границами модуля.
Затем ищите удаление, повторы и поведение при ошибке.
Последним читайте объяснение агента. Оно помогает найти место, но не служит доказательством.
С чего начать ревью кода агента?
Первая проверка, граница задачи. Агенту легко поправить соседний файл «заодно», переименовать общий helper или обновить конфигурацию, которую задача не затрагивает. Пройдите по списку файлов и спросите, зачем каждый нужен. Неясный файл не означает ошибку, но требует объяснения в коде или в задаче.
Вторая проверка, опасное действие. Ищите удаление данных, отправку во внешний сервис, изменение прав доступа, платежа, миграцию и повторяемый job. В этих местах агент нередко выбирает короткую ветку, которая работает на счастливом пути. Сымитируйте повторный вызов, отмену, пустое значение или чужую учётную запись.
Третья проверка, падающий тест. Спросите не «есть ли тест», а «какой неверный вариант он ловит». Тест, написанный после правки, может повторять ту же ошибочную гипотезу. Полезно временно поменять условие в коде на неправильное и убедиться, что тест краснеет.
Четвёртая проверка, уверенный тон. Фраза «обрабатывает все случаи» ничего не значит без списка случаев. Сверьте каждый такой вывод с веткой кода, журналом запуска или контрактом. Слова «безопасно», «всегда» и «готово» заслуживают лишней минуты внимания.
Пятая проверка, размер изменения. Маленькая задача с большим diff часто означает, что агент потянул зависимость, форматирование или чужую незавершённую правку. Большая задача с крошечным diff тоже подозрительна: возможно, не изменён главный путь.
Шестая проверка, обратимость. Перед слиянием должно быть ясно, как отключить новую ветку, вернуть конфигурацию или остановить фоновые вызовы. Для необратимой миграции нужен отдельный план отката, а не надежда на следующий pull request.
| Признак | Риск | Проверка |
|---|---|---|
| Агент поменял общий helper | Регрессия в другом модуле | Найти вызывающие места и запустить адресные сценарии |
| Тест повторяет код | Ошибка закрепляется вместе с тестом | Подменить условие на неверное и увидеть падение |
| Большой diff без связи с задачей | В работу попало чужое изменение | Разделить pull request или вернуть лишние файлы |
| Отчёт обещает безопасность | Не проверены права и ошибки | Прочитать проверки доступа и негативные ветки |
Как провести короткое ревью
Начните с описания задачи и diff. Затем откройте входной контракт: маршрут, интерфейс, схему события или команду CLI. После этого найдите выходное действие и посмотрите, что происходит при повторе и ошибке. Такой маршрут короче, чем линейное чтение всего файла, и быстрее выводит на реальный риск.
Если агент работал с API, проверьте ключи, таймауты и повтор. В Relay отдельный ключ может иметь срок, ограничения расхода и лимит запросов в минуту, детали доступны в кабинете ключей. Ошибки с повтором требуют отдельного решения: справочник ошибок советует ориентироваться на x-should-retry и учитывать Retry-After. Режимы работы с легаси и границы правок разобраны в статье о порядке работы с Claude Code.
Перед ревью запроса сверяйте его с публичным контрактом, а не с текстом агента. Для формата Chat Completions используйте спецификацию API, для другого протокола откройте соответствующий раздел документации.
Пишите замечание так, чтобы автор мог проверить его за один проход. Укажите условие, последствие и конкретное место. «При повторе после таймаута обработчик снова создаёт заказ; добавьте проверку по внешнему идентификатору и тест с повторным вызовом» лучше, чем «нужно улучшить идемпотентность».
Автогенерация хорошо ускоряет черновик. Ответственность за его границы остаётся у команды. Когда этот порядок войдёт в привычку, код агента перестанет быть отдельной категорией риска и станет обычным изменением с более тщательной проверкой происхождения.
Перед слиянием
Последний проход полезно сделать с чистым состоянием, без рассказа агента о проделанной работе. Откройте diff, условия задачи и тесты. Если смысл изменения нельзя восстановить из них, pull request ещё не готов к слиянию.
Особенно внимательно смотрите на правки, где агент одновременно меняет имя, логику и формат данных. Разделите такие изменения, если это возможно. Маленький diff легче проверить, легче откатить и проще обсудить без догадок о том, что автор хотел сделать заодно.
Если разделить работу уже нельзя, попросите автора явно обозначить части diff. Тогда ревью идёт по очереди: контракт, преобразование данных, побочное действие, тест. Такой маршрут снижает шанс, что одна длинная правка спрячется за общей фразой «рефакторинг».
Нужно ли ревьюить каждую строку AI-кода вручную?
Нет. Ищите точки, где изменение пересекает контракт, внешнее действие, данные или права. Затем проверьте тестами негативные пути. Линейное чтение полезно после этой карты, но не заменяет её. Такой порядок сокращает шанс потратить всё время на безопасные косметические строки.
Что делать, если агент написал тесты?
Читайте тесты как часть diff. Они должны падать при неверном поведении и покрывать риск, а не повторять формулировку реализации. Если сомневаетесь, внесите временную ошибку и проверьте реакцию теста. Отдельно посмотрите, не подменил ли тест внешний контракт удобным для реализации мок-объектом.
Нужно ли менять промпт после найденной ошибки?
Иногда достаточно теста, ограничения инструмента или ясной границы задачи. Промпт меняют, когда ошибка повторяется из-за недостающего контекста или правила. Зафиксируйте причину и сравните следующий запуск с прежним случаем, иначе изменение инструкции останется неподтверждённой догадкой.