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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чем 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 с критериями приемки и целями, которых не следует достигать
  • Машиночитаемая спецификация с валидацией схемы
  • Контрактные тесты, полученные непосредственно из спецификации
  • Формальная спецификация с автоматическим доказательством

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

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

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

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

Подписаться

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