Использование комментариев ревью для улучшения промптов при генерации кода

Почему одни и те же замечания возвращаются\n\nПовторяющиеся замечания в ревью обычно указывают на разрыв в ожиданиях, а не на единичные ошибки в коде. Сгенерированный AI-код часто выглядит приемлемо на первый взгляд, но не соблюдает привычки вашей команды: нейминг, покрытие тестами, обработку ошибок, границы файлов или то, где должен располагаться определённый кусок логики.\n\nИменно поэтому одни и те же замечания появляются в разных pull request'ах. В одном PR пишут «добавьте тесты на случаи ошибок». В другом — «разбейте этот файл». В третьем — «не выносите вызовы базы данных в контроллер». Файлы разные, но правило за комментарием одно и то же. Если никто не превратит это правило в ограничение промпта, ревьюеры будут снова и снова объяснять одно и то же.\n\nСтоимость скрыта в мелких правках. Две минуты на нейминг. Пять — на логирование. Десять — чтобы перенести логику в нужный слой. На загруженной команде эти минуты быстро накапливаются.\n\nОбщие промпты усугубляют проблему. «Напишите чистый, поддерживаемый код» звучит разумно, но не объясняет модели, что именно ваша команда считает чистым. Одни команды хотят тонких контроллеров и строгих сервисных границ. Другие предпочитают меньше слоёв и более короткие файлы. Общий промпт откатывается к средним шаблонам, а средние шаблоны часто не соответствуют локальным стандартам.\n\nМалые команды ощущают это первыми. Если три человека всю неделю занимаются ревью AI-кода, повторяющиеся замечания отнимают внимание у продуктовых решений, оценки рисков багов и архитектуры. Ревью превращается в рутинные правки вместо настоящей проверки качества.\n\nБольшинство повторяющихся замечаний укладывается в несколько знакомых категорий: отсутствие тестов на крайние случаи, неясный нейминг, слишком много логики в одной функции, слабые сообщения об ошибках и код, который игнорирует существующие шаблоны репозитория. Как только эти замечания начинают повторяться, их стоит рассматривать как хорошие кандидаты для переиспользуемых правил промпта.\n\n## Какие замечания стоит включать в промпт\n\nНекоторые замечания подходят для промпта. Другие — для ревью и должны там оставаться.\n\nЗамечание — хороший кандидат для правила промпта, когда оно появляется в разных задачах, файлах и у разных разработчиков. Если ревьюеры постоянно пишут «разбейте эту функцию», «проверьте входные данные» или «используйте формат ошибок проекта», значит модель пропускает общий стандарт. Когда одно и то же замечание встречается три–четыре раза за короткий период, зафиксируйте его как правило.\n\nЛучшие кандидаты обычно влияют на чтение кода, его безопасное поведение и организацию проекта. Это включает нейминг, структуру файлов, ожидания по тестам, формат логов, валидацию входных данных, проверки авторизации, таймауты и правила о том, где должна находиться бизнес-логика.\n\nНе включайте разовые предпочтения. Если один рецензент предпочитает определённый порядок импортов или стиль комментариев, это обычно не должно попадать в промпт, если только команда не согласна, что это важно. Промпты должны нести общие стандарты, а не личные привычки.\n\nПростой фильтр: будет ли это замечание иметь смысл в следующем месяце при другой задаче? Если да — включайте. Если это подходит только для одного файла или чьего‑то вкуса — оставьте в ревью.\n\nНачинайте с правил, которые экономят время ревью быстрее всего. «Добавьте тесты для новой логики ветвления» может убрать целый раунд комментариев. «Никогда не вызывать внешнюю службу без таймаута и обработки повторных попыток» может предотвратить баги ещё до открытия pull request.\n\nЭто особенно важно, если один ведущий инженер или CTO ревьюит код в нескольких продуктах. Повторяющиеся замечания накапливаются быстро. Перевод таких замечаний в правила промпта сокращает шум и оставляет ревьюерам сложные вопросы: компромиссы, архитектура и крайние случаи, которые не решит ни один промпт.\n\n## Как превратить замечание в рабочее правило\n\nНачните с реального комментария из ревью, а не с выдуманной политики. Самые сильные правила обычно происходят из того, что рецензент уже писал несколько раз за месяц.\n\nВозьмём комментарий: «Не подавляйте ошибки в обработчиках API». Это помогает в ревью, но для промпта слишком расплывчато. Модель может выполнить его по-разному и всё равно пропустить то, что вы на самом деле ожидаете.\n\nЛучший вариант именует поведение простым языком: «В обработчиках API никогда не оставляйте пустой блок catch. Логируйте ошибку, возвращайте понятный ответ об ошибке и сохраняйте исходный статус, если вышестоящая служба уже установила его». Теперь модель получает конкретную инструкцию, а рецензент может быстро проверить выполнение.\n\nХорошее правило отвечает на пять вопросов: где применяется, что код должен делать, чего избегать, какие есть исключения и как ревьюер поймёт, что правило выполнено. Если два ревьюера поссорятся о том, выполнено ли правило, формулировка всё ещё слишком мягкая.\n\nДобавляйте ограничения, пока пример ещё свеж. Если правило относится только к публичным эндпоинтам, скажите об этом. Если в тестовых помощниках логирование можно пропускать, отметьте и это. Слабые правила обычно проваливаются на крайних случаях, а не на основном сценарии.\n\nФормулировка важнее, чем команды думают. «Корректно обработайте ошибки» даёт место для дрейфа. «Для публичных API-обработчиков возвращайте JSON-ошибки с полями message и code, никогда не показывайте stack trace и логируйте неожиданные сбои один раз» даёт модели то, что она сможет повторить.\n\nВы не пытаетесь написать идеальный политический документ. Ваша цель — превратить одно повторяющееся исправление в правило, которое даёт лучший первый черновик.\n\nПроверьте правило на одной маленькой задаче, прежде чем распространять повсеместно. Небольшой эндпоинт, одна фонова задача или один обработчик формы — достаточно. Если AI следует правилу без дополнительных объяснений, правило, вероятно, сформулировано достаточно ясно.\n\n## Организуйте правила по типу задачи\n\nПромпты становятся хуже, когда пытаются контролировать всё сразу. Огромный блок правил выглядит исчерпывающим, но обычно создаёт шум. Модель пропускает части, смешивает приоритеты или применяет неверное правило к задаче.\n\nМеньшие блоки правил работают лучше. Их можно переиспользовать, менять и быстро определить, какой блок вызвал плохой результат.\n\nБольшинству команд подходят отдельные блоки для нейминга, тестов, обработки ошибок и документации. Держите каждый блок узким. Если блок по неймингу начинает говорить о повторных попытках, он делает слишком многое.\n\nПодбирайте блоки под задачу. Небольшое изменение текста в UI не нуждается в тех же правилах, что миграция базы данных. Исправление бага в бекенде может требовать валидации и тестов. Рефактор — нейминг и документация, но не советы по релизным заметкам.\n\nЭто становится очевидно, когда команда работает в нескольких слоях. React-страница, сервис на Go и CI-задача редко вызывают одни и те же замечания ревью. Если навязывать один мастер‑промпт всем трем, он растягивается и теряет ясность.\n\nПравила устаревают. Команды переименовывают папки, меняют инструменты тестирования, отказываются от старых шаблонов или меняют стиль логирования. Если устаревшие правила остаются в промпте, модель продолжит генерировать код, который конфликтует с текущим репозиторием.\n\nЗаведите простую привычку поддержки. Раз в несколько недель проверяйте, какие блоки промпта всё ещё уменьшают повторяющиеся замечания, а какие теперь создают трения. Удаляйте мёртвые правила. Переписывайте расплывчатые. Разбивайте любой блок, который превратился в мини‑документ политики.\n\nВам не нужен идеальный мастер‑промпт. Нужен небольшой набор чётких ограничений, подходящих для конкретной задачи.\n\n## Используйте примеры вместо абстрактных советов\n\nАбстрактные правила оставляют слишком много места для догадок. Модель может прочитать «используйте понятные имена» и всё равно произвести data, item или tmp. Короткая пара примеров закрывает разрыв быстро.\n\nВместо заметки «пожалуйста, лучше обрабатывайте ошибки» сохраните небольшой пример «до» и «после», показывающий, что команда принимает.\n\n### Покажите плохую версию рядом с лучшей\n\nНебольшой контраст работает лучше, чем длинное объяснение. Ограничьтесь одной функцией или одним тестовым файлом, чтобы модель могла скопировать шаблон без лишнего шума.\n\n```ts

