Чек-лист приёмки кода от агента: 24 пункта

Коротко

Код от нейросети проверяют не «на глаз», а по фиксированному списку — иначе взгляд соскальзывает. Такой код почти всегда синтаксически корректен, и это создаёт ложное чувство готовности: в замерах Veracode более 95% сгенерированного кода корректно по синтаксису, но 45% содержит известные уязвимости. «Запускается» — не критерий приёмки.

Рабочий минимум — 24 пункта в шести блоках: понимание диффа, зависимости, безопасность, поведение на краевых данных, тесты, эксплуатация. Опорные пункты: вы можете своими словами объяснить каждый изменённый файл; каждый новый пакет реально существует в реестре; в диффе нет секретов; пользовательский ввод не уходит напрямую в SQL, шелл или HTML; новый тест падает без правки и проходит с ней; есть способ откатить одной командой.

Проход занимает 10–20 минут на дифф до 300 строк. Больше — список не спасёт, режьте задачу на части. И отдельно: определить «написан ли код нейросетью» технически нельзя, детекторов для кода не существует. Проверять надо сам код.

Зачем это нужно

Три исследования объясняют, почему интуиция здесь подводит именно на коде от агента.

Сложите три факта. Код выглядит правильно, потому что синтаксис почти безупречен. Уязвимости распределены неравномерно: по данным того же отчёта Veracode, доля безопасных решений для Java — 29%, для Python — 62%, а хуже всего защита от XSS (15% проходов) и от инъекций в лог (13%). И собственное ощущение «я быстро глянул, всё нормально» откалибровано неверно — METR показал разрыв между воспринимаемой и реальной скоростью в 39 процентных пунктов.

Отсюда формат. Не «внимательно посмотреть», а список, по которому проходят подряд, потому что внимание к концу диффа заканчивается, а список — нет.

Готовый чек-лист целиком

Скопируйте в шаблон пул-реквеста или распечатайте. Порядок блоков не случайный: он идёт от дешёвых проверок к дорогим.

Понимание изменений

• Могу объяснить своими словами, что делает каждый изменённый файл.
• Знаю, зачем добавлена каждая новая зависимость.
• В диффе нет файлов, которых я не просил трогать.
• Объём диффа соответствует задаче — нет «заодно отрефакторил».

Зависимости

• Каждый новый пакет действительно существует в реестре, у него живой репозиторий и внятная история релизов.
• Имя пакета совпадает с официальным символ в символ.
• Версии зафиксированы, lock-файл пересобран и попал в дифф.
• Ни одна библиотека не добавлена «на будущее».

Безопасность

• В диффе нет ключей, токенов, паролей и файлов .env.
• Пользовательский ввод не попадает напрямую в SQL, шелл-команду или HTML.
• В логи не пишутся сырой пользовательский ввод и персональные данные.
• Проверка прав есть на сервере, а не только в интерфейсе.

Поведение и данные

• Обработаны пустой ввод, ноль элементов и отказ внешнего сервиса.
• Ничего не удаляется и не перезаписывается без явной необходимости; миграция обратима.
• У каждого внешнего вызова есть таймаут и предел повторов.
• Деньги, даты, часовые пояса и кодировки проверены руками на реальном примере.

Тесты

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

Эксплуатация

• Есть способ откатить изменение одной командой.
• Понятно, по какому логу или метрике я узнаю, что оно сломалось в проде.
• Изменения конфигов, прав и переменных окружения перечислены в описании PR.
• Сообщение коммита объясняет «почему», а не пересказывает дифф.

Разбор по частям: что здесь неочевидно

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

Блок зависимостей — самый недооценённый. Выдуманный пакет — не абстрактный риск. Атака «slopsquatting» строится ровно на том, что модели устойчиво предлагают одни и те же несуществующие имена, а злоумышленник регистрирует их в npm или PyPI заранее. Самый опасный подвид — не опечатка, а склейка двух настоящих названий: такое имя выглядит абсолютно правдоподобно. Проверка простая — открыть страницу пакета в реестре и посмотреть дату первого релиза и количество загрузок.

Блок безопасности сокращён до четырёх пунктов намеренно. Полный аудит по OWASP Top 10 на каждом PR никто делать не будет. В список вынесены категории, где модели проваливаются чаще всего по замерам: экранирование вывода, инъекции в лог, инъекции в SQL и шелл. Про секреты и токены отдельно: как их правильно хранить и что делать, если ключ уже утёк в историю git, разобрано в материале про API-ключи и секреты.

