Ревью сгенерированного кода: признаки, которые вредят поддержке

Почему аккуратно выглядящий код всё ещё создаёт работу

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

Разрыв проявляется сначала в мелочах. В промпте просят новое правило ценообразования, и модель добавляет его в API‑хэндлер, фоновой джоб и билдер текста для письма. Каждое изменение выглядит разумно само по себе. Дифф остаётся маленьким. Одобрение кажется лёгким. Но одно правило теперь живёт в нескольких местах, и следующее изменение продукта требует трёх правок вместо одной.

Имена причиняют более тихий вред. Сгенерированный код часто использует слова, которые звучат понятно, но почти ничего не говорят, например processPlan, status, data или result. Ревьюер читает мимо и предполагает, что они соответствуют бизнес‑идее. Часто это не так. Status может значить состояние пробного периода, состояние платежа или доступ к аккаунту. Это разные вещи. Когда имя скрывает реальное значение, последующие правки начинают расходиться.

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

Маленький стартап может столкнуться с этим за неделю. Команда просит ИИ добавить лимит мест для новых аккаунтов. Код проверяет users > 5 в одном сервисе, повторяет это в сообщении UI и использует то же число в экспорте отчёта. Сегодня это работает. В следующем месяце один клиент получает 10 мест, другой — 25, и команде приходится искать каждый тихий повтор 5.

Реальная стоимость редко в том, чтобы читать код сегодня. Она проявляется, когда кто‑то должен быстро изменить код и не может понять, какая аккуратно выглядящая строка скрывает реальное правило.

Где прячется дублирование

Сгенерированный код часто избегает явного copy‑paste. Он перефразирует одну и ту же идею с небольшими поверхностными изменениями, поэтому файл выглядит новым, хотя логика повторяется.

Валидация — частый случай. Одна функция проверяет, что email присутствует и обрезан. Другая проверяет то же самое, но возвращает чуть отличное сообщение. Третья добавляет ещё одну проверку на null. Теперь у вас три места для обновления, когда правило меняется.

То же самое происходит в коде маппинга. Хэндлер превращает поля запроса во внутреннюю модель, сервис снова преобразует эту модель, а тесты вручную собирают мок‑версию. Каждый блок по отдельности выглядит безобидно. Вместе они создают дрейф. Одно поле переименовали в одном слое, другое оставило старый дефолт, и тест всё ещё проходит, потому что он скопировал старую форму.

Обработка ошибок — ещё один тихий источник дублирования. Сгенерированный код часто оборачивает похожие вызовы API копированными try‑catch блоками, повторяющимися сообщениями логов и слегка отличающимися значениями‑fallback. Это выглядит аккуратно, пока команде не нужно менять правила ретраев или добавить ещё одну проверку статуса.

Маленькая продуктовая команда может почувствовать это быстро. Представьте один endpoint для создания пользователей и другой для импорта из CSV. Оба очищают имена, нормализуют телефоны и мапят роли. Сгенерированный код может положить эти шаги в два файла, потому что промпты пришли из двух разных задач. Через шесть недель один путь принимает новую роль, а другой её отклоняет.

Небольшие различия, которые стоят времени

Когда два хелпера отличаются только одной веткой, сравните их рядом. Если оба парсят один и тот же ввод, форматируют один и тот же вывод или строят один и тот же пэйлоад, вероятно, вам нужен один общий путь с явной опцией вместо двух близнецов.

Задайте прямой вопрос во время ревью сгенерированного кода: если это правило изменится завтра, сколько файлов сломается? Если ответ больше одного для одного бизнес‑правила, дублирование уже есть, даже если код выглядит аккуратно.

Обычные места скрытия: блоки валидации с мелкими изменениями формулировки, маппинг запроса‑в‑модель, повторяющийся через хэндлеры и сервисы, значения по умолчанию, скопированные через несколько слоёв, и обработка ошибок вокруг похожих вызовов API. Ничего драматичного в PR это не выглядит. Позже это становится болезненно.

