Spec-Driven Development: практическое введение

Разработчики часто начинают писать код, не ответив на главный вопрос — что именно должна делать система. Spec-Driven Development (SDD) предлагает другой путь: сначала описываем поведение в спецификации, затем отдаём её AI-агенту для реализации. Подход основан на курсе JetBrains и DeepLearning.AI и уже применяется командами, работающими с AI-coding агентами.

Что такое спецификация

Спецификация (spec) — это живой документ, который определяет:

• Что должна делать система
• Как она реагирует на разные сценарии
• Какие ограничения и правила соблюдает

Это не 50-страничный документ. Спека может занимать полстраницы — главное, чтобы в ней была ясность, а не объём.

От промпта к спецификации

Разница между размытым промптом и структурированной спецификацией — это разница между угадыванием и конструированием.

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

Хорошая спецификация задаёт конкретные условия успеха и неудачи, правила безопасности и краевые случаи. Именно структурированная спецификация даёт AI (или человеку) достаточно контекста, чтобы реализовать фичу с первого раза.

Пример спецификации: endpoint авторизации

Рассмотрим, как может выглядеть спецификация endpoint для логина.

Endpoint: POST /api/login

Request:

{
  "email": "user@example.com",
  "password": "string"
}

Поведение:

• Успех: если email и пароль верны — вернуть токен и данные пользователя
• Неверные данные: если учётные данные не совпадают — вернуть INVALID_CREDENTIALS
• Невалидный ввод: если поля пустые или формат email неправильный — вернуть INVALID_INPUT

Правила:

• Пароли хранятся в хешированном виде (bcrypt)
• Токен истекает через 24 часа
• Не раскрывать, что именно неверно — email или пароль (безопасность)

Краевой случай:

• После 5 неудачных попыток — блокировка аккаунта на 15 минут (rate limiting)

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

Три преимущества SDD

Централизация изменений

В традиционном проекте изменение фичи означает поиск по десяткам файлов. В SDD вы сначала обновляете спецификацию, а AI-агент адаптирует реализацию. Одна строка в спеке — и весь код перестраивается под неё.

Снижение потери контекста

Проекты обрастают «спагетти-кодом», когда первоначальные решения не зафиксированы. Актуальная спецификация работает как постоянная память проекта — почему фича существует и как должна работать.

Повышение точности намерений

Главная проблема при работе с AI — искажение намерений. Структурированная спецификация повышает intent fidelity: выходной код соответствует тому, что вы действительно имели в виду. Вы не просто даёте инструкции — вы определяете ожидания.

Архитектор и строитель

SDD сдвигает роль разработчика: вы переходите от строителя (пишет каждую строку кода) к архитектору (определяет систему). Но AI — не идеальный строитель, а быстрый colaborатор, который всё ещё нуждается в руководстве.

Как архитектор вы отвечаете за:

• Проверку поведения и ревью сгенерированного кода
• Обработку сложных архитектурных краевых случаев
• Поддержание спецификации в актуальном состоянии

Где SDD работает, а где — нет

Хорошо подходит для:

• Прототипирования — быстрая итерация при чётко определённых требованиях
• Обучения — разработчики понимают логику до синтаксиса
• Онбординга — общая документация вместо «tribal knowledge»

Осторожно:

• Размытые требования — плохая спека ведёт к плохому коду, только быстрее
• Высокая сложность — в сильно связанном legacy-коде AI может не справиться даже с хорошей спецификацией

Резюме

Spec-Driven Development — это не отказ от кодирования, а способ сделать намерения явными. Чем яснее ваше описание — тем качественнее результат. Инвестируя время в спецификацию, вы строите не быстрее — вы строите умнее.