Пункт 17 — единственный, который нельзя пропустить. Тест, написанный агентом, часто зелёный с самого начала и был бы зелёным при любой реализации. Проверка одна: откатите правку, запустите тест, убедитесь, что он покраснел. Без этого шага тесты дают только иллюзию покрытия. Подробнее про то, как заставить агента проверять себя и где эта самопроверка не работает, — в ревью и тестах: самопроверке.

Российский контекст в двух пунктах. Первый — логи: 152-ФЗ распространяется и на них, а модель по умолчанию охотно пишет в лог весь входящий объект вместе с телефонами и адресами. Второй — сам процесс ревью. Если вы прогоняете дифф через облачную модель, фрагменты кода уезжают за периметр вместе со всем, что в них попало: строками подключения, тестовыми персданными, внутренними доменами. Для кода, который этого не переживёт, ревью делают локально или на своём контуре — что для этого нужно, разобрано в рисках и безопасности вайб-кодинга.

Чего в этот список класть не надо

Стиль и форматирование. Отступы, порядок импортов, длина строк — работа линтера и форматтера в CI. Каждый такой пункт в ручном списке крадёт внимание у пунктов, которые машина проверить не может.

«Проверить, не ИИ ли это написал». Запрос популярный, ответ неприятный: детекторов ИИ для кода не существует. Синтаксис языка программирования жёстко ограничен, «стилистических отпечатков» в нём на порядок меньше, чем в тексте, а любой форматтер стирает и их. Любой сервис, который обещает такую проверку по коду, гадает. Проверяйте свойства кода, а не его происхождение.

Стопроцентное покрытие тестами. Метрика легко накручивается тестами, которые ничего не утверждают, — и агенты накручивают её отлично. Пункт 17 полезнее любого процента.

Производительность и микрооптимизации. Кроме случаев, когда задача изначально про производительность. Иначе это ветка обсуждения на полчаса при нулевом измеренном эффекте.

Архитектурные споры. Если код нарушает архитектуру проекта, чинить надо не приёмку, а файл с правилами, который агент читает перед работой.

Как поддерживать список в актуальном виде

Правило одно: список не растёт. У него фиксированный размер, и новый пункт въезжает только вместо старого.

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

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

Честное ограничение: 24 пункта не работают на диффе в тысячу строк. Не потому что список плох, а потому что на таком объёме человек физически не удержит контекст. Если приёмка регулярно упирается в размер — проблема в постановке задач агенту, и чинить надо там.

Частые вопросы

Сколько времени реально занимает проход по 24 пунктам?

10–20 минут на дифф до 300 строк, если проект знакомый. Первые несколько раз — вдвое дольше, пока не запомнится порядок. Блоки «понимание» и «зависимости» занимают минуты две; основное время съедают тесты и ручной прогон сценария. Если проход стабильно занимает больше сорока минут, это сигнал не про список, а про размер задач.

Можно ли поручить проверку по чек-листу самому агенту?

Частично. Механические пункты — секреты в диффе, существование пакетов, наличие таймаутов, обратимость миграции — агент проверяет хорошо и быстро. Но проверяющий агент не должен быть тем же экземпляром, который писал код в том же контексте: он уже «согласен» со своим решением. Запускайте отдельную сессию с чистым контекстом, дайте ей только дифф и список. Пункты про понимание и про то, откатывается ли изменение в вашей инфраструктуре, остаются за человеком.

Что делать, если в проекте нет тестов вообще?

Блок «Тесты» тогда не выполним целиком, и это надо признать честно, а не имитировать. Замена на переходный период: ручной прогон основного сценария до и после правки плюс усиленный блок эксплуатации — откат одной командой и понятная метрика поломки. Параллельно просите агента писать тест на тот код, который он трогает, а не на весь проект. Через десяток PR блок начнёт работать сам.

Помогает ли этот список против уязвимостей из отчётов Veracode?

Против четырёх категорий, которые там измеряют, — да, потому что пункты писались под них. Против всего остального — нет, и не должен. Список приёмки закрывает регулярный поток изменений, а не заменяет аудит безопасности. Если вы работаете с платежами, медицинскими или персональными данными, отдельный внешний аудит нужен независимо от того, кто писал код — человек или агент.

Чем приёмка кода от агента отличается от обычного код-ревью?

Смещёнными акцентами. В обычном ревью предполагается, что автор понимал, что пишет. С агентом добавляются проверки, которые человеку были бы оскорбительны: существует ли импортированный пакет, не влез ли он в чужие файлы, ловит ли тест хоть что-нибудь. Зато теряет смысл обсуждение стиля — его дешевле закрыть автоматикой.