Имена, которые почти ничего не говорят

Сгенерированный код часто выглядит опрятным, потому что имена звучат аккуратно. В этом как раз и проблема. Ревьюер видит data, item, result или manager и получает ложное ощущение порядка, хотя эти слова почти ничего не говорят.

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

Хорошие имена функций говорят вам правило, а не только действие. validateUser() расплывчато. Проверяет ли он возраст, формат email, статус аккаунта или оплату? allowPasswordResetForVerifiedEmail() длиннее, но говорит правду. Обычно это экономит больше времени, чем короткое имя.

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

Широкие имена классов заслуживают особого подозрения. UserManager или OrderService часто превращаются в ящик для всякого. Класс начинается с обновлений аккаунта, затем собирает проверку биллинга, отправку писем, аудит‑логи и экспорт. Это не одна обязанность. Это четыре‑пять обязанностей под вежливым именем.

Когда имена остаются общими, сопровождение замедляется мелкими способами, которые суммируются. Ревью занимают больше времени. Баги проскальзывают, потому что люди догадываются, что означает переменная. Рефакторы кажутся рискованными, потому что никто не доверяет границам. Аккуратное форматирование не исправит это. Помогут ясные имена.

Если имя заставляет ревьюера спросить: "Что это значит здесь?", код ещё не готов.

Предположения, спрятанные в коде

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

Дефолты — частая проблема. Код может автоматически выбирать USD, monthly, Pro или 30‑дневную пробную версию, потому что это совпало с промптом или образцом данных. Это работает, пока команда не добавит годовую оплату, бесплатный тариф или клиента из Японии. Ревьюеры должны спросить, исходит ли каждый дефолт из реального бизнес‑правила или из примера, который был рядом.

Жёстко заданные лимиты наносят тот же вред. Ограничение загрузки файла в 10 МБ, размер страницы 50 или проверка "макс 3 участника команды" может выглядеть безобидно на старте. Если код и тесты не объясняют, почему это число существует, считайте его догадкой. Поместите лимит в конфиг, привяжите к плану или назовите константу так, чтобы было понятно, кто и почему это выбрал.

Логика дат, валют и локалей может оставаться неправильной месяцами, потому что код всё ещё выглядит аккуратно. Парсинг дат как MM/DD/YYYY, форматирование цен одной валютой или сравнение строк, как будто все пишут на английском, сломается позже и часто тихо. Небольшие продуктовые команды замечают это только после первого клиента за пределами их домашнего рынка.

Обработка ошибок часто выдаёт самые узкие предположения. Сгенерированные клиенты могут ожидать одну форму ответа API, например {"success":true,"data":...}, и считать всё остальное необычным. В реальных системах бывают таймауты, частичные поля, прокси‑страницы ошибок, ограничения по частоте и старые версии с другими именами полей.

Быстрая проверка помогает. Уточните, исходят ли дефолты от продуктовых правил или от примеров. Спросите, откуда взялось каждое числовое ограничение. Просканируйте код на предмет логики, завязанной на один регион для дат, времени, валют и текста. Затем измените форму ответа API в тесте и посмотрите, как код отреагирует.

Эта часть ревью почти не связана со стилем. Нажмите на предположения — и слабые места сопровождения обычно вскрываются быстро.

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

Сгенерированный код часто проходит быструю визуальную проверку, потому что форма знакома. Хорошее ревью сгенерированного кода начинается с сомнения. Опрятное форматирование и спокойные комментарии не доказывают, что логика останется легко изменяемой через шесть недель.

Фиксированный порядок ревью помогает. Он не даст стилю украсть ваше внимание, пока дублирование, неясный нейминг и скрытые предположения проскальзывают.

