Spec-driven development: как писать ТЗ, чтобы ИИ-агент не додумывал

Коротко: spec-driven development (разработка через спецификацию, SDD) — это подход, при котором вы сначала пишете точное ТЗ, а код генерирует ИИ-агент строго по нему. Спецификация становится источником истины, а код — производным артефактом. Такой порядок убирает главную боль вайбкодинга: агент перестаёт додумывать то, что вы забыли или поленились описать.

• Что решает: предсказуемость результата вместо «угадал / не угадал».
• Как работает: спека → план → задачи → код, с проверкой на каждом шаге.
• Чем писать: GitHub Spec Kit, Amazon Kiro или свой процесс на обычных .md-файлах.
• Кому нужно: всем, кто делает не одноразовый скрипт, а фичу, которую потом поддерживать.

## Что такое spec-driven development

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

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

Ключевая мысль SDD: спецификация — это источник истины, а код — всего лишь её реализация. Если код разошёлся со спекой, неправ код. Если спека неполная — виновата спека, а не «тупой агент». Это смещает фокус с «поругать нейросеть» на «доописать требования», а именно там и лежит настоящая работа.

У подхода есть несколько названий, которые вам встретятся: spec-driven development, SDD, разработка через спецификацию, spec-first. Речь об одном и том же.

## Почему вайбкодинг ломается на серьёзных задачах

ИИ-агент не читает ваши мысли. Он заполняет пробелы в ТЗ наиболее вероятным вариантом из обучающих данных — и именно поэтому «додумывает». Проблема не в том, что модель глупая. Проблема в том, что вы дали ей неполный контракт и надеетесь на телепатию.

Типичные места, где вайбкодинг разваливается:

• Граничные случаи. Вы сказали «форма логина». Агент сделал happy path. Что при неверном пароле, пустом поле, блокировке аккаунта, третьей неудачной попытке — он додумал, и обычно не так, как вам нужно.
• Неявные бизнес-правила. «Скидка для новых пользователей» — а кто считается новым? Первые 30 дней? Без заказов? Это решение, а не верстка, и агент примет его за вас.
• Согласованность между сессиями. В новом чате агент не помнит вчерашних договорённостей и переизобретает их заново, часто иначе.
• Молчаливый scope creep. Агент «на всякий случай» добавляет обработку ошибок, флаги, абстракции, которых вы не просили, — и код растёт в стороны.

По данным 2026 года, команды, которые перешли на spec-driven workflow, сообщают о 3–10-кратном росте доли задач, решённых агентом с первого раза на нетривиальных фичах. Причина простая: чем меньше остаётся неоднозначности, тем меньше агент угадывает.

## Как работает SDD: спека → план → задачи → код

Разработка через спецификацию — это не «написать один большой документ и швырнуть агенту». Это цикл из четырёх шагов, где на каждом переходе стоит проверка человеком.

1. Спецификация (что и зачем). Описываем требования: что система должна делать, для кого, при каких условиях, что считается успехом. Здесь нет ни слова про технологии — только поведение.
2. План (как). По утверждённой спеке агент (или вы) готовит технический план: архитектура, стек, структура данных, границы модулей. Здесь спека превращается в инженерные решения.
3. Задачи (по шагам). План разбивается на маленькие атомарные задачи, каждую из которых можно выполнить и проверить отдельно. Не «сделай авторизацию», а «добавь модель User с полями X», «добавь эндпоинт логина», «добавь обработку неверного пароля».
4. Реализация (код). Агент берёт задачи по одной и пишет код. Каждая задача трассируется обратно к пункту спеки — так видно, что ничего не потерялось и ничего лишнего не добавилось.

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

## Из чего состоит хорошая спека

Устоявшийся формат (его используют и Amazon Kiro, и многие самодельные процессы) — три файла на одну фичу:

• requirements.md — требования. Что должно происходить, с точки зрения пользователя и бизнеса. Никакого кода и технологий.
• design.md — дизайн/архитектура. Как это реализовать: модели данных, API, потоки, зависимости, обработка ошибок.
• tasks.md — задачи. Пронумерованный список атомарных шагов со ссылками на пункты требований.

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

## EARS: как писать требования без воды

