Spec-driven development: разработка через спецификации на практике

Spec-driven development (SDD, разработка через спецификации) — это подход к разработке ПО, в котором главным рабочим артефактом становится спецификация: документ, фиксирующий, что должна делать система, зачем и по каким критериям проверяется результат. Код пишется по спецификации и сверяется с ней, а не наоборот. Подход сформировался как ответ на главную проблему разработки с AI-агентами: модель генерирует код быстро и уверенно, но без зафиксированного намерения так же быстро и уверенно генерирует не то.

Термин закрепился в индустрии в 2025 году. В июле AWS выпустила Kiro — агентный IDE, построенный вокруг цикла «требования → дизайн → задачи → код». В сентябре GitHub открыла Spec Kit — open-source-инструментарий spec-driven-разработки для AI-агентов (GitHub Copilot, Claude Code, Gemini CLI и других) с процессом «spec → plan → tasks → implement» — и в анонсе прямо противопоставила его «vibe coding» — стилю, когда разработчик описывает цель в чате, принимает сгенерированный код на глаз и итерирует промптами. Сам термин vibe coding предложил Андрей Карпаты в начале 2025 года, и для прототипов такой стиль работает; ломается он на продуктах, которые нужно поддерживать.

Идея не новая — новым стал исполнитель

Писать намерение до кода программисты придумали задолго до LLM. Waterfall опирался на техническое задание; в 2000-х появились BDD (behaviour-driven development) с исполняемыми сценариями на Gherkin и «design by contract» Бертрана Мейера с формальными пред- и постусловиями; API-разработка прошла через spec-first с OpenAPI. SDD наследует всем этим практикам, но отвечает на новый вопрос: как ставить задачу исполнителю, который работает со скоростью автодополнения, не задаёт уточняющих вопросов и не несёт ответственности за результат.

С человеком неполная постановка компенсируется опытом и диалогом: разработчик придёт и спросит. AI-агент не придёт. Задача «добавь экспорт в CSV» оставляет открытыми десятки решений — какие колонки, какая кодировка, что с пустыми значениями, где кнопка, что видит пользователь при ошибке. Агент примет все эти решения сам, статистически правдоподобно и без предупреждения. Спецификация закрывает развилки до того, как по ним разъехался код.

Как это выглядит на практике

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

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

Спека живёт в репозитории рядом с кодом (например, docs/specs/), имеет статус (draft → approved → in progress → shipped) и проходит утверждение до начала кода. Дальше цикл: агент (или человек) реализует по спецификации, ревью сверяет дифф со спекой, статус обновляется после отгрузки. Отгруженные спеки остаются историей продукта — почему фича устроена именно так, записано в момент, когда контекст ещё все помнили.

Чем SDD отличается от соседних подходов

• От классического ТЗ — жизненным циклом. ТЗ в waterfall пишется один раз, устаревает к середине проекта и живёт отдельно от кода. Спека — это файл в репозитории под версионным контролем: она маленькая (одна поставка — одна спека), обновляется вместе с кодом и читается агентом в каждой сессии.
• От user stories в agile — полнотой. История («как пользователь, я хочу…») фиксирует потребность, но не поведение на границах; детали доопределяются в разговоре. SDD требует зафиксировать сценарии, крайние случаи и критерии готовности письменно — потому что исполнитель не участвует в разговоре.
• От TDD и BDD — уровнем описания. Тесты и Gherkin-сценарии описывают проверяемое поведение, но не отвечают «зачем» и «что не входит». SDD не заменяет их: секция критериев готовности прямо порождает тесты. Спека — источник, тесты — производная.
• От vibe coding — наличием контракта. В vibe coding намерение живёт в промпте и умирает с контекстом чата; в SDD оно зафиксировано в артефакте, по которому можно проверять результат, возобновлять работу и спорить предметно.

Что это даёт команде с AI-агентами

• Предсказуемость. Агент строит то, что записано, а не то, что статистически вероятно. Развилки поведения решает спека, а не «настроение» модели.
• Возобновляемость. Сессия агента оборвалась — следующая читает спеку и план и продолжает с того же места. Контекст живёт в репозитории, а не в истории чата.
• Проверяемость. Ревью диффа против спеки — конкретный вопрос «делает ли код то, что зафиксировано» вместо расплывчатого «выглядит нормально».
• Документация как побочный эффект. История отгруженных спек — это ответ на вопрос «почему здесь так», который обычно теряется первым.

Как перейти, не утонув в процессе

1. Заведите шаблон спеки из пяти секций выше и папку docs/specs/.
2. Введите одно правило без исключений: фича не начинается без утверждённой спеки.
3. Спеку пишет тот, кто ставит задачу, — или AI-агент по разговору с ним, а человек утверждает. На практике это десять-пятнадцать минут диалога.
4. Держите спеки в репозитории, а не в стороннем трекере: агент должен читать их в каждой сессии без интеграций.
5. Обновляйте статус после отгрузки — актуальная история дешевле архива устаревших намерений.

Инструменты вроде Spec Kit и Kiro дают готовый каркас, но суть подхода не в инструменте: SDD — это дисциплина «сначала зафиксировать намерение, потом писать код», и она внедряется в любом стеке.

Мы переводим команды и проекты на spec-driven-процесс: шаблоны, правила, настройка AI-агентов, первые фичи вместе. Опишите свою ситуацию — подскажем, с чего начать.