// Bad function proc(u) { if (!u) return null; return { n: u.name }; }

// Better function buildUserProfile(user) { if (!user) { throw new Error("user is required"); }

return { name: user.name }; }

Второй вариант легче ревьюить. Имя говорит, что делает функция, ошибка явная, а форма возвращаемого значения читается без комментария.\n\nПолный файл обычно добавляет шум. Фрагмент на 10–20 строк достаточно, чтобы обучить правило. Команды, которые быстро работают с инструментами AI, обычно получают лучший результат от трёх коротких примеров, чем от одного большого «референсного» файла.\n\n### Покажите ожидаемые тесты\n\nЕсли хотите получить лучший результат, покажите тесты, соответствующие обычаям вашей команды. Не просто говорите «добавьте тесты». Покажите успешные и ошибочные случаи в стиле, который команда уже ревьюит и мержит.\n\n```ts
test("throws when user is missing", () => {
  expect(() => buildUserProfile()).toThrow("user is required");
});

test("returns the expected shape", () => {
  expect(buildUserProfile({ name: "Sam" })).toEqual({ name: "Sam" });
});

Эти примеры одновременно учат нескольким правилам: используйте имена, говорящие о назначении кода; бросайте понятные ошибки вместо молчаливых сбоев; тестируйте и счастливый путь, и путь ошибки; и добавляйте комментарии только когда причина неочевидна.\n\nЭто важно. Комментарии должны объяснять «почему», а не повторять то, что уже понятно из кода. Если команда следует этому правилу, включите один пример с полезным комментарием и один с бессмысленным. Модели быстрее схватывают разницу из конкретного контраста, чем из ещё одного абзаца инструкций.\n\nКогда примеры похожи на реальные исправления из ревью, промпт начинает звучать как ваша команда, а не как общий гайдлайн.\n\n## Пример цикла ревью\n\nОдин из частых комментариев в сгенерированном бекенд-коде: обработчик принимает данные и сразу обращается к базе почти без проверок. Код проходит быстрый smoketest, но падает на пустых полях, неверных идентификаторах или числах, которые никогда не должны быть отрицательными.\n\nТакое повторяющееся замечание не должно жить только в pull request'ах. Превратите его в правило промпта для функций-обработчиков.\n\nИспользуйте формулировку, которая не оставляет места для догадок:\n\n```text For every HTTP handler, validate path params, query params, and JSON body fields before calling services or the database. Reject missing or malformed required input with status 400 and a short error message. Stop execution after the first validation failure.

