Что такое OpenSpec? Полный гайд по Spec-Driven Development

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

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

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

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

Немного теории

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

Начнём с понятия «требование». Требование — это описание того, что должна делать система. Хорошее требование описывает наблюдаемый и проверяемый результат.

Требования бывают разного уровня:

• Бизнес-требования объясняют, зачем компании нужно изменение и какого результата она хочет достичь

• Пользовательские требования описывают, что пользователь должен иметь возможность сделать с помощью системы

• Системные требования определяют, как система должна вести себя, чтобы выполнить пользовательские и бизнес-требования

• Нефункциональные/технические требования фиксируют измеримые характеристики и ограничения реализации: производительность, нагрузку, технологии, протоколы, архитектурные правила и требования к инфраструктуре

Разработчик в основном работает с системными и нефункциональными/техническими требованиями: либо реализует уже сформулированные, либо формирует их на основе пользовательских и бизнес-требований.

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

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

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

Дальше формируем системные требования: как именно администратор создаёт владельца, добавляет ему домашних животных, регистрирует визит и редактирует его данные. На этом уровне уже могут появиться пользовательские сценарии и mockup-ы интерфейсов.

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

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

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

Мы развиваем собственный мультиагентный AI-плагин, и поддержка Spec-Driven Development – это одно из наших приоритетных направлений.

Все примеры и скриншоты ниже сделаны в OpenIDE с нашим AI-плагином. Подробнее о плагине и самой IDE можно прочитать тут.

OpenSpec

OpenSpec — это открытый фреймворк для Spec-Driven Development. Он помогает фиксировать требования в спецификациях и поддерживать их актуальность на всём жизненном цикле: от момента, когда идея нового функционала только возникла в голове продукта, до её реализации в приложении. В OpenSpec каждое требование описывает ожидаемое поведение системы и дополняется сценариями с критериями приёмки.

В OpenSpec есть два вида спецификаций: main specs и delta specs. Main specs хранят описание текущего поведения системы и выступают источником истины (source of truth). Delta specs создаются для конкретного изменения и описывают только разницу между текущим и желаемым состоянием: какие требования нужно добавить, изменить, удалить или переименовать.

Сама спецификация состоит из набора требований (requirements), и у каждого требования должен быть хотя бы один сценарий (scenario). И требования, и сценарии оформляются отдельными заголовками: ### Requirement: и #### Scenario: соответственно. Требование описывает одно наблюдаемое и проверяемое поведение системы, формулируется через SHALL или MUST и не содержит деталей реализации. Например: The system SHALL return the collection of all stored veterinarians.

Сценарий, в свою очередь, задаёт критерии приёмки требования и описывает конкретные условия и ожидаемый результат в формате GIVEN/WHEN/THEN — либо WHEN/THEN, если предусловий нет. Например, сценарий List with existing records определяет, что запрос GET /api/vets при наличии ветеринаров должен вернуть 200 OK и JSON-массив со всеми записями.

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

Естественно, в эпоху AI руками мы пишем разве что промпты — да и те иногда просто наговариваем. Поэтому самое время разобраться, как генерировать спецификации с помощью OpenSpec.

OpenSpec Change

Любая доработка в OpenSpec осуществляется через создание «изменения» (change). Внутри него OpenSpec хранит delta spec и связанные с доработкой артефакты. По умолчанию это proposal — фиксирует намерение и границы изменения; design — описывает техническое решение; tasks — задаёт последовательность работ, которой будет следовать агент. Этот список не исчерпывающий: при необходимости его можно дополнить артефактами, которые нужны именно вам.

Давайте создадим наше первое изменение. В качестве примера будем разрабатывать типовое приложение — ветеринарную клинику. За основу возьмём чистый проект на Spring Boot 4.1.1 и Java 26 с подключёнными Spring Web MVC, Spring Data JPA, Validation и PostgreSQL. Пока это пустая заготовка без доменной модели и endpoint-ов. Первым изменением добавим хранение информации о ветеринарах и CRUD REST API для работы с ними.