1. Прочитайте код один раз так, будто комментариев нет. Сгенерированные комментарии часто звучат уверенно, даже когда код делает немного иначе. Отслеживайте входы, ветвления, изменения состояния и выходы.
2. Отметьте каждую повторяющуюся ветку, запрос и проверку условия. Если вы видите одну и ту же проверку на null в четырёх местах или два SQL‑запроса, отличающиеся одним полем, будущие правки будут расходиться.
3. Переименуйте расплывчатые символы прежде чем судить логику. Имена вроде data, item, value, result или tmp заставляют ревьюера догадываться. Даже быстрая заметка о новом имени может обнаружить плохую логику.
4. Спросите, что должно оставаться правдой, чтобы код работал. Предполагает ли он, что записи приходят в порядке? Ожидает ли, что поле никогда не пустое? Полагается ли он на одну временную зону, одну валюту или одну форму ответа от другого сервиса?
5. Пройдитесь по одному грязному кейсу, а не по счастливому пути. Попробуйте дублирующее событие, отсутствующее поле или устаревшие кэшированные данные. Сгенерированный код обычно лучше всего выглядит на идеальном вводе и хуже всего — на реальном продакшн‑вводе.

Небольшая команда может легко пропустить это. Предположим, сгенерированный хэндлер обновляет заказ, шлёт письмо и пишет строчку аудита. Демо работает. Затем повтор пытается отправить то же событие дважды, и код создаёт два строки аудита, шлёт два письма и помечает заказ дважды с немного разными таймстемпами. Файл всё ещё выглядит аккуратно. Сопровождение ухудшается, потому что каждое исправление теперь зависит от угадывания первоначального намерения.

Этот порядок ревью прост, но он ловит большую часть проблем на раннем этапе. Он также делает обратную связь команды более конкретной. Вместо «это кажется не тем» ревьюер сможет указать на повторяющуюся проверку, неясное имя или предположение, которое падает на грязном кейсе.

Реалистичный пример от маленькой продуктовой команды

Команда из пяти человек добавляет простую задачу: пользователи с ролью billing_manager должны просматривать счета, но только для своего рабочего пространства. Один разработчик просит AI‑инструмент обновить логику прав и получает аккуратный результат за несколько минут.

Инструмент добавляет одно и то же правило в четырёх местах: API‑хэндлере, фронтенд‑гарде, фоновой задаче экспорта и в общей утилите. Каждое изменение выглядит опрятно. Имена тоже звучат разумно: canViewInvoices, hasInvoiceAccess, checkBillingRole, allowBillingUser.

На этом этапе ревью терпит фиаско. Каждый файл читается хорошо по‑отдельности, поэтому PR кажется безопасным. Никто не останавливается, чтобы спросить, почему одно правило теперь живёт в четырёх местах.

Команда одобряет. Тесты проходят. Поддержка молчит неделю.

Потом правило меняется. Биллинг‑менеджерам теперь надо смотреть счета по всем рабочим пространствам в их аккаунте, а не только по одному. Разработчик обновляет три копии правила и пропускает четвёртую в джобе экспорта.

Теперь баг выглядит случайным. Пользователь может открыть счета в приложении, но запланированные экспорты всё ещё падают с «access denied». Поддержка сообщает, что только некоторые клиенты видят проблему, и только ночью, когда запускается экспорт.

Худшая часть не в стиле кода. Худшая часть — следы сопровождения: четыре копии одного правила расходятся, неясные имена скрывают небольшие различия, одно старое предположение остаётся в менее заметном пути, и ревьюеры помнят аккуратный PR и думают, что баг где‑то ещё.

Внимательный ревьюер задал бы два простых вопроса: почему это правило появилось в четырёх файлах и кто владеет решением?

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

Ошибки, которые делают ревьюеры, когда код выглядит аккуратно

Красивая табуляция, небольшие функции и аккуратные импорты могут обмануть. Ревью сгенерированного кода обычно терпит неудачу, когда ревьюер предполагает, что чистое форматирование значит понятный дизайн.

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

Ревьюеры порой тратят слишком много времени на синтаксис и слишком мало — на смысл. Они проверяют типы, lint и компиляцию, но пропускают, что поле status смешивает состояние платежа, доставки и утверждения пользователя в одно значение. Код читается нормально. Бизнес‑логика — нет.

