Что такое спецификация-ориентированная разработка? Спецификация как источник истины

«Спецификация как источник истины, а не вспомогательный документ».

Содержимое страницы

Разработка на основе спецификаций (Spec-Driven Development) — это одна из тех идей, к которым инженеры по софту обращались ранее, а затем откладывали, когда усилия переставали приносить отдачу.

В 2025 году всё изменилось: появились ИИ-агенты для написания кода, и отсутствие явного намерения стало обходиться дорого. Промпты эфемерны. Сессии агентов сбрасываются. Код меняется, но логика, стоящая за ним, исчезает. Спецификация — это артефакт, который предотвращает такое положение дел.

Что такое разработка на основе спецификаций – спецификация как источник истины для ИИ-агентства

Спецификация становится источником истины

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

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

Это не новая идея. Формальные методы, проектирование по контракту и BDD (Behavior-Driven Development) содержат свои версии этого подхода. Новым является практическая мотивация: ИИ-агентам для написания кода необходимы явный, долговременный контекст, чтобы производить корректный и согласованный результат. Промпты слишком эфемерны. Спецификация — единственный артефакт, способный передать намерение между сессиями агентов, между членами команды и во времени.

Что на самом деле означает разработка на основе спецификаций

Разработка на основе спецификаций, обычно сокращаемая до SDD, — это рабочий процесс, в котором версионная спецификация направляет или генерирует реализацию. Спецификация пишется и рецензируется до того, как агент напишет код. Она фиксирует:

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

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

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

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

Три термина охватывают разные точки спектра использования спецификаций:

Spec-first означает написание полной спецификации до начала любой реализации. Это строгая интерпретация, и если не делать это осторожно, она ближе всего к каскадной модели (waterfall).

Spec-anchored означает поддержание спецификации в синхроне с реализацией на протяжении всего жизненного цикла функциональности. Спецификация обновляется по мере изменения решений. Это самая практичная версия для большинства команд.

Spec-as-source означает генерацию или валидацию реализации из спецификации, либо через ИИ-агентов, либо через инструменты, которые проверяют код на соответствие ограничениям спецификации. Именно в этом направлении движутся инструменты, такие как GitHub Spec Kit и Kiro, каждый из которых делает свой выбор в балансе между переносимостью и интегрированным руководством в IDE. Пакеты навыков, такие как Superpowers, ближе к концу спектра spec-anchored — они автоматически обеспечивают дисциплину рецензирования, а не генерируют код напрямую из спецификации.

Почему SDD важен сейчас

Честный ответ состоит в том, что SDD не убеждает одиночного разработчика, создающего скрипт на один день. Переработка не окупается.

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

Все три условия становятся все более частыми в разработке с ИИ-поддержкой.

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

Генерация кода дёшева; решение, что строить, по-прежнему сложно. Узким местом в разработке с ИИ-поддержкой больше не является набор текста — это знание того, что строить и как ограничивать агента. SDD переносит усилия туда, где они важны: явное определение намерения до начала генерации.

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

**Vibe coding быстрее для одноразовой работы; статья SDD vs Vibe Coding описывает, когда добавлять спецификации, а когда свободно использовать промпты.

Основные артефакты

SDD производит четыре типа артефактов. Каждый снижает свой вид неоднозначности до того, как агент коснется кода:

  • Спецификация требований — проблема, пользователи, цели, нецели, критерии приемки
  • Проектная спецификация — архитектура, модель данных, контракты API, ограничения безопасности для данной функциональности
  • План задач — небольшие срезы реализации с зависимостями и критериями валидации
  • Запись прослеживаемости — отображение от критериев приемки к тестам, от проектных решений к файлам, от задач к коммитам

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

Чем SDD отличается от документации

Самое распространенное заблуждение — рассматривать артефакты SDD как документацию. В традиционном смысле это не документация.

Документация описывает. Она рассказывает, что делает система, как ею пользоваться и что она содержит. Она пишется постфактум и обновляется, когда система меняется.

Спецификации ограничивают. Спецификация говорит агенту, что ему разрешено строить и что запрещено. Она является авторитетной до начала реализации. Она валидируется после завершения реализации. Спецификация, которая описывает то, что было построено на самом деле, а не ограничивает то, что должно быть построено, уже не выполнила своей цели.

Исполняемые спецификации направляют генерацию и валидацию. Лучшие спецификации SDD достаточно близки к машинно-читаемым, чтобы агент мог реализовывать их, а набор тестов — проверять. Критерий приемки, записанный как «эндпоинт должен отклонять неавторизованные запросы с ответом 401», — это исполняемая спецификация; «эндпоинт безопасен» — это документация.

Записи решений — ADR, PDR и DDR — дополняют артефакты SDD, но служат другой цели. Записи решений фиксируют, почему был сделан выбор и что было отклонено. Спецификации SDD фиксируют, что строить и как это верифицировать. Оба типа принадлежат в репозитории. Вместе они дают ИИ-агентам полную картину: текущее намерение и логику, стоящую за ним.