Главная беда обычных ТЗ — размытые формулировки: «система должна удобно обрабатывать ошибки». Для агента «удобно» — это ничего. Чтобы требования были однозначными, используют нотацию EARS (Easy Approach to Requirements Syntax). Идея — писать каждое требование по шаблону с триггером и обязательным поведением.

Базовые шаблоны EARS:

• Когда <событие>, система должна <поведение>.
• Если <условие>, то система должна <поведение>.
• Пока <состояние>, система должна <поведение>.
• Где <функция включена>, система должна <поведение>.

Сравните. Плохо: «форма логина с валидацией». Хорошо по EARS:

• Когда пользователь отправляет форму с корректными email и паролем, система должна создать сессию и перенаправить на /dashboard.
• Если пароль неверный, система должна показать ошибку «Неверный email или пароль» без указания, что именно не так.
• Если было 5 неудачных попыток за 15 минут, система должна временно заблокировать вход на 15 минут.
• Пока идёт запрос на сервер, система должна блокировать кнопку и показывать индикатор загрузки.

Разница очевидна: во втором случае агенту нечего додумывать. Каждое поведение задано триггером и результатом, и по нему же потом пишется тест.

## Как формализовать ТЗ, чтобы агент не додумывал

Несколько приёмов, которые работают вне зависимости от инструмента.

Описывайте поведение, а не пожелания. «Быстрый поиск» — пожелание. «Поиск возвращает результаты за ≤300 мс на выборке до 10 000 записей» — поведение, которое можно проверить.

Явно перечисляйте граничные случаи. Пустой ввод, максимальная длина, дубликаты, отсутствие прав, потеря сети, параллельные запросы. Всё, что не описано, агент закроет случайно.

Задавайте, чего делать НЕ нужно. Отдельный раздел «вне рамок» экономит вагон времени: «не добавляй ролевую модель», «не трогай платежи», «без кэширования на этом этапе». Это прямой антидот от scope creep.

Фиксируйте решения, а не только требования. Если выбрали JWT вместо сессий — запишите это и почему. Иначе в следующей сессии агент переизобретёт выбор.

Приводите примеры входа и выхода. Один конкретный пример JSON-ответа стоит трёх абзацев описания. Агент отлично работает по образцу.

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

## Пример: было и стало

Чтобы разница не осталась абстрактной, вот один и тот же запрос в двух вариантах.

Было (вайбкодинг):

Сделай экспорт заказов в CSV.

Агент выдаёт кнопку, которая выгружает все заказы, все поля, без пагинации, без учёта прав, с датами в непонятном формате. На 100 000 заказов страница падает по таймауту.

Стало (спека):

Требование. Когда менеджер нажимает «Экспорт», система должна сформировать CSV с заказами за выбранный период. Поля: id, дата (ISO 8601), сумма (в копейках), статус, email клиента. Другие поля не включать. Права: экспорт доступен только роли manager и выше. Иначе — 403. Объём: до 50 000 строк за один экспорт. Больше — генерировать файл в фоне и присылать ссылку. Граничные случаи: пустой период → файл только с заголовками; клиент без email → пустая ячейка, не падать. Вне рамок: экспорт в Excel, выбор колонок, планировщик — не в этой задаче.

Второй вариант длиннее, но именно он экономит время: агент собирает то, что нужно, с первого раза, а вы не ловите баги в проде через неделю.

## Инструменты spec-driven development в 2026

SDD можно вести хоть в блокноте, но в 2026 под него появились специальные инструменты.

GitHub Spec Kit — открытый тулкит, который добавляет агенту команды /specify, /plan, /tasks, /implement и ведёт вас по всему процессу. Работает поверх любого агента (Claude Code, Copilot, Gemini CLI и других). К середине 2026 репозиторий перевалил за 111 000 звёзд — показатель того, насколько тема выстрелила. Хороший выбор, если хотите готовый процесс, а не изобретать свой.

Amazon Kiro — IDE, построенная вокруг спек. Она по вашему запросу генерирует requirements.md (в том числе в EARS-формате), design.md и tasks.md, а затем выполняет задачи по одной. Подходит тем, кто хочет, чтобы инструмент сам вёл структуру спеки.

