Мы работаем над большим проектом с долгой историей. В нём накопились годы продуктовых решений, технического долга, внутренних соглашений, старых библиотек и неочевидных зависимостей между модулями. В какой-то момент стало понятно: косметическими правками уже не обойтись, проект нужно переводить на новые рельсы — Next.js 15, современный React, новый роутинг, более понятные границы между серверным и клиентским кодом.

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

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

А потом началось детальное ревью.

И там выяснилось, что узкое место никуда не исчезло. Оно просто переехало в code review. На ревью приходили не 150 строк аккуратной ручной правки, а тысячи строк сгенерированного кода. Ревьюверы физически не успевали осмысливать такой поток. Нужно было проверять не только синтаксис, но и архитектуру, соответствие старому поведению, использование существующих open source решений, интеграцию с текущими модулями, тесты и регрессии.

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

Отдельно всплыл фронтенд-пласт. Код выглядел правдоподобно, но работал не совсем так, как нужно. Дизайн переносился неаккуратно: токены из Figma не подтягивались, потому что MCP Figma вообще не использовался. Вместо того чтобы работать от дизайн-системы и существующих источников правды, AI угадывал значения и собирал интерфейс «на глаз».

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

В какой-то момент стало понятно: проблема уже не в конкретном PR и не в конкретном разработчике. Нужно менять процесс в компании. Вайбкодинг без правил превращает опытного инженера в сверхбыстрый генератор задач для ревьюверов.

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

Так мы пришли к prompt-first подходу: сначала обсуждать не готовый AI-generated PR, а промт-план, по которому этот PR будет создан.

Что такое prompt-first разработка

Prompt-first разработка — это процесс, в котором перед генерацией кода команда сначала согласует короткий промт-план: что именно нужно сделать, какие файлы можно менять, какие ограничения важны, какие тесты обязательны и что явно не входит в задачу.

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

В классическом процессе цепочка выглядит так:

1. Разработчик читает задачу.

2. Пишет или генерирует код.

3. Открывает большой pull request.

4. Команда пытается понять, что именно было задумано.

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

В prompt-first процессе цепочка меняется:

1. Разработчик пишет короткий .prompt.md или раздел в задаче.

2. Команда быстро проверяет замысел.

3. После согласования AI генерирует код по утверждённому плану.

4. Code review проверяет реализацию уже согласованной идеи.

Это не отменяет code review. Скорее наоборот: делает его дешевле, потому что ревьювер смотрит не на бесформенный поток AI-кода, а на реализацию заранее понятного решения.

Почему проблема стала заметной именно сейчас

AI-инструменты хорошо ускоряют создание текста кода. Но скорость генерации сама по себе не гарантирует качество решения.

Модель может уверенно написать компонент, миграцию, тесты и документацию. При этом она так же уверенно может:

• выбрать не тот уровень абстракции;

• затронуть файлы, которые не относятся к задаче;

• использовать устаревший API;

• обойти внутреннее архитектурное правило;

• добавить «удобное» поведение, которого не было в требованиях;

• написать тесты, которые проверяют не тот контракт.

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

Ревьюверу приходится отвечать сразу на два вопроса:

1. Правильная ли идея?

2. Правильно ли она реализована?

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

Ревью промта дешевле ревью кода

Архитектурная ошибка почти всегда дешевле на стадии плана.

Представим задачу: добавить форму логина в Next.js-приложение. Разработчик просит AI сделать всё сразу. Модель создаёт страницу, форму, server action, валидацию, тесты и пару вспомогательных утилит. На ревью выясняется, что в проекте уже есть middleware, схема валидации должна лежать в другом модуле, а client component получился там, где достаточно server component.

Теперь нужно не просто поправить пару строк. Нужно переосмыслить структуру PR.

Если бы до генерации был короткий план, ревьювер мог бы за пару минут заметить:

• «не трогай middleware, он уже есть»;

• «валидацию кладём в lib/auth/validation.ts»;

• «форму делаем client component, страницу оставляем server component»;

• «не добавляем регистрацию, только логин».

После этого AI получает гораздо более узкую и проверенную инструкцию. Итоговый code review всё ещё нужен, но он уже не вытаскивает задачу из архитектурной канавы.

Я бы формулировал это так: prompt review не заменяет code review, а снимает с него часть работы, которую дешевле выполнить раньше.

Что должно быть в .prompt.md

Хороший промт-план не должен быть длинным. Его задача — не описать весь код, а зафиксировать инженерные границы.

