Промты для вайб-кодинга: каркас, правила проекта, тесты

Вайб-кодинг перестал быть развлечением: на таком коде работает production. Вместе с этим появился новый класс проблем.

Модель уверенно выдаёт правдоподобный, но неверный код. Переписывает то, что её не просили. Удаляет падающий тест вместо устранения причины. Предлагает установить пакет, которого не существует.

За последние полтора года практика устоялась. Anthropic, OpenAI и Google независимо описали в документации примерно одно и то же, а практикующие инженеры пришли к тем же выводам своим путём.

Ниже — то, что повторяется у всех, с готовыми текстами промтов. Шаблоны переносятся без изменений в Claude Code, Cursor, Windsurf, Copilot, Codex, Aider или обычный чат.

Каркас промта: пять обязательных частей

Магической формулировки, после которой модель начинает писать хороший код, не существует. Существует структура, которой не хватает большинству плохих промтов.

Каркас состоит из пяти частей:

1. Цель. Одним предложением: что считается «готово».
2. Контекст. Какие файлы, какой стек, какие команды, на какие существующие решения ориентироваться.
3. Ограничения. Что менять нельзя, чего не делать.
4. Проверка. Чем модель докажет решение: тесты проходят, поведение изменилось, ошибка не воспроизводится.
5. Порядок действий. Сначала план, потом код. Маленькими шагами.

Anthropic описывает это как цикл «изучи → спланируй → напиши → зафиксируй». В руководстве OpenAI по Codex тот же подход разбит на четыре обязательных блока промта, включая «Done when» — проверяемое условие завершения. Google для Gemini даёт близкую по смыслу схему «роль, задача, контекст, формат» с рекомендацией разделять блоки XML-тегами или заголовками Markdown.

Сравнение на практике. Постановка, оставляющая простор для домысливания:

почини баг с авторизацией

Постановка с контекстом, границами и способом проверки:

Пользователи сообщают, что вход перестаёт работать после истечения сессии.
Проверь поток аутентификации в src/auth/, особенно обновление токена.
Сначала напиши падающий тест, воспроизводящий проблему, затем исправь её.
Устраняй первопричину, а не глуши ошибку.

Второй вариант не длиннее в разы. Он просто содержит критерий готовности: падающий тест либо воспроизводит проблему, либо нет.

Файл правил проекта: один раз вместо каждого раза

У всех современных помощников есть один механизм под разными именами: файл, который читается в начале каждой сессии.

