Spec-driven разработка с AI: сначала план, потом пусть агент строит

У vibe coding есть настоящее обаяние. Открываете Claude Code, пишете «сделай мне форму логина» — и через минуту смотрите на работающий код. Для прототипа или проекта выходного дня это волшебно. Проблемы начинаются, когда вы пробуете то же самое на продакшен-системе с 200 тысячами строк кода, тремя командами и клиентами, которые очень не хотят, чтобы у них в пятницу вечером упали платежи.

Вот тут freestyle prompting перестаёт работать. Агент — исключительно способный исполнитель, но он хорош ровно настолько, насколько хороша поставленная задача. А «сделай как-нибудь» — это не задача. Именно поэтому лучшие разработчики в 2026 в серьёзной работе не переключаются между «AI или без AI». Они переключаются между «vibe coding» и «spec-driven development». Давайте разберём, что это значит и когда что использовать.

Что ломается, когда вы vibe-кодите серьёзные вещи

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

Вторая проблема — scope. Агент с энтузиазмом рефакторит, переименовывает и «улучшает» файлы, которых задача вообще не должна была касаться. В итоге получается PR из 40 файлов, где 35 из них — шум. Ревью такого PR — кошмар, и именно здесь рождаются дыры в безопасности и регрессии — потому что ни у кого нет сил честно прочитать 2000 строк изменений.

Как выглядит хороший spec для агента

Spec — это не формальный документ на десять страниц. Это чёткое, краткое задание, которое не даёт агенту додумывать главное. Хороший spec для задачи по реализации содержит пять вещей:

• Scope — что именно нужно сделать и чего агент НЕ должен касаться («меняй только эндпоинт X, модель данных не трогай»)
• Constraints — какие библиотеки, конвенции и паттерны соблюдать («используй существующий ApiClient, никаких новых зависимостей»)
• Критерии приёмки — как понять, что готово («возвращает 400 при отсутствии email, 200 с токеном при успехе»)
• План по файлам — какие файлы меняются и примерно как («новый handler в auth/views.py, тест в tests/test_auth.py»)
• Ожидания по тестам — что должно быть покрыто и в каком стиле («unit-тесты на валидацию, один интеграционный тест happy path»)

Фокус в том, что этот spec часто не нужно писать целиком вручную. Пусть агент сначала набросает черновик плана, а вы его прочитаете и поправите. Это, кстати, самый быстрый способ поймать недопонимание — когда агент пишет в плане «добавлю новое поле в модель User», а вы знаете, что это запрещено, вы ловите это за десять секунд вместо часа реализации.

## Zadacha: Rate limiting na login endpoint

### Scope
- Menyaem POST /api/auth/login/
- NE trogaem model dannyh i drugie endpointy

### Constraints
- Ispolzuem sushchestvuyushchiy Redis-klient (core/cache.py)
- Nikakih novyh zavisimostey
- Soblyudaem konvenciyu trailing slash v URL

### Kriterii priyomki
- Maks 5 popytok v minutu na IP
- Pri prevyshenii: 429 + zagolovok Retry-After
- Uspeshnyy login sbrasyvaet limit

### Plan po faylam
- core/ratelimit.py — novaya utilita
- auth/views.py — dekorator na login
- tests/test_ratelimit.py — pokrytie

### Testy
- Unit: limit srabatyvaet posle 5 popytok
- Integracionnyy: 429 neset pravilnyy zagolovok

Цикл: план → ревью → реализация → проверка

У spec-driven разработки есть ритм. Речь не о том, чтобы написать идеальное задание и исчезнуть на час. Это четыре фазы с человеческими контрольными точками в нужных местах.

1. План

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

2. Ревью плана

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

3. Реализация

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

4. Проверка

В конце вы проверяете по критериям приёмки, а не по ощущению. Прошли ли те тесты, которые вы хотели? Ведёт ли себя эндпоинт так, как сказано в spec? Держится ли дифф в рамках scope? Поскольку критерии вы написали заранее, ревью — это конкретное «да/нет», а не расплывчатое «хм, вроде норм».

Когда vibe coding всё ещё уместен

Это не манифест против vibe coding. Freestyle prompting — вполне законный инструмент, просто для другого типа работы. Vibe coding имеет смысл для прототипов, где цель — быстро выяснить, стоит ли идея вообще усилий. Для одноразовых скриптов, которые вы запускаете раз и удаляете. Для личных инструментов, где вы единственный пользователь и единственный, кто их поддерживает. Для изучения новой библиотеки, где вы просто хотите быстро увидеть, как всё устроено.

Выбирайте spec-driven подход в момент, когда верно хотя бы одно: код пойдёт в продакшен, над ним будет работать больше одного человека, он будет поддерживаться долго или делает что-то, где ошибка больно бьёт — платежи, аутентификация, данные клиентов. Иными словами: чем выше цена ошибки и чем дольше живёт код, тем больше окупается вложение в spec заранее.

Вывод: план — это новый промпт

Лучший способ использовать coding-агента для серьёзной работы сегодня — не писать более умные одноразовые промпты. Это научиться писать хорошие specs и вести цикл план → ревью → реализация → проверка. Агент берёт на себя исполнение. Вы оставляете себе главное: определение проблемы, границы решения и решение о том, что работа сделана.

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