Свой процесс на .md-файлах. Никакой магии в тулкитах нет: можно держать папку specs/ с теми же тремя файлами и правилом «агент не пишет код, пока спека не одобрена». Это отлично сочетается с AGENTS.md, где вы один раз описываете, как агент должен работать со спеками в вашем проекте.

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

## Частые ошибки и анти-паттерны

• Спека-роман. Документ на 20 страниц, который никто не читает и который устарел на второй день. Спека должна быть ровно настолько подробной, насколько нужно, чтобы убрать неоднозначность, — и не длиннее.
• Технологии в требованиях. «Использовать Redis» в requirements.md — ошибка. Требование говорит что (кэшировать результат на 5 минут), решение про Redis живёт в design.md.
• Спека, которую не обновляют. Если код разошёлся со спекой и вы правите только код, спека мертва. Тогда весь подход теряет смысл: источника истины больше нет.
• Атомарные задачи, которые не атомарны. «Сделать бэкенд» — не задача. Если шаг нельзя проверить одним тестом или одним взглядом на diff, его надо дробить дальше.
• Пропуск ревью переходов. Дать агенту сразу сгенерировать спеку, план, задачи и код без остановок — это тот же вайбкодинг, только с лишними файлами. Ценность именно в утверждении на каждом стыке.
• SDD для одноразовых скриптов. Писать три файла спеки ради разового парсера — оверинжиниринг. Инструмент должен быть под масштаб задачи.

## Чеклист готовности спеки

Перед тем как пускать агента в код, пройдитесь по списку:

• Каждое требование описывает поведение через триггер и результат (стиль EARS).
• Перечислены граничные случаи: пустые данные, лимиты, ошибки, права доступа.
• Есть раздел «вне рамок» — что делать НЕ нужно.
• Все неоднозначные термины определены.
• Есть хотя бы один пример входа и выхода.
• Зафиксированы принятые технические решения и их причины.
• Задачи атомарны и каждая ссылается на пункт требований.
• Понятно, что считается «сделано»: какие тесты или проверки должны пройти.

Если по чеклисту всё зелёное — агент почти не будет додумывать. Если есть пробелы — именно там он и ошибётся.

## Когда spec-driven development избыточен

Честно: SDD нужен не всегда. Для разового скрипта, эксперимента на выброс, крошечной правки или прототипа, который вы завтра выкинете, полноценная спека — это лишние движения. Здесь вайбкодинг быстрее и уместнее.

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

## Частые вопросы

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

Это не то же самое, что старое доброе ТЗ? По духу — да, но с двумя отличиями. Спека пишется в машиночитаемом, однозначном виде (EARS, примеры, атомарные задачи) специально под ИИ-агента, и она живёт рядом с кодом, а не в забытом документе. Это ТЗ, из которого напрямую генерируется код.

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

С чего начать без специальных инструментов? Заведите папку specs/, на каждую фичу — файлы requirements.md, design.md, tasks.md. Пропишите в AGENTS.md правило: агент не пишет код, пока спека не одобрена. Этого достаточно, чтобы почувствовать эффект.

Нужно ли обновлять спеку после изменений? Обязательно. Как только вы правите поведение только в коде, спека перестаёт быть источником истины и весь подход рушится. Меняете поведение — сначала спека, потом код.

## Вывод

Spec-driven development — это не про бюрократию и не про «больше документов». Это про то, чтобы перенести момент принятия решений из середины генерации кода в начало, где эти решения дёшево менять. Вы один раз честно отвечаете на вопросы «что должно происходить, при каких условиях и что считается успехом» — и агенту просто не остаётся места, чтобы додумать за вас.

Начните с малого: возьмите следующую нетривиальную фичу, напишите на неё короткую спеку по EARS, добавьте раздел «вне рамок» и пример входа-выхода. Сравните результат с тем, как обычно. Скорее всего, агент попадёт в цель с первого раза — а вы поймёте, что «тупая нейросеть» всё это время просто выполняла ваше неполное ТЗ.

## Что читать дальше

• AGENTS.md: единый источник истины для ИИ-агентов
• Memory Bank: хранение контекста для ИИ в разработке проектов
• Как писать тесты через ИИ
• Подготовка проекта с помощью ИИ: от идеи до документации