Что такое OpenSpec: установка и рабочие процессы

OpenSpec — это лёгкий фреймворк для разработки на основе спецификаций (Spec-Driven Development). Он добавляет слой договорённостей между вами и ИИ-ассистентом для программирования: сначала записать, что нужно сделать, посмотреть план и только потом писать код, а не оставлять требования только в истории чата. Проект открыт, лицензия MIT, поддерживает более 30 инструментов ИИ для программирования, и на нём построен собственный процесс HagiCode. Эта страница — кратчайший путь к установке и первому полному изменению; полные руководства находятся на отдельном сайте.

Ключевые понятия

OpenSpec строится на пяти идеях:

1. Спецификации (specs) — источник истины. Они описывают, как система работает сейчас, лежат в openspec/specs/, сгруппированы по областям и состоят из требований и сценариев.
2. Изменение (change) — единица работы. Чтобы добавить, изменить или удалить поведение, создаётся папка в openspec/changes/, где собраны предложение, дизайн, список задач и правки спецификаций.
3. Дельта-спецификации описывают только изменения. Внутри изменения не переписывается вся спецификация, а пишутся ADDED, MODIFIED и REMOVED; поэтому OpenSpec хорошо подходит для правки существующих систем.
4. Артефакты опираются друг на друга. proposal (зачем) → specs (что) → design (как) → tasks (шаги) → реализация. Это помощники, а не барьеры: к любому из них можно вернуться.
5. Архивация возвращает изменение в источник истины. Когда работа закончена, дельта-спецификации вливаются в основные, а папка изменения переносится в changes/archive/ с датой.

Установка

Нужен Node.js 20.19.0 или новее (для остальных компонентов HagiCode рекомендуется 24 и выше, см. Установка Node.js).

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

В macOS и Linux можно также использовать Homebrew: brew install openspec. pnpm, yarn (1.x) и bun тоже умеют ставить пакет глобально, но OpenSpec по-прежнему работает на Node.js.

Затем перейдите в каталог проекта и выполните инициализацию:

cd your-project
openspec init

Инициализация спросит, какими ИИ-инструментами вы пользуетесь, и создаст для них файлы навыков или команд. Чтобы обойтись без вопросов, используйте openspec init --tools claude,cursor; идентификаторы инструментов перечислены в разделе Поддерживаемые инструменты.

Первое полное изменение

Слэш-команды вводятся в чате ИИ-ассистента, а не в терминале:

/opsx:explore            # ещё не уверены? пусть ИИ прочитает код и взвесит варианты
/opsx:propose add-dark-mode   # создать папку изменения: proposal, specs, design, tasks
/opsx:apply              # выполнить список задач
/opsx:archive            # архивировать; дельта-спецификации вливаются в основные

/opsx:propose создаёт openspec/changes/add-dark-mode/ с файлами proposal.md, specs/, design.md и tasks.md. Спецификации — обычный Markdown без особого синтаксиса:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Их пишет ИИ, а вы проверяете план до того, как будет написан код. В профиль по умолчанию входят propose, explore, apply, update, sync и archive. Для расширенного процесса (new, continue, ff, verify, bulk-archive и другие) выберите его через openspec config profile и примените командой openspec update.

В разных ассистентах имена команд немного отличаются

/opsx:propose — основная запись. В Cursor и GitHub Copilot это /opsx-propose, в Amazon Q — @opsx-propose, в Codex — $openspec-propose. openspec init выводит правильную форму для выбранных вами инструментов.

Обновление

npm install -g @fission-ai/openspec@latest   # обновить пакет
openspec update                              # обновить файлы инструкций ИИ в каждом проекте

Если установка была через Homebrew, используйте brew upgrade openspec.

Частые проблемы

• openspec: command not found: глобальный каталог npm не входит в PATH. Выполните npm prefix -g; в macOS и Linux добавьте в PATH подкаталог bin/ этого каталога, а в Windows — сам каталог.
• «Requires Node.js 20.19.0 or higher»: проверьте версию командой node --version и обновите Node.js.
• /opsx:propose не появляется в чате: убедитесь, что вводите команду в ассистенте, а не в терминале, выполните openspec update, чтобы пересоздать файлы, и перезапустите ассистента. Инструментам только с навыками, например Codex, нужна запись вида $openspec-propose.
• Инициализация не настроила ваш инструмент: запустите openspec init ещё раз или передайте --tools.

Полная документация

Документация OpenSpec на русском языке

• Установка OpenSpec
• Начало работы
• Рабочие процессы
• Устранение неполадок

Дополнительные материалы

• Чтобы выбрать между ним и Spec Kit от GitHub, прочитайте Spec Kit и OpenSpec: сравнение.
• Практика HagiCode поверх OpenSpec: Оптимизация эффективности каждого этапа OpenSpec с помощью разных агентов: практическое резюме HagiCode и MonoSpecs: что это и почему это является дальнейшим обновлением и расширением OpenSpec.