Введение в OpenSpec: удерживайте границы AI-кооперационной среды спецификацией

Для старта | примерно 15 минут | Вы освоите ключевые концепции OpenSpec (Delta Specs, граф зависимостей артефактов), процесс инициализации, workflow OPSX (propose → apply → archive), а также параллельное управление множественными изменениями

---

Обзор проекта

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

Эти проблемы не в том, что AI слишком глупый, а в том, что** требования никогда не были «подписаны и зафиксированы»**. Они существуют только в истории чата — а пространство для свободного творчества AI слишком велико.

OpenSpec делает всё предельно просто: прежде чем вы начнёте писать код, заставьте человека и AI согласовать спецификацию, а затем AI действует по этой спецификации. Его разработала Fission-AI; он поддерживает 20+ AI-инструментов для программирования (Claude Code, Cursor, Windsurf и т. п.) и по сути добавляет AI-программирующему ассистенту лёгкий слой управления спецификациями.

---

Целевая аудитория

• Разработчики, которые ежедневно используют AI-программирующие ассистенты
• Инженеры, которые в командной работе мучаются из‑за того, что человек и AI по‑разному понимают требования
• Продакт-менеджеры, которые хотят получать более контролируемый результат от AI

Ключевые зависимости и окружение

• Node.js 20.19.0+

Полное дерево структуры проекта

openspec/
├── specs/                    # текущие спецификации поведения системы (по доменам)
│   └── <domain>/spec.md
├── changes/                  # предложения изменений (по папке на каждое изменение)
│   ├── <change-name>/
│   │   ├── proposal.md       # мотивация + рамки + подход/решение
│   │   ├── specs/             # Delta-спецификации (ADDED/MODIFIED/REMOVED)
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # технический дизайн
│   │   └── tasks.md          # чек-лист проверки реализации
│   └── archive/               # архивная история
└── config.yaml               # конфигурация проекта (опционально)

---

Пошагово

Шаг 1: Глобальная установка OpenSpec

npm install -g @fission-ai/openspec@latest

После установки проверьте:

openspec --version
# 1.2.0

Шаг 2: Инициализация проекта

Перейдите в каталог вашего проекта и выполните команду инициализации:

cd your-project
openspec init

Эта команда делает три вещи:

1. Создаёт структуру каталога openspec/
2. Генерирует AI-файлы умений в .claude/ (чтобы ассистент распознавал команды вида /opsx:*)
3. Спрашивает, хотите ли вы создать конфигурационный файл проекта config.yaml (опционально — для внедрения контекста проекта)

После завершения инициализации в вашем проекте появятся такие папки:

openspec/
├── specs/       # текущие спецификации поведения системы (пустой каталог, ждёт заполнения)
├── changes/     # директория предложений изменений (пустой каталог)
└── config.yaml  # конфигурация проекта (если вы выбрали создание)

Шаг 3: Включение расширенного workflow OPSX

Только что установленный OpenSpec по умолчанию работает в режиме core; доступны всего 4 команды: propose, explore, apply, archive. Если вы хотите использовать полноценный workflow (включая new, continue, ff, verify, bulk-archive и т. п.), выполните:

openspec config profile
# выбрать expanded или full
openspec update

openspec update пересоздаст AI-файлы умений на основе выбранного profile, чтобы в диалогах с AI можно было использовать больше команд.

Шаг 4: Создайте первое изменение — добавим тёмный режим

Теперь заставим AI помочь создать изменение. Возьмём пример: «добавить тёмный режим в приложение» — просто скажите AI:

/opsx:propose add-dark-mode

AI автоматически создаст 4 файла Artifact в openspec/changes/add-dark-mode/:

openspec/changes/add-dark-mode/
├── proposal.md     # зачем это изменение? рамки? подход?
├── specs/
│   └── ui/spec.md  # Delta-спецификация для UI
├── design.md       # как спроектировать техническое решение?
└── tasks.md        # что именно нужно сделать? шаг за шагом