Этот разрыв особенно важен в бизнес‑логике. Если флоу оформления заказа, шаг утверждения или правило биллинга читаются как обобщённая обработка данных, кто‑то сломает его позже, потому что имена никогда не сказали, для чего правило.

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

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

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

Команды, которые двигаются быстро, часто видят это: аккуратный PR одобрили, затем поддержка находит крайние случаи через неделю. Ревьюер не пропустил синтаксис. Он пропустил предположения.

Хорошее ревью — это тянуть за эти предположения, пока код не объяснит себя или не сломается на простых вопросах.

Быстрые проверки перед одобрением

Небольшой дифф всё ещё может породить недели дополнительной работы. Прежде чем одобрить сгенерированный код, задайте простой вопрос: будет ли следующее изменение в одном месте или кто‑то будет править одно и то же правило в трёх файлах и надеяться, что нашёл все?

Это часто самый быстрый тест в ревью сгенерированного кода. Аккуратность форматирования мало что значит, если логика скопирована, имена сливаются или тихий дефолт меняет поведение при странном вводе.

Несколько проверок ловят большую часть проблем:

• Убедитесь, что одно бизнес‑правило живёт в одном понятном месте.
• Прочитайте имена вслух. data, item, result или handleInput обычно скрывают смысл вместо того, чтобы его давать.
• Испытайте неудобный, но допустимый ввод. Пустая строка, неизвестный статус или отсутствующее поле часто выявляют дефолт, который никто не собирался выпускать.
• Проверьте, сможете ли вы объяснить правило, не открывая половину проекта. Если ответ лежит по компоненту, утилите, файлу конфигурации и тесту — код распылён.
• Предпочитайте два упрямых теста пяти простых. Один грязный кейс и один явно неверный говорят больше, чем куча счастливых путей.

Маленькие команды быстро вместе с этим сталкиваются. Ревьюер видит аккуратный PR по обработке заказа и нажимает approve. Позже поддержка сообщает, что отменённые заказы иногда становятся completed, потому что один хелпер использовал запасной статус, о котором другой файл не знал. Код выглядел спокойно. Поведение — нет.

Имена в сгенерированном коде заслуживают повышенного внимания. Если коллега не понимает, меняет ли process, normalize или prepare данные, валидирует их или просто перемещает, он откроет три файла перед тем как что‑то править. Эти задержки суммируются.

Тесты должны также доказывать, что код намеренно отвергает плохой ввод. Happy‑path тесты дешёвы. Полезный тест показывает, что происходит, когда число отсутствует, значение приходит в неверной форме или следующий месяц появится новое значение enum.

Красивому коду слишком много приписывают. Ясные правила, прямые имена и пара упрямых тестов важнее аккуратного диффа.

Что делать дальше

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

Эти примеры дают ревьюерам конкретные вещи для проверки. Они также делают командные правила реальными, потому что каждое правило исходит из бага, медленного рефактора или непонятного запроса на изменение.

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

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

Отслеживайте то, что команда исправляет после мержа, а не только то, что ревьюеры ловят до одобрения. Запись в PR, метка в issue или общий документ — уже достаточно. Если вы снова и снова видите один и тот же класс правок, процесс ревью сгенерированного кода пропускает правило, ограничение для промпта или и то, и другое.

Здесь многие команды теряют время. Они исправляют одну и ту же проблему пять раз и не обновляют промпт или чеклист. Через месяц кодовая база всё ещё выглядит аккуратно снаружи и становится труднее для изменений.

Если ваша команда активно выпускает код с поддержкой ИИ, полезно привлечь кого‑то, кто уже выработал эти привычки. Oleg Sotnikov at oleg.is работает со стартапами и малыми командами над практиками AI‑first разработки, стандартами ревью и бережными техническими процессами. Иногда внешний взгляд — самый быстрый способ прекратить повторение одних и тех же исправлений.