Правила ИИ‑кода для общих репозиториев, сохраняющие читабельность

Почему смешанный код быстро становится путаным

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

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

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

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

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

Выберите базовые правила сначала

Прежде чем кто‑то вставит промпт в инструмент программирования, команда должна решить, где AI может помогать, а где — нет. Это звучит строго, но экономит время.

Начните с границ файлов. Многие команды считают допустимым, чтобы AI черново писал тесты, небольшие UI‑части, внутренние инструменты и низкорисковые документы. Они блокируют его использование в миграциях баз данных, аутентификации, биллинге, секретах, файлах деплоя и везде, где одна ошибка в мердже может повредить данные или безопасность.

Достаточно короткого письменного набора правил:

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

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

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

То же и с документацией. Разрешите AI черново писать её, если хотите, но требуйте, чтобы человек переписал всё, что будет направлять будущую работу. Черновик — ок. Неопределённая страница, которой никто не доверяет — нет.

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

Установите правила именования, которым люди будут следовать

Если люди и AI пишут код в одном репо, дрейф имен распространяется быстро. В одном месте user_service.ts, в другом UserHelpers.ts, а в третьем — работа спрятана в misc.ts. Такой беспорядок замедляет ревью больше, чем команды ожидают.

Выберите один стиль для каждого уровня и запишите его. Имена файлов должны соответствовать нормам языка. Функции — глаголы. Переменные — простые существительные. Булевы — начинаются с is, has или can.

Коротким именам тоже нужны правила. id и url подходят, потому что все их понимают. cfg, tmp и proc обычно слишком неопределённы, если только область не крошечная и очевидная. Если новый сотрудник останавливается и начинает гадать — имя слишком короткое.

Избегайте остроумных имён. Шутки, внутренний жаргон и широкие корзины вроде utils, helpers, data или manager скрывают намерение. Хорошее имя подсказывает ревьюеру, что делает код, ещё до открытия файла. createInvoiceDraft, retryCount, isArchived и billing_report.ts — понятны. doStuff, x, flag и misc.ts — нет.

Если ваше репо охватывает разные языки, сохраняйте смысл неизменным, даже когда меняется стиль написания. TypeScript‑функция и Go‑функция могут следовать локальным конвенциям, но обе должны описывать одно и то же действие одними и теми же словами. Тогда у модели будет меньше шансов придумать новый шаблон именования.

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

Держите комментарии короткими и полезными

Большинство плохих комментариев стареет быстрее, чем код. Когда код уже говорит, что делает, комментарий должен не мешать. Строка, объясняющая price * quantity, ничего не добавляет. Строка, объясняющая, почему вы округляете перед сохранением или почему повторяете попытку только один раз, может предотвратить плохое изменение позже.

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

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

TODO и FIXME требуют небольшой дисциплины:

• TODO — для плановой работы с реальным владельцем.
• FIXME — для известной ошибки, рискованного упрощения или сломанного краевого случая.
• Добавляйте имя, команду или тег тикета.
• Убирайте заметки, которые никто не собирается делать.

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

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

Определите правила тестирования до мерджа

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

Имена тестов должны описывать поведение, а не внутренности. Название вроде "uses formatOrderDate" мало что говорит. "Показывает дату заказа в локальном времени на странице чекаута" — лучше, потому что любой в команде поймёт, что сломалось.

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

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

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

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

Один вопрос на ревью ловит много слабых PR до их мерджа: "Какое поведение изменилось и где это покрыто?"

Сделайте владение видимым

Ясное владение должно быть записано рядом с правилами репозитория, а не жить в чьей‑то голове. Смешанный человек‑модель вывод становится запутанным, когда никто не знает, кто принимает окончательное решение.

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

Простой подход работает хорошо:

• Дайте каждому сервису, пакету или папке именованного владельца.
• Отправляйте AI‑тяжёлые PR небольшой группе ревьюеров, которые умеют судить о сгенерированном коде.
• Когда код переходит к другой команде, требуйте короткой заметки о передаче и нового владельца.
• Записывайте, кто одобрил любое исключение из стиля.

Это особенно важно, когда сгенерированный код пересекает границы. Модель может переименовать файлы, перенести логику или добавить тесты в области, которые автор едва понимает. Если во время рефактора аутентификации меняется биллинг‑код, владелец биллинга должен это проверить, даже если PR начался в другом месте.

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

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

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

Используйте простой поток pull request'ов

Большинство проблем с ревью начинаются ещё до открытия PR. Если задача расплывчата, AI заполнит пробелы догадками, и ревьюеры потратят время на распутывание намерений вместо проверки кода.

Начните каждое изменение с короткой заметки о задаче и нескольких критериев приёмки. Держите их простыми: что должно измениться, что не должно и как понять, что работа завершена.

Поток не должен быть сложным. Определите маленький объём. Генерируйте или пишите код только для этой области. Почините неловкие имена и ненужные комментарии до ревью. Прогоните тесты. Уберите шумные diffs, например, не относящуюся к делу правку форматирования. Затем откройте PR с краткой заметкой о том, где AI помогал.

Это последнее важнее, чем кажется. Ревьюерам не нужен транскрипт. Им нужно короткое резюме: AI написал хендлер, предложил тест‑кейсы и переписал комментарии. Теперь они знают, где смотреть внимательнее.

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

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

Реалистичный пример из общего репозитория

Небольшая команда добавляет фичу: пользователи могут приостанавливать еженедельные напоминания по email на 7 дней. Sam пишет продуктовую заметку и крайние случаи сначала. Модель черново генерирует код, Sam редактирует его перед открытием PR.

В репо уже есть одно правило для этой области: каждый файл использует одно доменное имя invoiceReminder. Это делает фичу легкой для поиска. PR затрагивает invoiceReminderService.ts, useInvoiceReminder.ts, invoiceReminderService.test.ts и InvoiceReminderPanel.tsx.

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

Sam также держит комментарии короткими. Модель сначала добавила строки вроде "This function checks whether reminders should be sent." Ревьюер вырезает это и просит один полезный комментарий: почему сервис округляет окно паузы до полуночи. Эта заметка поможет следующему человеку. Пять очевидных комментариев — нет.

Владение убирает обычную задержку. Репо отмечает уведомления как зону ответственности Priya, поэтому запрос на ревью идёт прямо к ней, когда Sam открывает PR. Ей не нужно гадать, кто должен одобрить, и Sam не нужно отмечать троих человек на всякий случай.

Priya проверяет три вещи: совпадают ли имена со стилем репо, покрывают ли тесты паузу на 7 дней и краевые случаи, и объясняет ли один комментарий единственный неожиданный выбор.

Она одобряет после одного малого переименования. pauseUntil становится reminderPauseUntil, потому что это термин, который уже используется в репо. Эта маленькая правка — суть. Смешанный человек‑модель вывод остаётся читабельным, когда команда защищает небольшие правила каждый раз.

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

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

• Совпадают ли новые имена со стилем репо?
• Удалены ли комментарии, которые только повторяют код?
• Доказывают ли тесты изменившееся поведение?
• Указан ли владелец в описании PR?
• Дешевле ли переписать, чем делать ещё один проход ревью?

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

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

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

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

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

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

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

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

Следующие шаги для вашей команды

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

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

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

Потом опробуйте стандарт на двух‑трёх реальных PR. Не оценивайте его в теории. Один PR покажет шумные комментарии. Другой выявит, что правила по тестам слишком свободные или слишком жёсткие. Реальная работа быстро обнаружит слабые места.

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

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