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

Генерация кода перестала быть дефицитом: агент пишет двести строк за секунды. Дефицит сместился в другую сторону: точно сформулировать, что именно нужно сделать. Именно здесь ломается большинство AI-проектов — не на уровне кода, а на уровне постановки задачи. Spec-driven development — это инженерный ответ на эту проблему.

Что не так с vibe-coding

Vibe-coding — это когда вы даёте агенту задачу свободным текстом и итеративно дожимаете результат. Работает для прототипов и набросков. Ломается, когда фича касается реальных данных.

Типичная картина: вы просите агента сделать программу лояльности для кофейни. Агент генерирует код. Бонусы начисляются в долларах вместо баллов. Списание не проверяет баланс. Поля в базе не совпадают с моделью Client. Правите промпт — агент переписывает, ломает соседнее. Третья итерация, пятая, десятая.

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

Vibe-coding ставит вас в позицию, где думаете и переделываете после кода — в самом дорогом месте. Spec-driven development переносит мышление влево: до кода, когда цена ошибки минимальна.

Спека — это контракт, а не документация

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

Главный признак хорошей спеки: её нельзя понять двумя разными способами. Если два инженера (или два агента) прочитают её независимо и реализуют по-разному — спека плохая.

Что фиксирует хорошая спека для фичи лояльности:

• Бонусы начисляются в баллах (1 балл = 1 рубль покупки), не в денежных единицах.
• Списание невозможно, если баллов на балансе меньше, чем запрошено.
• Баллы округляются в меньшую сторону до целых.
• Пользователь видит баланс в личном кабинете в реальном времени.

Это уже не двусмысленно. Когда агент ошибётся — а он ошибётся — вы спорите не с кодом, а со спекой. Это несравнимо дешевле.

Связь со структурой контекста в Claude Code прямая: спека — это управляемый вклад в контекст агента. Подробнее о том, как устроен контекст и инструменты агента, — в статье что такое Claude Code.

Constitution: нерушимые правила проекта

Спека — это задача одной фичи. constitution (конституция проекта) — это принципы, которые действуют для всех фич сразу.

В spec-kit конституция живёт в .specify/memory/constitution.md. Примеры принципов из реального проекта:

• «Весь код покрыт тестами»
• «Стек — Next.js + NestJS + PostgreSQL»
• «Никаких платных API»
• «Каждая фича расширяет сквозной проект, а не живёт в вакууме»

Конституция стабильна. Она не меняется от фичи к фиче. Она приоритетнее любого отдельного решения.

Ключевая механика: на шаге планирования spec-kit делает Constitution Check — сверяет план фичи с принципами конституции. Если план нарушает хотя бы один принцип — это явный гейт. Его надо либо исправить, либо письменно обосновать отступление.

	Constitution	Spec
Область	Весь проект	Одна фича
Стабильность	Не меняется	Своя у каждой задачи
Смысл	«Как мы работаем»	«Что делаем»
Проверка	На каждом /plan (Constitution Check)	На ревью перед кодом

Аналогия с CLAUDE.md из настройки Claude через CLAUDE.md: CLAUDE.md — это как агент работает в проекте вообще. Constitution — это принципы команды, которые агент обязан соблюдать в каждом решении.

Поток spec-kit: пять шагов

Spec-kit реализует spec-driven development как конкретный инструментальный поток в Claude Code. Пять шагов, каждый с чётким артефактом на выходе.

/speckit.specify — превращает идею в свободном тексте в структурированную спеку: пользовательские истории (US), требования (FR), критерии успеха (SC). Неясности помечаются тегом [NEEDS CLARIFICATION]. Артефакт: spec.md.

/speckit.clarify — задаёт уточняющие вопросы и закрывает все [NEEDS CLARIFICATION]. Цель — убрать неоднозначность до единственного толкования. Артефакт: обновлённый spec.md без тегов.

/speckit.plan — из однозначной спеки строит технический план: стек, структура, модель данных. Прогоняет Constitution Check. Артефакт: plan.md.

/speckit.tasks — разбивает план на атомарные задачи по фазам, привязанные к требованиям FR/SC с зависимостями. Артефакт: tasks.md.

/speckit.implement — выполняет задачи по порядку, пишет код и помечает выполненное. Артефакт: код в ветке и PR.

Запомните роли, а не буквы команд: specify — что. clarify — добиваем однозначность. plan — как, со сверкой по конституции. tasks — режем на куски. implement — пишем код.

Поток не обязан быть линейным. Если на /implement всплыла дыра — это сигнал вернуться к спеке или плану, а не молча дописывать руками. Именно поэтому поток ценнее, чем один длинный промпт.

Сравнение spec-driven подхода с vibe-coding подробнее разобрано в vibe-coding vs spec-driven.

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

В учебном проекте курса — CoffeeCRM (Next.js + NestJS + PostgreSQL) — фича программы лояльности проходит ровно этот поток.

Сначала /speckit.specify превращает «копят бонусы, тратят на заказы» в документ с требованиями FR-001…FR-007 и критериями успеха SC-001…SC-004. Тег [NEEDS CLARIFICATION] появляется там, где исходный запрос не дал ответа: «округление баллов», «максимальный процент оплаты баллами».

Затем /speckit.clarify задаёт именно эти вопросы — не все подряд, а только непонятные. После ответов спека становится однозначной.

На /speckit.plan Constitution Check проверяет: используем ли платные API (нет), соответствует ли стек выбранному (да), покрыт ли модуль тестами (план включает). Только тогда переходим к задачам и коду.

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

Почему это важно именно сейчас

Узкое место AI-разработки — не скорость генерации кода. Это умение точно формулировать задачу. Spec-driven development — инженерный процесс для работы с этим узким местом: спека убирает неоднозначность до кода, конституция держит проект последовательным, поток spec-kit делает это воспроизводимым.

Хаотичная генерация — это не проблема агента. Это проблема отсутствия контракта между вами и агентом. Спека — этот контракт.

Если хотите освоить spec-driven development системно — от постановки спеки до деплоя реальной фичи — это тема пятого модуля полного курса по Claude Code.