Но прежде чем создавать первое изменение (change), необходимо инициализировать OpenSpec в репозитории.

Для этого нам потребуется OpenSpec CLI. Инструкцию по установке для вашей платформы и ОС можно найти в официальной документации.

Далее выполняем команду openspec init и выбираем агентов, которых будем использовать при разработке приложения.

Что произошло под капотом? openspec init создал в корне репозитория каталог openspec/, в котором будут храниться конфигурация проекта, актуальные спецификации и будущие изменения. Заодно CLI установил для выбранных агентов skill-ы и slash-команды. Спецификаций на этом этапе ещё нет: init только подготовил структуру проекта и инструкции, по которым будут работать агенты.

Дальше пройдём полный цикл изменения, состоящий из трёх этапов: Propose, Apply и Archive. Каждый из них разберём отдельно.

Propose

Чтобы создать первое изменение, воспользуемся командой /opsx:propose и передадим ей промпт с описанием того, что хотим изменить в приложении.

/opsx:propose Добавь модель для хранения информации о ветеринарах и CRUD REST API для создания, получения, изменения и удаления записей о них.

В реальном проекте описание задачи обычно уже есть в тикете или на странице Wiki/Confluence, поэтому в /opsx:propose мне достаточно указать ссылку. Поскольку мой агент подключён к этим корпоративным системам, он сам загрузит исходные требования и уже на их основе создаст изменение (change).

В рамках propose агент сначала смотрит, что уже зафиксировано в main specs. Если спецификации есть, он определяет, какие из них затронет изменение: какие требования нужно добавить, какие — уточнить, а какие — убрать. Если main specs ещё нет — как в нашем чистом Spring Boot-проекте, — агент описывает новое поведение с нуля. Результат этой работы — delta specs: требования и сценарии, описывающие только разницу между текущим и желаемым поведением системы.

Затем агент разбирает текущую кодовую базу: какие модули и зависимости уже есть, куда логично встроить новую функциональность и какие технические ограничения нельзя игнорировать. На этой основе он готовит design.md — технический дизайн изменения — и tasks.md — план работ, по которому агент будет реализовывать задачу на следующем шаге.

Когда propose завершится, проверяем сгенерированные артефакты. Я читаю их в таком порядке: proposal.md → specs → design.md → tasks.md. Нужно убедиться, что агент верно понял исходную задачу и что предлагаемая реализация соответствует нашим ожиданиям: по интерфейсу, пользовательским сценариям и внутренней архитектуре. В tasks.md отдельно проверяю, что в плане есть задачи, связанные с проверкой барьеров (guardrails): юнит- и интеграционные тесты, Checkstyle, архитектурные проверки ArchUnit, coverage и мутационное тестирование PITest. Кроме того, убеждаюсь, что есть задача на ревью кода другим агентом: если основную разработку вёл Claude Code, ревью делает Codex, и наоборот.

В моей ситуации мне часто приходилось просить агента вносить одни и те же правки от изменения к изменению на этапе propose. Снизить количество правок и скорректировать поведение агента можно несколькими способами:

1. Добавить «управляющий» prompt в CLAUDE.md или AGENTS.md вашего агента

2. Положить инструкции в openspec/AGENTS.md — OpenSpec сам поддерживает этот файл

3. Описать правила в конфигурационном файле OpenSpec — openspec/config.yaml

4. Создать собственную схему артефактов

Артефакты проверены, правки зафиксированы — можно переходить к непосредственной реализации.

Apply

Чтобы агент начал разрабатывать спецификацию, достаточно вызвать /opsx:apply. Он возьмёт tasks.md выбранного изменения и пойдёт по пунктам плана. Но перед этим я делаю несколько предварительных шагов.

