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

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

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

Подход вырос из проблемы вайб-кодинга. Когда разработчик описывает задачу агенту в чате, требования остаются в истории переписки. Агент заполняет пробелы догадками, и через неделю никто не помнит, почему код устроен именно так. Спека фиксирует требования в файле, который лежит в репозитории, проходит ревью и меняется вместе с кодом.

Зачем спека, если агент и так понимает задачу

• Агент не додумывает молча. Если в спеке нет ответа, агент задаёт вопрос до начала работы. Без спеки он выбирает вариант сам, и ошибка всплывает на ревью или в production.
• Ревью становится короче. Ревьюер сверяет код со спекой и acceptance criteria. Ему не нужно восстанавливать замысел по диффу.
• Дефект можно отследить до причины. Если в спеке ошибка, чинят спеку или её шаблон. Если спека верная, а код нет, чинят правила и проверки в harness.
• Работу можно передать другому агенту. Спека отделяет «что делаем» от «как делаем», поэтому одну задачу могут вести планировщик, исполнитель и ревьюер.

Как выглядит процесс

Большинство инструментов SDD используют одну последовательность шагов.

1. Specify. Описать, что нужно и зачем: пользовательские сценарии, требования, acceptance criteria. Без выбора технологий.
2. Clarify. Агент находит неясные места и задаёт вопросы. Ответы записываются в спеку.
3. Plan. Технический план: архитектура, изменения в данных, контракты, риски.
4. Tasks. Разбивка плана на небольшие задачи, каждую можно проверить отдельно.
5. Implement. Агент выполняет задачи, тесты и ревью проверяют результат по acceptance criteria.

Человек участвует на переходах: утверждает спеку, принимает план, смотрит результат. Внутри шагов работает агент.

Что писать в спецификации

Хорошая спека для агента короткая и проверяемая. Минимальный набор разделов:

• Контекст. Зачем задача, кто пользователь, какую проблему решаем.
• Требования. Что система должна делать, нумерованным списком.
• Acceptance criteria. Конкретные проверки в формате «дано, когда, тогда». Каждый критерий связан с тестом. Как агенту писать такие тесты — в статье про генерацию тестов.
• Вне задачи. Что в этой задаче не делаем, чтобы агент не расширял объём.
• Ограничения. Производительность, безопасность, совместимость, какие модули трогать нельзя.
• Открытые вопросы. Агент дописывает их на шаге clarify, человек отвечает.

Пример фрагмента спеки:

# Сводный отчёт по сделкам за день

## Требования
1. Отчёт группирует сделки по дате в часовом поясе клиента.
2. Сумма за день совпадает с суммой сделок клиента за эти сутки.

## Acceptance criteria
- AC-1. Дано: клиент в UTC+3, сделка в 23:40 по местному времени 14.03.
  Когда: строим отчёт за 14.03.
  Тогда: сделка входит в отчёт за 14.03.
  Тест: reports/test_daily.py::test_local_day_boundary
- AC-2. Дано: 1000 сделок за сутки.
  Тогда: отчёт строится быстрее 2 секунд.

## Вне задачи
- Экспорт в Excel.
- Изменение схемы таблицы deals.

Критерий AC-1 появился после реального дефекта: агрегация шла по серверному UTC, и поздние сделки попадали в соседние сутки. Когда такой критерий записан в шаблон спеки, агент учитывает часовой пояс с первой задачи.

Три уровня SDD

Бригитта Бёкелер из Thoughtworks в разборе инструментов SDD выделяет три уровня того, насколько серьёзно команда относится к спеке:

Большинству команд стоит начинать со spec-first на новых задачах и переходить к spec-anchored для модулей, которые часто меняются. Spec-as-source пока остаётся экспериментом.

Инструменты: Spec Kit, Kiro и markdown в репозитории

GitHub Spec Kit

Spec Kit — открытый набор шаблонов и команд от GitHub. Он ставится в репозиторий и работает с агентом, которым команда уже пользуется: Copilot, Claude Code, Cursor, Gemini CLI и другими. Процесс идёт через команды /speckit.specify, /speckit.plan, /speckit.tasks и /speckit.implement. Перед ними пишется constitution — общие принципы проекта, которые действуют для всех спек.

Kiro

Kiro — среда разработки от AWS на базе Code OSS со встроенным процессом SDD. Спека в Kiro состоит из трёх файлов: требования, дизайн и задачи. Требования пишутся в формате EARS («когда …, система должна …»). Kiro подходит, если команда готова сменить IDE. Если нет, тот же процесс собирают на Spec Kit или на своих шаблонах.

Свои шаблоны в markdown

Для старта инструмент не обязателен. Папка specs/ в репозитории, шаблон спеки и правило в AGENTS.md «перед реализацией прочитай спеку задачи и сверь план с acceptance criteria» дают основную часть эффекта.

Что делать, если задачи живут в Jira

В крупных компаниях Jira часто нельзя заменить: через неё идут планирование, отчётность и согласования. Спеки в этом случае встраивают рядом:

• Тикет в Jira остаётся точкой учёта: приоритет, исполнитель, статус.
• Спека лежит в репозитории, тикет ссылается на неё, а спека — на тикет.
• Агент читает тикет через интеграцию и создаёт черновик спеки, человек его утверждает.
• Изменения требований вносят в спеку через merge request, чтобы история была в git.

Какой вариант подходит, решается на диагностике: где команда реально договаривается о требованиях и кто сможет поддерживать спеки.

Когда SDD не нужен

• Правка опечатки, обновление зависимости, мелкий рефакторинг внутри модуля. Хватит хорошего AGENTS.md и тестов.
• Прототип, который выбросят через неделю.
• Исследовательская задача, где требования появятся только после эксперимента. Сначала спайк, потом спека по его итогам.

Чем больше модулей и команд затрагивает изменение, тем подробнее спека.

Вопросы