От слов к коду: Гайд по Spec-Driven Development и OpenSpec

# Что такое OpenSpec и как работает разработка через спецификацию?

В последние годы термин Spec-Driven Development (SDD) всё чаще появляется в дорожных картах крупных технологических компаний. Иногда это эксперимент нескольких отделов, а иногда спецификация становится обязательным входным контролем для любой задачи. Однако представление о том, что под SDD подразумевается лишь написание нескольких Markdown-файлов перед началом кодинга, часто оказывается ошибочным.

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

Иерархия требований и природа спецификации

Чтобы говорить на одном языке с разработчиками и AI-агентами, необходимо чётко разграничить уровни абстракции требований. Система существует не сама по себе, а ради выполнения конкретных целей.

1. Бизнес-требования отвечают на вопрос «зачем?». Они описывают цель изменений для организации. Например, владельцу ветеринарной клиники необходимо автоматизировать учёт истории посещений животных для снижения бумажной работы и улучшения сервиса. 2. Пользовательские требования описывают «что». Они фиксируют возможности системы для конечного пользователя. В нашем примере администратор должен иметь интерфейс для регистрации новых животных и поиска по базе. 3. Системные требования объясняют «как» система должна вести себя, чтобы удовлетворить предыдущие уровни. Сюда входят поведенческие сценарии: система принимает данные о визите, сохраняет их в базу и отображает в ленте. 4. Нефункциональные/Технические требования устанавливают ограничения и характеристики реализации: время отклика не более 100 мс, поддержка одновременной работы десяти администраторов, использование PostgreSQL.

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

Архитектура OpenSpec: от изменений к коду

OpenSpec формализует процесс разработки через концепцию Changes (Изменений). В отличие от традиционного подхода, где спецификация создаётся параллельно или после кодинга, здесь изменение начинается с намерения и заканчивается лишь после того, как код проверен и заархивирован.

В основе лежат два типа спецификаций: * Main Specs: «Сборник законов» системы. Они описывают текущее полное поведение приложения и служат эталоном для всех будущих изменений. * Delta Specs: Описание разницы между текущим состоянием и желаемым. Они содержат только те требования, которые нужно добавить, изменить или удалить в рамках конкретной задачи.

Каждая спецификация состоит из требований (Requirements) и сценариев (Scenarios). Требования формулируются через модальности вроде SHALL или MUST, описывая наблюдаемое поведение. Сценарии используют формат GIVEN/WHEN/THEN для фиксации критериев приёмки. Например: GIVEN список ветеринаров заполнен, WHEN отправлен запрос GET /api/vets, THEN система возвращает 200 OK и JSON-массив объектов.

Цикл разработки: Propose, Apply, Archive

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

Этап 1: Propose (Предложение) Процесс начинается с команды /opsx:propose, в которую передаётся промпт с описанием задачи. Если требования уже зафиксированы в корпоративных системах, агент сам их загружает; в противном случае он создаёт описание с нуля.

Агент анализирует Main Specs и генерирует Delta Specs. Затем он изучает код репозитория, чтобы понять контекст зависимостей и архитектуру, создавая технические артефакты: * design.md: Техническое решение, как реализовать фичу. * tasks.md: План работ, включающий задачи на кодирование, тестирование и ревью.

На этом этапе критически важно проверить сгенерированные артефакты. Агент должен корректно интерпретировать требования, предусмотреть guardrails (барьеры) вроде unit-тестов и архитектурных проверок ArchUnit, а также назначить другому агенту ревью кода. После согласования плана переходим к реализации.

Этап 2: Apply (Применение) Команда /opsx:apply запускает процесс написания кода. Агент следует плану из tasks.md, используя имеющиеся знания о стеке технологий (например, Spring Boot, Java) для генерации сущностей, контроллеров и миграций базы данных.

Разработчик на этом этапе выполняет роль редактора и тестировщика. Необходимо вручную проревьювать критические компоненты (модели, сервисы), проверять наличие end-to-end тестов и запускать инструменты мутационного тестирования (например, PITest). Важно отметить: в этот момент код закоммивается, но Pull Request (PR) пока не создаётся, так как спецификации ещё не обновлены.

Этап 3: Sync & Archive (Синхронизация и Архивация) Перед закрытием задачи требуется обновить «источник истины». Команда /opsx:sync переносит изменения из Delta Specs в Main Specs. Это гарантирует, что следующим AI-агентам, которые будут работать над новой фичей, будет известно о существовании уже реализованных функций.

После синхронизации вызывается команда /opsx:archive. Изменение перемещается в архив, а все промежуточные артефакты сохраняются для истории. Только после этого изменения кода можно коммитить в основную ветку и создавать PR.

Заключение

Открытый фреймворк OpenSpec демонстрирует, как формальные описания требований становятся драйвером автоматизации разработки. Метод Spec-Driven Development позволяет снизить количество ошибок, связанных с непониманием задач, заставляя AI-агентов ориентироваться на чёткие сценарии, а не на расплывчатые инструкции. Подход доказывает, что в эпоху генеративного ИИ документация трансформируется из бюрократической нагрузки в активный инструмент управления качеством ПО.