Минимальный шаблон может выглядеть так:

Такой файл можно хранить рядом с кодом, например в prompts/feature-login.md, или прямо в описании задачи. Важно, чтобы он был доступен ревьюверу до генерации кода.

Prompt CI: автоматическая проверка промтов

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

Можно. Подход похож на обычный CI: часть требований проверяется простыми скриптами, часть — линтерами, часть — LLM-проверкой.

Что можно проверять без LLM:

Что удобнее проверять с LLM:

Пример GitHub Actions workflow:

name: Prompt CI

on:
  pull_request:
    paths:
      - 'prompts/*.md'

jobs:
  validate-prompt:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Check mandatory fields
        run: python scripts/check_prompt_fields.py prompts/

      - name: Check forbidden patterns
        run: python scripts/check_forbidden_prompt_patterns.py prompts/

      - name: Check contradictions with LLM
        env:
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: python scripts/check_prompt_contradictions.py prompts/

      - name: Publish prompt report
        run: gh pr comment ${{ github.event.pull_request.number }} --body-file prompt_report.md

Отчёт может быть таким:

# Prompt CI Report

Ошибки:

- `prompts/feature-auth.md:12`: не указана версия React.
- `prompts/feature-auth.md:24`: промт разрешает использовать `any`, хотя это запрещено правилами проекта.

Предупреждения:

- Промт затрагивает 8 файлов. Возможно, задачу стоит разделить.

Проверки пройдены:

- Ссылка на задачу присутствует.
- Противоречий не найдено.
- Критерии приёмки указаны.

На первом этапе такой CI лучше запускать в advisory mode: он пишет предупреждения, но не блокирует PR. Когда команда привыкнет к формату, критичные проверки можно сделать блокирующими.

Как внедрять без бюрократии

Главный риск prompt-first подхода — превратить его в ещё одну обязательную бумажку. Тогда команда быстро начнёт писать формальные промты, которые никто не читает.

Чтобы этого не случилось, начинать стоит с малого.

Неделя 1: договориться о шаблоне

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

• контекст;

• цель;

• файлы;

• критерии приёмки;

• ограничения.

Неделя 2: использовать prompt review на рискованных задачах

Не надо заставлять команду писать .prompt.md на каждую правку текста. Начните с задач, где AI генерирует много кода или где есть архитектурный риск.

Неделя 3: добавить простые проверки

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

Неделя 4: подключить LLM-проверки

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

Через месяц: измерить эффект

Полезные метрики:

• средний размер PR после внедрения prompt-first;

• число итераций на code review;

• доля PR, где архитектурные замечания появились уже после генерации;

• время от начала задачи до апрува.

Если метрики не улучшаются, значит процесс стал ритуалом, а не инструментом. Это тоже хороший сигнал.

Почему промт становится инженерным артефактом

Промт-план полезен не только до генерации кода. Он остаётся в репозитории и объясняет, почему решение вообще появилось именно таким.

Через месяц после мержа можно открыть PR и увидеть не только diff, но и исходный замысел:

• какую задачу решали;

• какие файлы разрешалось менять;

• какие компромиссы были осознанными;

• какие ограничения были важны;

• какие вопросы оставались открытыми.

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

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

Для кого это особенно полезно

Для джуниора prompt-first даёт карту задачи. Он меньше гадает и быстрее получает обратную связь по замыслу, а не по уже написанному большому куску кода.

Для сеньора это способ влиять на архитектуру раньше, не тратя час на чтение сгенерированного diff, который всё равно придётся переписывать.

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

Что важно не перепутать

Prompt-first — не серебряная пуля и не замена инженерному мышлению. Плохой промт-план может так же уверенно привести к плохому коду, как плохое ТЗ — к плохому продукту.

Ещё одна ловушка — пытаться согласовывать каждый микрошаг. Тогда команда потеряет скорость, ради которой вообще использует AI-инструменты.

На практике prompt-first стоит применять там, где цена ошибки выше цены короткого предварительного обсуждения:

• архитектурные изменения;

• новые пользовательские сценарии;

• безопасность и авторизация;

• миграции данных;

• интеграции с внешними сервисами;

• большие AI-сгенерированные PR.

Для мелких правок достаточно обычного review.

Вывод

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

Prompt-first разработка предлагает сдвинуть обсуждение раньше. Сначала согласовать короткий промт-план. Затем сгенерировать код. Потом проверить реализацию.

Код — это результат. Промт — это намерение. А хороший инженерный процесс должен уметь ревьюить и то и другое.