Сначала коммичу change-спецификацию. На этом этапе в репозитории ещё нет кода фичи — только proposal, delta specs, design и tasks. Если во время реализации что-то пойдёт не так, к согласованным артефактам всегда можно вернуться.

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

Затем очищаю контекст текущей сессии или завожу новую. Сессия propose уже успела обрасти обсуждением, комментариями и промежуточными правками, а для реализации агенту это не нужно и может быть даже вредно: всё необходимое уже лежит в файлах изменения (change).

После этого вызываю /opsx:apply уже с указанием конкретной change-спецификации.

/opsx:apply add-vets-crud-api

На этом этапе агент уже не планирует, а пишет код. OpenSpec задаёт, что нужно сделать, но не заменяет инструкции о том, как это делать в Spring. Поэтому Spring Skills сохраняют свою актуальность: агент по-прежнему опирается на них, когда создаёт сущности, репозитории, DTO и REST-контроллеры.

После того как код написан, необходимо сделать его ревью. Агент генерирует слишком много изменений, чтобы читать каждое одинаково внимательно, поэтому смотрю только наиболее значимый код: модель, сервисы, репозитории, db-миграции и тесты.

Обязательно проверяю наличие автоматизированных end-to-end-тестов и их корректность. Если автоматизировать некоторые end-to-end-сценарии по какой-то причине невозможно, прохожу их руками (или прошу пройти QA). Затем запускаю PITest для вновь написанного или изменённого кода, чтобы убедиться, что на этапе разработки агент не упустил какой-нибудь из важных сценариев.

Закончив ревью и все необходимые проверки, хочется сразу закоммитить изменения, создать PR/MR и двинуться по стандартному процессу. Но постойте, постойте: мы ещё не превратили delta спецификации в main спецификации. Поэтому изменения в исходном коде коммитим, а PR/MR пока не создаём. Сначала нужно выполнить синхронизацию спецификаций и архивацию изменения.

Sync & Archive

Зачем вообще синхронизировать спецификации? Пока delta спецификации живут только внутри изменения (change), main спецификации по-прежнему описывают систему до нашей доработки. А ведь именно main спецификации — источник истины, на который агент будет опираться в следующих propose. Если их не обновить, следующее изменение начнётся с устаревшей картины мира: агент не увидит уже добавленные требования и либо опишет их заново, либо спокойно предложит поведение, которое мы только что реализовали иначе. Синхронизация переносит ADDED, MODIFIED и REMOVED из delta спецификаций в main спецификации. Для этого в OpenSpec есть специальная команда /opsx:sync. Но не торопитесь её вызывать.

Дело в том, что синхронизация — только половина работы. Пока изменение лежит в changes/, OpenSpec считает его незавершённым. Чтобы завершить изменение (change), его необходимо заархивировать. Для этого в OpenSpec есть команда /opsx:archive.

В процессе архивации агент, во-первых, выполняет синхронизацию delta спецификаций с main спецификациями, а во-вторых, переносит каталог изменения (change) в changes/archive/ с текущей датой. Proposal, design, tasks и delta спецификации, а также другие артефакты никуда не пропадают: к ним всегда можно будет вернуться позже.

Так же, как и перед apply, я очищаю текущую сессию или завожу новую и вызываю /opsx:archive с указанием названия изменения.

/opsx:archive add-vets-crud-api

Коммитим результаты синхронизации и архивации, создаём PR/MR, выполняем остальные шаги стандартного процесса разработки и переходим к следующей задаче, начиная с шага propose. Таким образом мы прошли полный цикл внесения изменения с OpenSpec.

Заключение

Теперь мы знаем всё необходимое, чтобы начать вести разработку с OpenSpec: как устроены требования и спецификации, чем main specs отличаются от delta specs и как изменение проходит через этапы Propose, Apply и Archive.

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

OpenIDE бесплатна навсегда, а Pro версию можно попробовать в течение 60 дней без регистрации. Часть описанных возможностей доступна и в обычной версии, все возможности без исключения в OpenIDE Pro.