Проверка кода с ИИ начинается до этапа pull request

Почему боль ревью начинается раньше

Большая часть проблем с ревью начинается до того, как кто‑то откроет pull request. Всё начинается с расплывчатой подсказки вроде «добавить поиск пользователей» или «почистить биллинг». Модель заполняет пробелы сама — и именно здесь начинается повторная доработка.

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

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

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

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

Маленькие стартапы особенно чувствуют это. Когда один старший инженер или fractional CTO держит большинство стандартов, каждая слабая подсказка превращается в новый раунд избежатьable комментариев. Потраченные десять минут на уточнение запроса могут сэкономить час на уборке ревью и переписке.

Что должна включать подсказка

Запрос на программирование нуждается в большем, чем просто описание фичи. Если оставить пробелы, модель заполнит их привычками из какого‑то другого репо. Именно поэтому качество ревью часто начинается с качества подсказки, а не с комментариев в pull request.

Начните с области изменения. Назовите точные папки, файлы и модули, которые разрешено менять. Если модель должна править только src/billing/* и tests/billing/*, скажите это. Если shared/ трогать нельзя — укажите это тоже. Маленькие границы экономят время, потому что модель перестаёт делать несвязанные правки, которые ревьюерам потом приходится откатывать.

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

Полезно также указать то, чего репо не должно использовать. Старые библиотеки, функции-хелперы, которые вы собираетесь убрать, и паттерны, от которых команда уже отказалась, часто вновь всплывают в сгенерированном коде. Короткий «банд‑лист» предотвращает много повторной доработки.

Держите в каждой подсказке четыре вещи:

• какие файлы и папки может трогать задача
• какие правила нейминга, структуры и стиля приняты в репо
• какие библиотеки, хелперы и паттерны модель должна избегать
• что значит «готово» до начала написания кода

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

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

Установите границы задачи до кодирования

Большинство громоздких pull request начинаются с слишком широкой задачи. Если вы просите модель «улучшить поток аутентификации», она может затронуть API‑хендлеры, сессии, UI‑тексты и логирование в одном заходе. Ревьюеры потом тратят время на отделение реального изменения от побочных правок.

Дайте модели одну задачу: одну фичу, один баг или один рефактор. Сначала это может показаться медленнее, но ревью становится чище. Малый объём даёт ревьюеру простой вопрос: сделал ли этот дифф то единственное, что мы просили?

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

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

Это убирает распространённую боль ревью. Ревьюер может одобрить фикc за пять минут, а затем потратить двадцать на поиск переименованного метода, перемещённого файла и тихой правки конфига, о которой никто не просил.

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

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

Держите границу видимой в подсказке:

• один конкретный результат
• разрешённая область правок
• зона, которую трогать нельзя
• правило «остановись и спроси»

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

Задайте ожидания по тестам заранее

Большая часть шума в ревью, связанная с тестами, не имеет отношения к уровню навыков. Шум возникает потому, что подсказка никогда не говорила, какие доказательства нужны. Модель пишет код, пропускает тесты или добавляет не те тесты, и pull request превращается в очистку.

Лучше заранее назвать тесты в подсказке. Это даёт модели финишную линию. Также ревью ускоряется, так как ревьюер может проверить, выполнило ли изменение понятный план тестирования, вместо того чтобы гадать, что значит «готово».

Будьте конкретны с тестами

Просите точные тесты для добавления или обновления. Используйте реальные имена, когда можете. «Обновить unit‑тесты сервиса аутентификации» лучше, чем «добавить тесты». «Добавить интеграционный тест на таймаут при оплате» ещё лучше.

Уточните, когда годится unit‑тест, а когда — интеграционный. Unit‑тесты подходят для маленьких изменений логики внутри функции, класса или модуля. Интеграционные тесты нужны, когда изменение касается базы данных, внешнего API, очереди, файлового хранилища или любого взаимодействия между системами.

Не останавливайтесь на «добавить покрытие». Попросите, по крайней мере, один тест на основной путь, один тест на путь ошибки, команду для запуска тестов и ожидаемый результат после выполнения.

Этот последний пункт важнее, чем многие думают. Если подсказка требует команду для запуска и ожидаемый результат, модель с меньшей вероятностью отдаст непроверенный код. Простая строка вроде "Run pytest tests/payments/test_retry.py and expect all tests to pass" убирает много переписки.

В маленьком стартапе это легко представить. Задача: добавить логику повторной отправки вебхуков при ошибке. Unit‑тест должен проверить, что счётчик повторов увеличивается и останавливается на заданном лимите. Интеграционный тест должен убедиться, что приложение реально повторяет отправку при провале и корректно логирует ошибку. Один путь ошибки может покрывать некорректный ответ от удалённого сервиса.

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

Пишите подсказку из пяти частей

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

1. Начните с проблемы пользователя в одном предложении. Держите её конкретной. Например: пользователи теряют черновики комментариев после таймаута и должны их получать обратно без изменения ощущения редактора.
2. Добавьте правила репо, вытащенные из реального кода. Укажите паттерны, которые уже используются в репо: тонкие хендлеры, типизированные ошибки, текущий стиль нейминга и как называются тесты. Короткий пример из существующего кода помогает больше, чем общее правило.
3. Определите область и запретные зоны. Скажите, что модель может трогать, что оставлять нетронутым и какие крайние случаи покрыть. Если задача про восстановление черновиков, укажите не менять поток аутентификации, биллинг или несвязанный UI.
4. Перечислите работу по тестам и критерии приёмки. Назовите ожидаемые тесты, поведение, которое не должно меняться, и кейсы отказа, которые должны проходить. Если изменение требует одного unit‑теста и одного интеграционного — скажите это заранее.
5. Попросите короткий план до написания кода. Достаточно плана в 4–5 шагов. Он должен включать открытые вопросы, вероятные файлы или модули для правки и возможные конфликты с правилами репо.

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

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

Простой пример из стартап‑репо

Маленькая команда хочет одно изменение в логине: при вводе неверного пароля сообщение должно быть понятнее и менее «холодным». В прошлый раз, когда попросили модель «улучшить UX логина», она переписала полформы, переименовала поля, сменила копирайт кнопок и затронула логику аутентификации, чего никто не просил. Pull request выглядел загруженным, но большая часть правок была уборкой для ревьюера.

Более строгая подсказка меняет это.

Task: improve login error messages for failed sign-in.

Edit only:
- the web login form component
- the login API handler
- tests related to failed login states

Do not change:
- field names
- success flow
- copy style used in the rest of the app
- validation rules
- routing or session handling

Use the current tone of the product. Keep messages short and plain.
Add or update tests for wrong password, unknown email, and locked account.
If you find a larger auth issue, leave a comment in the code and do not expand the scope.

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

Ревьюер теперь получает маленький pull request: один изменённый компонент формы, один API‑хендлер и связанные тесты. За несколько минут можно посмотреть дифф и сосредоточиться на том, подходят ли новые сообщения, а не на том, зачем модель переименовала email в username.

Здесь ревью становится проще. Модель всё ещё пишет код, но подсказка блокирует обычный беспорядок до начала работы. Малый объём, фиксированные имена и четкие правила тестирования лучше, чем ревью неожиданной переписи.

Ошибки, которые создают ту же уборку

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

Где подсказки ошибаются

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

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

Тесты создают ту же проблему. «Добавь тесты» звучит понятно, но не ясно. Модель может добавить только счастливый путь и посчитать задачу выполненной. Ревью становится легче, когда подсказка объясняет, что значит достойное покрытие: некорректный ввод, один путь ошибки и отсутствие новых сетевых вызовов.

Много шумных pull request приходит от тихих переписей рядом с целевым кодом. Модель меняет имена, комментарии или форматирование в смежных файлах. Эти правки делают дифф громоздким и прячут то единственное изменение, которое нужно проверить.

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

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

Быстрая проверка перед открытием pull request

Большинство pull request нуждаются не в долгих обсуждениях, а в быстром «smell test». Если изменение нарушает правила подсказки, ревьюер должен заметить это до чтения каждой строки.

Используйте короткую пред‑PR проверку:

• Сравните изменённые файлы с задачей. Если в подсказке было указано одно сервисное и одно тестовое дерево, дифф должен оставаться в этих границах. Дополнительные файлы часто означают, что модель вышла за рамки.
• Просканируйте имена, комментарии и паттерны кода. Новый код должен выглядеть как часть репо, а не как вставка из другого проекта с другими привычками.
• Раннее проверьте тесты. Если задача меняет поведение, автор должен добавить или обновить ожидаемые тесты. Отсутствие тестов чаще всего означает, что подсказка была расплывчатой или игнорированной.
• Читайте задачу и дифф вместе. Изменение должно решать заявленную проблему и останавливаться на этом. Маленькие бонусные правки часто создают больше работы, чем экономят.
• Дайте себе две минуты. Если вы всё ещё не можете объяснить, что поменялось, зачем и как это было протестировано, pull request не готов.

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

Простой пример из стартапа показывает это ясно. Если задача «обновить валидацию при регистрации и добавить тесты», а в PR ещё переписаны общие утилиты и переименованы поля формы, ревью сразу замедляется. Дополнительная уборка не относится к задаче, но кто‑то всё равно должен её проверить.

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

Лучшие pull request выглядят почти скучными. Они остаются в рамках, соответствуют репо, включают ожидаемые тесты и понятны при беглом просмотре.

Что делать команде дальше

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

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

Хороший командный шаблон обычно состоит из четырёх коротких частей:

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

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

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

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

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

Если вашей команде нужна помощь в настройке — внешний консультант ускорит процесс. Oleg Sotnikov делает практическую работу в роли Fractional CTO и советника для стартапов, фокусируясь на правилах репо, привычках тестирования и бережной AI‑первой разработке. More of that work is outlined on oleg.is.