proposal.md выглядит так (AI генерирует автоматически; вы с AI можете вместе править):

# Proposal: Add Dark Mode

## Intent
Пользователь просит добавить тёмный режим, чтобы снизить усталость глаз при использовании ночью.

## Scope
- Добавить в настройках кнопку переключения темы
- Поддерживать определение системных предпочтений
- Сохранять предпочтение в localStorage

## Approach
Использовать CSS-переменные для тем, а состояние управлять через React Context.

specs/ui/spec.md — это ключевая Delta-спецификация в формате ниже:

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
СИСТЕМА SHALL  позволит пользователю переключаться между светлой и тёмной темами.

#### Сценарий: ручное переключение
- GIVEN Пользователь находится на любой странице
- WHEN Пользователь нажимает кнопку переключения темы
- THEN Тема меняется сразу, а предпочтение сохраняется между сессиями

#### Сценарий: системное предпочтение
- GIVEN У пользователя нет сохранённых предпочтений
- WHEN Приложение загружается
- THEN Используется цветовая схема по умолчанию, заданная системой

tasks.md — чек-лист реализации:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Создать ThemeContext (состояние light/dark)
- [ ] 1.2 Добавить определения CSS-переменных для цветов
- [ ] 1.3 Реализовать сохранение в localStorage

## 2. UI Components
- [ ] 2.1 Создать компонент ThemeToggle
- [ ] 2.2 Добавить кнопку переключения на страницу настроек
- [ ] 2.3 Добавить быстрый переключатель в Header

## 3. Styling
- [ ] 3.1 Определить палитру для тёмной темы
- [ ] 3.2 Сделать так, чтобы существующие компоненты использовали CSS-переменные

Шаг 5: Выполнение задач реализации

После подтверждения, что спецификация корректна, запускаем реализацию:

/opsx:apply

AI будет проверять задачи из tasks.md по одной: выполняет — ставит галочку. Вы заметите, что поведение AI изменилось: он больше не «вольничает», а строго продвигается по порядку, заданному tasks.md. Если в процессе реализации выяснится, что в дизайне есть проблема, можно прямо изменить design.md, а затем снова продолжить apply — AI подхватит автоматически.

Шаг 6: Проверка и архивирование изменения

Проверка (опционально, но рекомендуется):

/opsx:verify

AI проверит вашу реализацию по трём измерениям:

Архивирование:

/opsx:archive

Архивирование выполнит две вещи:

1. Объединит Delta-спецификации с основной спецификацией openspec/specs/ui/spec.md
2. Переместит папку изменений в openspec/changes/archive/2026-04-11-add-dark-mode/

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

Шаг 7: Параллельное управление множественными изменениями

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

# Предположим, вы делаете add-dark-mode, и вдруг нужно исправить bug
/opsx:new fix-login-redirect

# Нормально заканчиваем исправление bug
/opsx:ff
/opsx:apply
/opsx:archive

# Возвращаемся к предыдущей работе по тёмному режиму
/opsx:apply add-dark-mode

Когда вы завершите несколько изменений, архивируйте их вместе:

/opsx:bulk-archive

OpenSpec автоматически обнаружит конфликты спецификаций (оба изменения правят specs/ui/) и объединит их в правильном порядке по времени.

Шаг 8: Настройка Schema

Workflow OPSX в OpenSpec основан на Schema: вы можете полностью настроить типы Artifact и отношения зависимостей. Например, вы хотите workflow «сначала исследование, затем предложение»:

# создать новый schema на основе дефолтного
openspec schema fork spec-driven research-first

Структура сгенерированного Schema:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

Соответствующий граф зависимостей теперь такой:

research ──► proposal ──► tasks

В schema.yaml определите:

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

Шаг 9: Быстрый справочник по популярным CLI-командам

# Инициализация
openspec init

# Обновление AI-файлов умений (нужно выполнять после каждого апгрейда или смены profile)
openspec update