Варианты именования: CLAUDE.md, .cursor/rules/*.mdc, GEMINI.md, AGENTS.md. Последний постепенно становится общим стандартом и поддерживается сразу несколькими средами.

Задача файла — снять необходимость повторять в каждом чате стек проекта и команду запуска тестов.

Почему размер файла критичен

Главная ошибка — раздувать файл правил. Anthropic прямо предупреждает: чем длиннее файл, тем выше вероятность, что модель проигнорирует инструкции.

Документация Cursor рекомендует держать правило короче 500 строк и разбивать крупные правила на составные. Для правил, применяемых всегда, практики советуют жёстче — порядка тридцати строк, поскольку за них платят токенами при каждом запросе.

Проверочный вопрос для каждой строки: если её убрать, начнёт ли модель ошибаться? Если нет — строка удаляется.

Рабочая структура файла

# Проект: <название>

## Что это и стек
- Назначение, язык, фреймворк и версии.

## Команды
- Сборка: <команда>
- Тесты: <команда> (запускай отдельные тесты, не весь набор)
- Линтер: <команда>
- Проверка типов: <команда>

## Стиль кода (только отличия от общепринятого)
- <именование, структура папок, модули>

## Рабочий процесс
- Сначала покажи план — я утверждаю — потом код.
- Делай маленькие правки, каждую можно проверить.
- После серии правок прогоняй типы и тесты.

## Запреты
- Не меняй файлы вне задачи и не рефактори несвязанный код.
- Не добавляй новые зависимости без явного разрешения.
- Не меняй и не удаляй тесты, чтобы они «прошли».
- Не выдумывай API и библиотеки — сверяйся с реальным кодом и документацией.

## Этикет репозитория
- Ветки: <схема>, коммиты: <схема>, пул-реквесты: <правила>.

Наибольший эффект стабильно даёт раздел «Команды»: это ровно то, что модель не угадает и начнёт выдумывать.

Правила ведения самого файла

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

Форматы с областью применения

Cursor использует .mdc с фронтматтером, где правило привязывается к маскам файлов и режиму применения:

---
description: Project conventions for the web app
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
# Web app — conventions

## Stack
Next.js (App Router), TypeScript, Tailwind, Drizzle + Postgres.

## Conventions
- Server Components по умолчанию; "use client" — только при state или effects.
- Никакого any — типизировать всё; предпочитать unknown с сужением.
- Тесты рядом с файлом: *.test.ts

## Don't
- Не трогать /legacy — модуль переписывается.

Флаг alwaysApply: false и маски globs позволяют держать основной набор правил компактным: узкие конвенции подгружаются только при работе с соответствующими файлами. Правила с alwaysApply: true оплачиваются токенами на каждом запросе, поэтому режутся жёстче остальных.

Для кросс-инструментальной совместимости имя контекстного файла настраивается явно. Пример конфигурации Gemini CLI, распознающей общий стандарт:

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

Как заставить агента сначала планировать

Самая дорогая ошибка ИИ-помощника — не кривой код, а качественно выполненная не та задача. Лечится разделением фаз.

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

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

Вот идея: <ИДЕЯ>

Ограничение «только один вопрос за раз» не косметическое. Без него модель выдаёт список из пятнадцати пунктов, отвечают на треть, половина требований остаётся неозвученной.

Вариант с записью спецификации в файл

Второй формат того же приёма — интервью с фиксацией результата на диск:

Задача: построить [краткое описание]. Подробно проинтервьюируй меня.

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

Продолжай интервью, пока не покрыты все аспекты, затем запиши полную
спецификацию в SPEC.md.

Разбивка на шаги

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

Отдельно запрашивается чеклист todo.md: он держит состояние между сессиями, когда контекст приходится очищать.

Ручной режим планирования

Если у инструмента нет отдельного режима планирования, инструкция добавляется вручную:

Прочитай относящийся к задаче код и НЕ меняй пока ни одного файла.
Составь план: какие файлы затронуты, в каком порядке вносить изменения,
какие риски и граничные случаи. Дождись моего подтверждения — потом код.

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

Архитектура: варианты решения и проверка замысла

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

Несколько вариантов до выбора

Предложи 2–3 разных подхода к реализации [задача или возможность].
Для каждого: краткое описание, плюсы, минусы, влияние на существующую
архитектуру, риски и примерная сложность.
НЕ пиши код. В конце дай рекомендацию с обоснованием.
Выбор варианта за мной, после выбора переходим к плану.

Проверка замысла на прочность

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

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

Формулировка «не соглашайся по умолчанию» здесь обязательна: без неё модель подтверждает предложенное решение практически при любом его качестве.

Как не дать сломать рабочий код

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

Помогает шаблон запроса на изменение с явными границами:

## Запрос на изменение
[Что именно нужно изменить]

## Место
Файл: [точный файл]
Функция или строка: [точное место]

## Ограничения
- Меняй ТОЛЬКО [конкретную вещь]
- НЕ меняй [что должно остаться прежним]
- НЕ переименовывай, не рефактори и не «улучшай» другой код
- Если считаешь, что нужны другие изменения — скажи, но не делай их

## Проверка
После изменения должно стать так: [что именно изменится]

Пункт «скажи, но не делай» важнее, чем кажется: он даёт модели легальный выход. Без него она либо молча делает лишнее, либо молча не делает нужное.

Область изменений и критерии приёмки

Для задач крупнее одной функции границы задаются на уровне каталогов, а критерий готовности — списком:

Область изменений:
- Меняй только src/components/ и src/hooks/.
- Не трогай бэкенд-API.
- Не добавляй зависимости без разрешения.
- Не рефактори несвязанный код.

Критерии приёмки:
- Существующее поведение не ломается.
- <новое поведение> работает.
- Добавь тест на новое поведение, если в проекте есть автотесты.
- Запусти команду проверки. Если команда неизвестна — посмотри
  конфигурацию проекта, не угадывай.
- Если проверку выполнить нельзя — скажи об этом явно.

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

Тесты как узда для помощника

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

Это не мелкая шалость. Тест фиксирует контракт. Молча переписав тест, модель молча меняет спецификацию — и это обнаруживается в лучшем случае на проверке кода, в худшем на бою.

Работай строго по циклу: красный → зелёный → рефакторинг.
1. Сначала напиши ОДИН самый простой падающий тест на следующее требование.
   Остановись и покажи мне его на утверждение.
2. После моего подтверждения напиши минимум кода, чтобы тест прошёл.
3. Запусти тесты. Если красный — чини код, а НЕ тест.
4. Рефактори только когда тесты зелёные.

ЗАПРЕТ: не изменяй и не удаляй тесты, чтобы они «прошли». Тест фиксирует
контракт; менять контракт можно только с моего явного разрешения.

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

Поиск недостающих тестов

Отдельная задача, которая хорошо решается в свежей сессии на готовом коде:

Проверь этот код и выпиши список отсутствующих тестовых сценариев
и тестов, которые должны существовать.
Будь конкретен. Не выдумывай.
Формат вывода — задачи, готовые к постановке в трекер.

Отладка: гипотеза вместо готового ответа

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

Отличить одно от другого позволяет требование доказательств:

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

Контекст: <логи, недавние изменения, окружение>

Разбор стектрейса

Самый частый в ежедневной работе шаблон — структурированный разбор трассировки вместо свободного пересказа:

Разбери стектрейс и ответь:
1. Где именно возникает ошибка — файл, строка, функция.
2. Что означает это сообщение об ошибке простыми словами.
3. Наиболее вероятная первопричина.
4. Что смотреть в первую очередь для исправления.

Стектрейс:
<вставить>

Вопрос «что ты предположил?»

Недооценённый приём: вместо вопроса «это правильно?» (ответ всегда утвердительный) запрашиваются допущения. Именно в них прячутся баги.

После того как напишешь функцию, ответь:
- Какую структуру данных ты выбрал и почему?
- Три самых вероятных граничных случая — все ли обработаны?
- Что произойдёт при пустом, отсутствующем или некорректном вводе?
- Где бы ты поставил первую точку останова, если это сломается на бою?

Рефакторинг и проверка кода

Для рефакторинга ключевое — явно разделить «лучше внутри» и «другое поведение снаружи»:

Цель: отрефакторить [модуль] без изменения наблюдаемого поведения.

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

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

Нельзя: добавлять возможности, чинить несвязанные баги, менять тесты
только ради того, чтобы рефакторинг «прошёл».

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

Проверка кода в свежем контексте

Для проверки применяется новая сессия — та, что не писала этот код и не привязана к нему:

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

Сверка изменений с планом

Отдельный вариант проверки, когда план был зафиксирован заранее:

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

Легаси-код и миграции

ИИ-помощник облегчает изменение кода до его понимания. В легаси-модуле это прямой путь к тихой регрессии: бизнес-правило, зашитое в неочевидном условии, исчезает вместе с «упрощением».

Поэтому фаза анализа отделяется от фазы изменений жёстче, чем в обычной задаче.

Анализ перед изменением

Выполняется миграция функциональности [название].
Текущая реализация находится в /legacy/[модуль].
Целевая архитектура разделяет слои: домен, приложение, инфраструктура.
Характеризующие тесты в /tests/legacy описывают поведение,
которое должно остаться совместимым.

Проанализируй текущую реализацию и выпиши:
1. бизнес-правила,
2. внешние зависимости,
3. побочные эффекты,
4. вероятные риски миграции,
5. файлы, которые потребуют изменений.

Код пока не генерируй.

Инвентаризация побочных эффектов

Критичный шаг для любой миграции: именно побочные эффекты ломаются при переносе логики между слоями.

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

Неуверенные ответы помечай как unknown.

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

Документация из кода

Для генерации архитектурного обзора репозиторий передаётся моделью в «упакованном» виде (утилиты вроде repomix собирают дерево проекта в один файл). Формулировка задачи задаёт целевого читателя: обзор пишется для человека, который приходит в проект впервые, а не для того, кто уже знает код.

Выдуманные пакеты и слопсквоттинг

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

Исследование, представленное на USENIX Security 2025 (576 тысяч сэмплов кода, шестнадцать моделей), показало: в среднем 19,7% рекомендованных пакетов оказались выдуманными — свыше 205 тысяч уникальных несуществующих имён.

Разброс по типам моделей существенный: у открытых моделей доля выдуманных пакетов составила 21,7%, у коммерческих — 5,2%. При этом 43% несуществующих имён повторялись при каждом из десяти повторных прогонов, то есть они предсказуемы.

Отсюда атака, получившая название «слопсквоттинг»: злоумышленник заранее регистрирует популярное выдуманное имя и ждёт установки пакета без проверки.

Автономные циклы и изоляция агента

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

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

• Изоляция обязательна. Агент с правом выполнять команды запускается в контейнере или отдельной виртуальной машине с ограниченным доступом к файловой системе и сети — не на основной рабочей машине.
• Расход бюджета. Цикл без ограничителя итераций способен непредсказуемо израсходовать квоту API.
• Ограничение области. Каталог проекта монтируется отдельно, доступ к секретам и ключам исключается на уровне окружения, а не инструкцией в промте.

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

Антипаттерны и пороговые правила

Список того, что стабильно портит результат:

• Расплывчатая постановка. «Сделай красиво», «почини баг». Заменяется симптомом, местом и критерием готовности.
• Всё в одной сессии. Несвязанные задачи засоряют контекст. Между задачами контекст очищается.
• Раздутый файл правил. Важные инструкции тонут в шуме.
• Бесконечное исследование без рамок. Модель читает сотни файлов и забивает контекст до начала работы. Область чтения ограничивается явно.
• Слепое доверие правдоподобному коду. Он компилируется, хорошо читается и не обрабатывает граничные случаи.
• Разрешение править тесты. Тихое изменение контракта.
• Установка выдуманных пакетов. Риск для цепочки поставок.
• Огромный набор изменений за раз. Его физически некому проверять. По данным исследований агентских пул-реквестов значительная их часть отклоняется, зависает в очереди на проверку или получает многократно увеличенное время ревью; известен случай отклонённого пул-реквеста на тринадцать тысяч строк.
• Уговоры вместо структуры. «Пожалуйста, сделай хорошо» не работает — работают пять частей каркаса.

Пороговые правила смены подхода

Три сигнала, по которым процесс останавливается и перестраивается:

• Модель поправляют больше двух раз подряд по одному вопросу → контекст очищается, промт переписывается с нуля. Это быстрее спора.
• Файл правил перестал соблюдаться → он слишком длинный, требуется сокращение.
• Набор изменений нельзя проверить за один подход → задача слишком крупная, требуется дробление.

С чего начать сегодня

Первый шаг — файл правил проекта. Минимально: два раздела, команды и запреты, в пределах одного экрана.

Второй шаг — привычка «сначала план». Для любой задачи сложнее однострочного изменения: план, подтверждение, код.

Третий шаг — способ проверки в каждом промте. Тест, сборка, линтер, вывод команды. Результат, который нельзя проверить, не уходит в production.

Остальное — надстройки над этими тремя вещами.

FAQ

Нужен ли файл правил для небольшого проекта?

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

Чем AGENTS.md отличается от CLAUDE.md?

Механика идентична: файл читается в начале сессии. Различие в поддержке — AGENTS.md распознаётся сразу несколькими средами и постепенно вытесняет вендорские имена. В части инструментов список распознаваемых имён настраивается в конфигурации.

Что делать, если модель игнорирует запреты из файла правил?

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

Как безопасно переносить легаси-модуль?

Сначала фаза анализа без генерации кода: бизнес-правила, внешние зависимости, побочные эффекты, риски. Затем характеризующие тесты на текущее поведение. Перенос выполняется по одному модулю или маршруту, а не целиком.

Какой объём изменений безопасно отдавать на проверку?

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

Помогают ли вежливые формулировки в промте?

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

Как проверить, что агент не подправил тесты?

Тесты фиксируются в системе контроля версий до реализации. Далее достаточно посмотреть изменения в каталоге тестов перед слиянием.

Можно ли запускать агента в автономном режиме?

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

Заключение

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