Спецификация перед кодом (Spec-First Вайбкодинг)

1. Обзор концепции и системная проблема

Главная соблазн новичка в вайбкодинге — это скорость. Кажется, что магия ИИ заключается в том, чтобы закинуть одно предложение: «Сделай мне систему подписок со Stripe, кабинетом пользователя и базой данных» — и смотреть, как за 30 секунд появляется куча кода.

Но в 95% случаев такая эйфория заканчивается крахом: проект выдает 50 красных ошибок компиляции, миграции баз данных конфликтуют, а попытки попросить «Исправь это!» лишь ухудшают ситуацию, стирая уже написанный рабочий код.

Методология Spec-First (Спецификация перед кодом) — это золотой стандарт зрелой разработки с ИИ. Она основана на железном правиле:

Ни одной строки кода, пока архитектурный план в файле SPEC.md не будет прочитан и утвержден человеком!

2. Архитектурная таксономия и ментальная модель

┌─────────────────────────────────────────────────────────────┐
│                 ДВА ПОДХОДА К ВАЙБКОДИНГУ                  │
├─────────────────────────────────────────────────────────────┤
│ ❌ Хаотичный подход (Vibe & Pray):                          │
│    «Напиши всю фичу сразу»                                 │
│    ➔ ИИ нагенерировал 500 строк каши                         │
│    ➔ Ничего не работает ➔ 3 часа дебага и нервов           │
├─────────────────────────────────────────────────────────────┤
│ ✅ Подход Spec-First (Дисциплинированный инжиниринг):      │
│    1. Составляем `SPEC.md` (Архитектура и шаги)            │
│    2. Человек вычитывает план: «Вот тут поправь логику»    │
│    3. Только после ОК: Агент реализует Шаг 1 ➔ Проверка    │
│    4. Агент реализует Шаг 2 ➔ Проверка                     │
│    ➔ Чистый, работающий проект с первого раза!              │
└─────────────────────────────────────────────────────────────┘

3. Технический пайплайн и внутренняя механика

1. Шаг 1: Запрос на проектирование (Planning Prompt):

   «Не пиши код! Мы планируем добавить систему комментариев под статьями. Составь файл SPEC.md, где опиши: схему таблицы в базе данных, необходимые API-роуты, список новых компонентов и 4 пошаговые задачи реализации».

2. Шаг 2: Ревью человеком: Вы открываете созданный SPEC.md, читаете его и вносите правки: «Давай уберем возможность анонимных комментариев, только после логина».
3. Шаг 3: Пошаговое выполнение (Execution):

   «План утвержден. Теперь выполни ТОЛЬКО Задачу 1 из спецификации (создай схему таблицы и миграцию). Остальное не трогай».

4. Шаг 4: Верификация: Вы проверяете, что миграция успешно прошла, и только тогда даете команду перейти к Задаче 2.

4. Практические инженерные сценарии в продакшене

01. Запрос на создание системы комментариев

Вы инициируете проектирование системы комментариев, создавая файл SPEC.md, который включает структуру базы данных и необходимые API.

02. Ревью и одобрение спецификации

Человек проверяет и вносит изменения в SPEC.md, уточняя детали реализации, прежде чем модель начнет кодить.

03. Пошаговая реализация и проверка

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

5. Подводные камни, типовые ошибки и безопасность

При использовании подхода Spec-First важно избегать чрезмерной самоуверенности в ИИ. Необходимо помнить, что даже с четким планом могут возникнуть ошибки, и их нужно тщательно проверять на каждом этапе.