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

Спецификация как источник истины, а не побочный документ

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

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

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

Что такое разработка, управляемая спецификациями – спецификация как источник правды для ИИ

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

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

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

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

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

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

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

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

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

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

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

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

Spec-as-source (Спецификация как источник) означает генерацию или валидацию реализации из спецификации, либо через агентов ИИ, либо через инструменты, которые проверяют код на соответствие ограничениям спецификации. Именно в этом направлении движутся такие инструменты, как GitHub Spec Kit и Kiro.

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

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

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

Все три условия становятся все более распространенными при разработке с помощями ИИ.

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

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

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

Vibe coding работает, пока работает. Для прототипов и одноразовой работы ad-hoc промптинг быстрее и уместен. Как только фича требует ограничений безопасности, архитектурных решений для нескольких файлов или передачи дела команде, отсутствие спецификации становится основным источником отклонений и дефектов. Сравнение см. в SDD vs Vibe Coding.

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

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

Спецификация требований. Формулировка проблемы, затронутые пользователи, цели, явные non-goals и критерии приемки. Non-goals так же важны, как и цели — они говорят агенту, что не нужно строить, и предотвращают располнение scope. Критерии приемки достаточно точны, чтобы каждый из них соответствовал хотя бы одному тесту.

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

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

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

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

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

Самая распространенная ошибка — считать артефакты SDD документацией. Они не являются документацией в conventional смысле.

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

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

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

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

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

Разработка, управляемая тестами (Test-Driven Development) и разработка, управляемая спецификациями, часто путаются, так как обе производят явные артефакты до существования кода. Разница заключается в отправной точке.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Затраты разработки, управляемой спецификациями

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

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

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

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

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

Заключение

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

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

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

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

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

Подписаться

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