# Просмотр текущей конфигурации
openspec config show

# Переключение profile workflow
openspec config profile

# Просмотр активных изменений
openspec list

# Просмотр деталей конкретного изменения
openspec show add-dark-mode

# Проверка формата
openspec validate add-dark-mode

# Интерактивный Dashboard
openspec view

# Управление Schema
openspec schemas              # список доступных schema
openspec schema which --all   # посмотреть источник schema
openspec schema validate my-schema  # проверить schema

---

Устранение типовых проблем

1. AI не находит команду /opsx:propose

Это самая частая проблема. После выполнения openspec init ассистенту AI нужно перезагрузить файлы умений. Выполните:

openspec update

Затем заново откройте диалог. Если AI всё равно не распознаёт команды, вручную проверьте, существует ли каталог .claude/.

2. openspec init сообщает об ошибке версии Node.js

node --version
# подтвердите, что >= 20.19.0

# если версия слишком низкая — обновите через nvm
nvm install 20 && nvm use 20

3. Конфликт при объединении Delta-спецификаций

При выполнении /opsx:bulk-archive, если два изменения правят один и тот же файл спецификации, OpenSpec обнаружит это и сообщит вам. По умолчанию используется объединение по времени; если нужно обработать вручную:

# сначала отдельно архивировать одно
/opsx:archive fix-login-redirect

# затем архивировать другое
/opsx:archive add-dark-mode

4. Ошибка загрузки пользовательского Schema

Обычно причина — синтаксическая ошибка в schema.yaml. Проверьте так:

openspec schema validate my-schema

Частые ошибки: неверные отступы YAML и ссылка в artifact-поле requires на несуществующий ID (циклическая зависимость).

5. Формат сгенерированных AI спецификаций не соответствует требованиям

Можно добавить правила в openspec/config.yaml:

rules:
  specs:
    - Описывайте каждый сценарий в формате GIVEN/WHEN/THEN
    - В каждом Requirement должен быть как минимум один Scenario

Эти правила будут внедрены в инструкции для генерации спецификаций AI.

6. Во время /opsx:apply AI пропускает некоторые задачи

Прямо скажите AI:

Пожалуйста, выполняйте задачи в порядке из tasks.md. Задание 1.3 ещё не завершено — не пропускайте.

Fluid-особенность OpenSpec позволяет вам в любой момент редактировать Artifact: после правки tasks.md запустите apply снова — AI продолжит с места, на котором остановился.

---

Дополнительное чтение / направления развития

Подробно о формате Delta Specs: у ADDED/MODIFIED/REMOVED три типа изменений со своей семантикой — ADDED добавляет новые требования, MODIFIED заменяет существующие, REMOVED удаляет устаревшие требования. Понимание правил их объединения — ключ к тому, чтобы эффективно использовать OpenSpec.

Сравнение OPSX и Legacy workflow: OpenSpec v1.x использует Legacy workflow (/openspec:proposal), а начиная с v1.2 продвигается OPSX. Главная разница: Legacy строго phase-locked (всё есть или всё отсутствует), а OPSX fluid (можно редактировать любые Artifact в любой момент).

Руководство по подключению 20+ AI-инструментов: OpenSpec генерирует файлы умений через каталог .claude/skills/ и совместим с популярными инструментами вроде Claude Code, Cursor, Windsurf, Copilot и т. д. См. docs/supported-tools.md.

Интеграция с командным Slack: корпоративные команды могут обратиться по [email protected] за поддержкой в выделенном канале Slack — особенно подходит для сценариев, где вместе работает много людей, и нужен процесс управления спецификациями и их ревью.

Глубокая настройка конфигурации проекта: кроме context и rules, можно через config.yaml задать дефолтный Schema и внедрить информацию о техстеке проекта (например, фреймворк тестирования, стандарты стиля кода), чтобы генерируемые AI спецификации сильнее соответствовали вашему реальному проекту.