Теперь сделайте правило конкретным. Если команда часто ревьюит сгенерированный `CreateInvoice`-обработчик и оставляет заметки вроде «Проверьте `customerId`», «Не принимайте нулевую сумму» и «Не допускайте отсутствие currency», добавьте эти ожидания в задачу, а не только в общее правило. Тогда модель получает и общий шаблон, и конкретные проверки под задачу.\n\nСледующий сгенерированный файл обычно меняется так, как вы ожидаете. Вместо того чтобы парсить тело и вызывать `invoiceService.create(...)` на пятой строке, обработчик начинает с охранников: проверяет, что `customerId` присутствует, `amount` больше нуля и `currency` не пустое. Если проверка не проходит, обработчик возвращает понятный 400‑й ответ и завершает выполнение.\n\nЭто лучше, но ревью всё ещё нужно. Рецензент проверит, подходит ли правило для продукта, согласуется ли текст ошибки с остальной частью приложения и не вываливает ли обработчик в логах лишних деталей. Промпт может закрепить привычку валидировать вход, но люди решают, что считать «валидным» для бизнеса.\n\n## Ошибки, которые ухудшают промпты\n\nКоманды часто берут сфокусированный промпт и превращают его в свалку правил. Это обычно делает сгенерированный код менее согласованным, а не лучше.\n\nОбычная ошибка — вставлять в промпт каждую старую заметку ревью. Большинство комментариев ревью локальны: они исправляют один баг, странный нейминг или поспешный хак. Если замечание не повторяется в разных PR, скорее всего, оно не должно попадать в промпт.\n\n### Когда правила конфликтуют\n\nПротиворечивые правила быстро запутывают модель. Команда может требовать «держать функции короткими» и одновременно «избегать лишних вспомогательных функций». Обе идеи имеют смысл, но не всегда одинаково применимы. Когда правила конфликтуют, модель угадывает, а угадывание порождает странный код.\n\nПохожая проблема возникает, когда старые правила не удаляются. Стандарты меняются. Команда может принять новый шаблон, переименовать слой или изменить стиль тестирования, а промпт всё ещё навязывает старый выбор. Тогда модель продолжит генерировать код по уже заброшенному стандарту.\n\n### Расплывчатые слова ломают правило\n\nСлова вроде «чисто», «лучше» и «просто» звучат полезно, но не говорят модели, что делать. Разные рецензенты вкладывают в них разный смысл: один — меньше строк, другой — более понятные имена, третий — меньше абстракций.\n\nСлабые правила обычно выглядят так:\n\n- "Write clean code"\n- "Make it better"\n- "Use good structure"\n\nЭти строки нужно переформулировать конкретно: предпочитайте ранние возвраты, держите логику работы с базой вне контроллеров, добавьте тест на null‑вход или соблюдайте структуру существующих файлов.\n\nЕщё одна ошибка — ждать, что промпт заменит ревью. Он не заменит. Ревью по‑прежнему ловит компромиссы, контекст и продуктовые решения. Промпт убирает повторяющиеся стандарты. Ревью решает спорные вопросы.\n\nХороший промпт со временем должен укорачиваться, а не разрастаться. Оставляйте правила, которые действительно повторяются, убирайте единичные замечания и используйте простой язык, который даёт меньше места для догадок.\n\n## Быстрая проверка перед развёртыванием в команде\n\nПеред тем как дать промпт всем, попробуйте его на трёх–четырёх недавних pull request'ах. Этот небольшой тест покажет, помогают ли правила в реальной работе или они лишь красиво звучат на бумаге.\n\nКороткий чеклист:
\n- Чётко опишите задачу. «Улучшить эту функцию» слишком расплывчато. «Обновить обработчик webhook платёжки и сохранить существующую форму ответа» даёт модели ясную рамку.\n- Держите каждое правило простым. Ревьюеру должно быть быстро понятно, а модели не нужно угадывать, что значит «чисто» или «лучше».\n- Подбирайте примеры под текущий код команды. Если команда использует Vitest вместо Jest или хранит SQL в конкретной папке, примеры должны следовать этим паттернам.\n- Просите доказательства, когда это уместно. Это могут быть тесты, проверки типов, результаты линтинга или короткая заметка о том, что модель проверила и что оставила без изменений.\n- Следите за следующим раундом ревью. Если рецензенты всё ещё оставляют те же замечания, правило либо слишком расплывчато, либо применяется не к тому типу задач.\n\nСмысл прост: сократить повторяющееся трение. Правило заслуживает места в промпте только тогда, когда ревьюеры видят разницу в следующей партии кода.\n\nЭто же помогает держать промпты короткими. Пять острых проверок лучше длинного блока инструкций, за которым никто не следит. Если одно правило важно только для работы с базой или CI, поместите его в отдельный, меньший промпт для этой задачи, а не в общий.\n\nГибкие команды быстро это почувствуют. Когда промпт называет тип файла, использует простой язык и просит доказательства, ревьюеры тратят меньше времени на повторения и больше — на проверку реальных изменений.\n\n## Включите это в рутину команды\n\nКоманды получают лучшие результаты, если рассматривают повторяющиеся замечания ревью как процессный дефект. Если одно и то же замечание появляется каждую неделю, не оставляйте его в старых pull request'ах. Превратите его в общее правило.\n\nНачните с короткого окна ревью. Просмотрите PR за последний месяц и выпишите три замечания, которые повторялись. Выбирайте те, которые легко реализовать: отсутствие тестов на крайние случаи, расплывчатый нейминг или бизнес-логика в неверном слое.\n\nПреобразуйте эти замечания в небольшой блок промпта, который команда сможет переиспользовать:\n\n- Добавить тесты для счастливого пути и одного пути ошибки.\n- Держать бизнес-логику вне контроллеров.\n- Использовать имена, которые ясно описывают действие.\n\nЭтого достаточно для первой версии. Большинство команд делает наоборот: слишком быстро расширяют набор правил. Промпт с пятнадцатью правилами обычно превращается в фоновый шум.\n\nПрименяйте блок в следующих задачах и внимательно смотрите PR. Когда модель всё ещё ошибается, перепишите правило, а не добавляйте ещё слов. Короткие правила часто работают лучше, потому что оставляют меньше места для домыслов.\n\nВедите простой лог. Запишите правило, где его использовали и сократило ли оно число повторных замечаний. После пяти–шести PR вы увидите, какие правила действительно улучшают выход, а какие лишь удлиняют промпт.\n\nЕсли команде нужна внешняя помощь в настройке стандартов AI-кодирования, oleg.is делится работой Oleg Sotnikov как Fractional CTO и советника для стартапов. Он фокусируется на практичной AI‑ассистированной разработке, инфраструктуре и бережных инженерных процессах для малых и средних команд.\n\nЦель проста: меньше повторяющихся замечаний, меньше лишних правок и код, который раньше соответствует стандартам команды.