Чем SDD отличается от TDD

Тест-ориентированная разработка (TDD) и разработка на основе спецификаций (SDD) часто путают, потому что оба подхода производят явные артефакты до существования кода. Разница в отправной точке.

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

SDD начинается с намерения. До того, как существуют тесты, до того, как приняты архитектурные решения, спецификация отвечает на вопросы: у кого эта проблема, как выглядит корректное поведение, что явно вне области. Затем спецификация определяет, какие тесты писать, поэтому хороший SDD и хороший TDD дополняют, а не конкурируют друг с другом.

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

Чем SDD отличается от BDD

Поведенческая разработка (BDD) использует сценарии на естественном языке — обычно в формате Gherkin — для описания ожидаемого поведения с точки зрения пользователя. Эти сценарии закрывают разрыв между бизнес-намерением и технической реализацией.

SDD шире. Он включает описания поведения (которые могут использовать язык в стиле BDD или обычный текст), но также охватывает архитектурные решения, модели данных, ограничения безопасности, планирование задач и прослеживаемость. BDD может быть полезным форматом для написания критериев приемки внутри спецификации требований SDD. Спецификация — это контейнер; сценарии BDD — один из способов написать то, что в него помещается.

Различие важно на практике: инструменты BDD сфокусированы на том, чтобы сделать сценарии исполняемыми. Практика SDD сфокусирована на том, чтобы сделать намерение долговременным — между инструментами, между сессиями и между членами команды.

Чем SDD отличается от формальных методов

Формальные методы используют математическую нотацию и автоматическую верификацию для доказательства свойств программных систем. Они чрезвычайно строгие и чрезвычайно дорогие для большинства контекстов производственной разработки.

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

Отношение представляет собой спектр:

  • Неформальная прозаическая спецификация (минимально жизнеспособный SDD)
  • Структурированный markdown с критериями приемки и нецелями
  • Машинно-читаемая спецификация с валидацией по схеме
  • Контрактные тесты, выведенные напрямую из спецификации
  • Формальная спецификация с автоматическим доказательством

Большинство команд работают в середине этого спектра. Цель — не математическая строгость, а сделать намерение достаточно явным, чтобы ИИ-агент мог реализовать его, а человеческий рецензент — проверить результат.

Преимущества разработки на основе спецификаций

Меньше дрейфа намерения. Спецификация — это эталон. Когда агент отклоняется — и он будет — у рецензента есть с чем сравнить реализацию. Без спецификации дрейф невидим, пока что-то не сломается.

Лучший выход ИИ. Агенты, получившие явные ограничения, нецели и критерии приемки, производят реализации, более близкие к намерению, и их проще исправить, когда они ошибаются. Качество контекста напрямую определяет качество вывода.

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

Согласованность команды. Когда несколько человек или агентов работают над одной функциональностью, спецификация — это общий контракт. Без нее каждый участник оптимизирует локально, и части могут не подойти друг к другу.

Лучшее планирование тестов. Критерии приемки в спецификации напрямую отображаются на тестовые случаи. Покрытие тестами становится вопросом покрытия спецификацией: покрыт ли каждый критерий приемки хотя бы одним тестом?

Долговременная передача. Когда функциональность меняет руки — между инженерами, между сессиями агентов, между спринтами — спецификация является артефактом передачи. Она фиксирует, что было решено, что было вне области и что осталось верифицировать.

Затраты на разработку на основе спецификаций

Предварительные усилия. Написание хорошей спецификации до написания любого кода занимает время. Для маленьких функциональностей эти накладные расходы реальны и иногда не стоят того.

Ложная уверенность. Спецификация, которая существует, но не валидирована по реализации, дает ложное чувство правильности. Устаревшие спецификации иногда хуже, чем отсутствие спецификации: они вводят в заблуждение рецензентов и агентов, которые их читают.

Устаревшие спецификации. Спецификации дрейфуют, когда команда относится к ним как к планировочным артефактам, а не к живым документам. Обновление спецификации, когда реализация отличается от дизайна, — не опционально; именно это отличает SDD от документации, которая накапливается и гниет.

Сгенерированная бюрократия. ИИ-агенты могут быстро генерировать исчерпывающие списки задач и многословные спецификации. Спецификация из 200 задач, сгенерированная за тридцать секунд, — это не полезная спецификация; это генератор бюрократии. Хороший SDD требует суждения о том, что специфицировать, а что оставить неявным.

Зависимость от инструментов. Некоторые инструменты SDD имеют сильное мнение о формате, структуре файлов и рабочем процессе. Спецификация, написанная в проприетарном формате, труднее переносится между инструментами, чем markdown-файл с четкими заголовками и критериями приемки.

Заключение

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

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

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

SDD находится на пересечении практики документации, архитектуры тестирования и дизайна кода — все это описано в кластере Архитектура приложений в производстве наряду с записями решений, дизайном API и паттернами доступа к данным.

Полезные ссылки

Подписаться

Получайте новые материалы про системы, инфраструктуру и AI engineering.