Переход на OPSX

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

Что меняется?

OPSX заменяет старый процесс с фиксированными этапами гибким подходом, основанным на действиях. Главное отличие:

Аспект	Устаревший процесс	OPSX
Команды	/openspec:proposal, /openspec:apply, /openspec:archive	По умолчанию: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (расширенные команды необязательны)
Рабочий процесс	Создание всех артефактов за один раз	Постепенно или сразу — на ваш выбор
Возврат к предыдущим шагам	Неудобные переходы между этапами	Естественный процесс — в любой момент обновите любой артефакт
Настройка	Фиксированная структура	Управление через схемы, широкие возможности настройки
Конфигурация	CLAUDE.md с маркерами + project.md	Удобная конфигурация в openspec/config.yaml

Изменение философии: работа не линейна, и OPSX больше не делает вид, что это так.

---

Перед началом

Ваша текущая работа в безопасности

Процесс перехода устроен так, чтобы сохранить существующие материалы:

• Активные изменения в openspec/changes/ — полностью сохраняются; продолжайте работу над ними командами OPSX.
• Архивированные изменения — остаются нетронутыми; история сохраняется.
• Основные спецификации в openspec/specs/ — остаются нетронутыми; это источник истины.
• Ваше содержимое в CLAUDE.md, AGENTS.md и других файлах — сохраняется. Удаляются только блоки-маркеры OpenSpec; всё написанное вами остаётся.

Что удаляется

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

Что	Причина
Устаревшие каталоги и файлы slash-команд	Заменяются новой системой навыков
openspec/AGENTS.md	Устаревший триггер рабочего процесса
Маркеры OpenSpec в CLAUDE.md, AGENTS.md и других файлах	Больше не нужны

Расположение устаревших команд в инструментах (примеры; у вас могут отличаться):

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Devin Desktop, ранее Windsurf: .windsurf/workflows/openspec-*.md
• Cline: .clinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md (только расширения IDE; в Copilot CLI не поддерживается)
• Codex: OpenSpec использует стандартный путь .agents/skills/openspec-*. Управляемые OpenSpec файлы SKILL.md в прежнем каталоге .codex/skills сверяются только после появления заменяющих файлов; пользовательские файлы и отличающиеся копии остаются на месте. Если в каталоге .agents без маркера уже есть навыки OpenSpec, система сохраняет существующее представление Codex ($openspec-*) или универсальное (/openspec-*), а не пытается угадать его по старому каталогу. Чтобы изменить владельца каталога, явно выберите codex командой openspec init. Очистка старых запросов по-прежнему затрагивает только разрешённые имена файлов OpenSpec в $CODEX_HOME/prompts или ~/.codex/prompts.
• И другие (Augment, Continue, Amazon Q и т. п.)

Миграция обнаруживает настроенные инструменты и удаляет их устаревшие файлы.

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

Что нужно сделать вручную

Один файл нужно перенести вручную:

openspec/project.md — этот файл не удаляется автоматически, поскольку может содержать написанный вами контекст проекта. Вам нужно:

1. Проверить его содержимое.
2. Перенести нужный контекст в openspec/config.yaml (см. инструкции ниже).
3. Удалить файл, когда будете готовы.

Почему мы это изменили:

Старый project.md был пассивным: агенты могли прочитать его, проигнорировать или забыть прочитанное. Поэтому поведение было непоследовательным.

Контекст из нового config.yaml автоматически добавляется к каждому запросу планирования OpenSpec. Поэтому соглашения проекта, технологический стек и правила всегда доступны ИИ при создании артефактов. Надёжность повышается.

Компромисс:

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

• технологический стек и основные соглашения;
• неочевидные ограничения, о которых нужно знать ИИ;
• правила, которые раньше часто игнорировались.

Не стремитесь сразу добиться идеального результата. Мы продолжаем изучать лучшие подходы и будем совершенствовать передачу контекста по мере экспериментов.

---

Выполнение миграции

Команды openspec init и openspec update обнаруживают устаревшие файлы и предлагают одинаковый процесс очистки. Выберите подходящую команду:

• В новых установках по умолчанию используется профиль core (propose, explore, apply, update, sync, archive).
• При миграции сохраняются ранее установленные рабочие процессы; при необходимости записывается профиль custom.

Использование openspec init

Запустите эту команду, если хотите добавить инструменты или изменить конфигурацию:

openspec init

Команда init обнаружит устаревшие файлы и предложит очистить их:

Обновление до новой версии OpenSpec

Теперь OpenSpec использует навыки агентов — новый стандарт для
агентов программирования. Это упрощает настройку и сохраняет
прежнюю работоспособность.

Файлы для удаления
Пользовательское содержимое сохранять не требуется:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Файлы для обновления
Маркеры OpenSpec будут удалены, ваше содержимое сохранится:
  • CLAUDE.md
  • AGENTS.md

Требуется ваше внимание
  • openspec/project.md
    Этот файл не удаляется автоматически. В нём может быть полезный контекст проекта.

    В новом openspec/config.yaml есть раздел "context:" для контекста
    планирования. Он включается в каждый запрос OpenSpec и надёжнее,
    чем прежний подход с project.md.

    Проверьте project.md, перенесите нужное содержимое в раздел context
    файла config.yaml, а затем удалите файл, когда будете готовы.

? Обновить и удалить устаревшие файлы? (Y/n)

Что произойдёт после подтверждения:

1. Устаревшие каталоги slash-команд удаляются.
2. Из CLAUDE.md, AGENTS.md и других файлов удаляются маркеры OpenSpec (ваше содержимое сохраняется).
3. Удаляется openspec/AGENTS.md.
4. Новые навыки устанавливаются в .claude/skills/.
5. Создаётся openspec/config.yaml со схемой по умолчанию.

Использование openspec update

Запустите эту команду, если нужно выполнить миграцию и обновить существующие инструменты до последней версии:

openspec update

Команда update также обнаруживает и удаляет устаревшие артефакты, а затем обновляет сгенерированные навыки и команды согласно текущему профилю и настройкам установки.

Неинтерактивный режим и среды CI

Для миграции с помощью сценариев:

openspec init --force --tools claude

Флаг --force пропускает запросы и автоматически подтверждает очистку.

Сюда входит очистка управляемых OpenSpec файлов запросов Codex в глобальном каталоге запросов Codex. Удаляются только разрешённые устаревшие имена файлов OpenSpec и только после появления заменяющих навыков .agents/skills/openspec-*; остальные файлы сохраняются.

---

Перенос project.md в config.yaml

Старый openspec/project.md был произвольным Markdown-файлом для контекста проекта. Новый openspec/config.yaml имеет структурированный формат и, что особенно важно, добавляется к каждому запросу планирования, поэтому ИИ всегда учитывает ваши соглашения.

До миграции (project.md)

# Контекст проекта

Это монорепозиторий на TypeScript с использованием React и Node.js.
Для тестирования используется Jest и строгие правила ESLint.
Наш API соответствует REST и описан в docs/api.md.

## Соглашения

- Для всех публичных API необходимо сохранять обратную совместимость.
- Для новых функций следует добавлять тесты.
- Для спецификаций нужно использовать формат Given/When/Then.

После миграции (config.yaml)

schema: spec-driven

context: |
  Технологический стек: TypeScript, React, Node.js
  Тестирование: Jest и React Testing Library
  API: REST, документация в docs/api.md
  Мы сохраняем обратную совместимость всех публичных API

rules:
  proposal:
    - Добавлять план отката для рискованных изменений
  specs:
    - Использовать формат Given/When/Then для сценариев
    - Сначала ссылаться на существующие шаблоны, а не изобретать новые
  design:
    - Добавлять диаграммы последовательностей для сложных процессов

Основные различия

project.md	config.yaml
Markdown произвольного формата	Структурированный YAML
Один большой текст	Отдельные контекст и правила для каждого артефакта
Непонятно, когда используется	Контекст включается во ВСЕ артефакты; правила — только в соответствующие
Нельзя выбрать схему	Поле schema: явно задаёт рабочий процесс по умолчанию

Что оставить и что удалить

При переносе выбирайте только нужное. Спросите себя: «Нужно ли это ИИ для каждого запроса планирования?»

Подходящее содержимое для context:

• технологический стек (языки, фреймворки, базы данных);
• основные архитектурные шаблоны (монорепозиторий, микросервисы и т. п.);
• неочевидные ограничения («нельзя использовать библиотеку X, потому что…»);
• важные соглашения, которые часто игнорируются.

Перенесите в rules:

• форматирование отдельных артефактов («использовать Given/When/Then в спецификациях»);
• критерии проверки («в предложениях должен быть план отката»);
• эти правила добавляются только к соответствующим артефактам и не перегружают другие запросы.

Полностью исключите

• общие лучшие практики, уже известные ИИ;
• многословные объяснения, которые можно сократить;
• исторический контекст, не влияющий на текущую работу.

Этапы миграции

1. Создайте config.yaml (если init ещё не создал файл):

   schema: spec-driven

2. Добавьте контекст (кратко — он включается в каждый запрос):

   context: |
     Здесь укажите контекст проекта.
     Сосредоточьтесь на сведениях, действительно необходимых ИИ.

3. Добавьте правила для отдельных артефактов (необязательно):

   rules:
     proposal:
       - Рекомендации по подготовке предложений
     specs:
       - Правила написания спецификаций

4. Удалите project.md, когда перенесёте всё нужное.

Не усложняйте. Начните с самого важного и дорабатывайте постепенно. Если ИИ упускает важные сведения, добавьте их. Если контекст становится слишком большим, сократите его. Это живой документ.

Нужна помощь? Используйте эту инструкцию

Если не знаете, как сократить project.md, попросите ИИ-ассистента:

Я переношу контекст из старого project.md OpenSpec в новый формат config.yaml.

Вот текущий project.md:
[вставьте содержимое project.md]

Помоги мне создать config.yaml со следующими разделами:
1. Краткий `context:` (он добавляется к каждому запросу планирования, поэтому не перегружай его; укажи технологический стек, важные ограничения и соглашения, которые часто игнорируются).
2. `rules:` для отдельных артефактов, если какие-то требования относятся только к ним (например, «использовать Given/When/Then» должно быть правилом для спецификаций, а не общим контекстом).

Не включай общие сведения, уже известные моделям ИИ. Стремись к максимальной краткости.

ИИ поможет определить, что важно, а что можно сократить.

---

Новые команды

Наличие команд зависит от профиля:

По умолчанию (профиль core):

Команда	Назначение
/opsx:propose	Создать изменение и за один шаг подготовить артефакты планирования
/opsx:explore	Свободно обдумать идеи
/opsx:apply	Выполнить задачи из tasks.md
/opsx:update	Изменить артефакты планирования и сохранить их согласованность
/opsx:sync	Объединить дельта-спецификации с основными
/opsx:archive	Завершить изменение и архивировать его

Расширенный рабочий процесс (пользовательский выбор):

Команда	Назначение
/opsx:new	Создать каркас нового изменения
/opsx:continue	Создать следующий артефакт (по одному за раз)
/opsx:ff	Создать все артефакты планирования сразу
/opsx:verify	Проверить соответствие реализации спецификациям
/opsx:bulk-archive	Архивировать несколько изменений одновременно
/opsx:onboard	Пошагово пройти полный процесс знакомства

Включите расширенные команды с помощью openspec config profile, а затем запустите openspec update.

Соответствие устаревших и новых команд

Устаревшая команда	Эквивалент OPSX
/openspec:proposal	/opsx:propose (по умолчанию) или /opsx:new, затем /opsx:ff (расширенный процесс)
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

Новые возможности

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

Пошаговое создание артефактов:

/opsx:continue

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

Режим исследования:

/opsx:explore

Обсудите идею с помощником, прежде чем начинать изменение.

---

Новая архитектура

От фиксированных этапов к гибкому процессу

Устаревший процесс требовал последовательного выполнения этапов:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│ ПЛАНИРОВАНИЕ│ ───► │ РЕАЛИЗАЦИЯ  │ ───► │ АРХИВАЦИЯ   │
│    ЭТАП     │      │    ЭТАП     │      │    ЭТАП     │
└──────────────┘      └──────────────┘      └──────────────┘

На этапе реализации выяснилось, что проектное решение неверно?
Жаль: ограничения этапов затрудняют возврат.

В OPSX используются действия, а не этапы:

         ┌───────────────────────────────────────────────┐
         │             ДЕЙСТВИЯ (не этапы)               │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    любой порядок               │
         └───────────────────────────────────────────────┘

Граф зависимостей

Артефакты образуют направленный граф. Зависимости — это опоры, а не барьеры:

                        proposal
                       (корневой узел)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (требуется:                 (требуется:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (требуется:
                     specs, design)

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

Навыки и команды

В устаревшей системе использовались файлы команд для отдельных инструментов:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

В OPSX используется новый стандарт навыков:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Навыки распознаются разными инструментами для программирования с ИИ и содержат больше метаданных.

В OPSX для Codex используются только навыки. OpenSpec больше не создаёт для Codex пользовательские файлы запросов; используйте созданные каталоги .agents/skills/openspec-*.

---

Продолжение работы над существующими изменениями

Активные изменения без проблем продолжают работать с командами OPSX.

Есть активное изменение из устаревшего рабочего процесса?

/opsx:apply add-my-feature

OPSX прочитает существующие артефакты и продолжит с того места, где вы остановились.

Хотите добавить артефакты к существующему изменению?

/opsx:continue add-my-feature

Показывает, какие артефакты можно создать с учётом уже существующих.

Нужно проверить состояние?

openspec status --change add-my-feature

---

Новая система конфигурации

Структура config.yaml

# Обязательное поле: схема по умолчанию для новых изменений
schema: spec-driven

# Необязательное поле: контекст проекта (не более 50 КБ)
# Добавляется ко ВСЕМ инструкциям для артефактов
context: |
  Контекст проекта, технологический стек,
  соглашения и ограничения.

# Необязательное поле: правила для отдельных артефактов
# Добавляются только к соответствующим артефактам
rules:
  proposal:
    - Добавлять план отката
  specs:
    - Использовать формат Given/When/Then
  design:
    - Документировать стратегии резервного варианта
  tasks:
    - Разбивать работу на части продолжительностью не более двух часов

Определение схемы

При выборе схемы OPSX проверяет источники в следующем порядке:

1. Флаг CLI: --schema <name> (наивысший приоритет).
2. Метаданные изменения: .openspec.yaml в каталоге изменения.
3. Конфигурация проекта: openspec/config.yaml.
4. По умолчанию: spec-driven.

Доступные схемы

Схема	Артефакты	Назначение
spec-driven	proposal → specs → design → tasks	Большинство проектов

Выведите список всех доступных схем:

openspec schemas

Пользовательские схемы

Создайте собственный рабочий процесс:

openspec schema init my-workflow

Или скопируйте существующую схему:

openspec schema fork spec-driven my-workflow

Подробности см. в разделе Настройка.

---

Устранение неполадок

«В неинтерактивном режиме обнаружены устаревшие файлы»

Вы работаете в CI или неинтерактивной среде. Используйте:

openspec init --force

После миграции команды не появились

Перезапустите IDE: навыки обнаруживаются при запуске.

«Неизвестный ID артефакта в rules»

Убедитесь, что ключи rules: соответствуют ID артефактов схемы:

• spec-driven: proposal, specs, design, tasks

Чтобы просмотреть допустимые ID артефактов, выполните:

openspec schemas --json

Конфигурация не применяется

1. Убедитесь, что файл находится в openspec/config.yaml, а не в .yml.
2. Проверьте синтаксис YAML.
3. Изменения конфигурации вступают в силу сразу, перезапуск не требуется.

project.md не был перенесён

Файл project.md намеренно сохраняется, поскольку в нём может быть ваше содержимое. Просмотрите его вручную, перенесите полезные сведения в config.yaml, а затем удалите файл.

Хотите посмотреть, что будет удалено?

Запустите init и отклоните предложение об очистке: будет показана полная сводка найденных файлов, но никаких изменений не произойдёт.

---

Краткий справочник

Файлы после миграции

project/
├── openspec/
│   ├── specs/                    # Без изменений
│   ├── changes/                  # Без изменений
│   │   └── archive/              # Без изменений
│   └── config.yaml               # НОВЫЙ: конфигурация проекта
├── .claude/
│   └── skills/                   # НОВЫЕ: навыки OPSX
│       ├── openspec-propose/     # профиль core по умолчанию
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # расширенный профиль добавляет new/continue/ff и др.
├── CLAUDE.md                     # маркеры OpenSpec удалены, ваше содержимое сохранено
└── AGENTS.md                     # маркеры OpenSpec удалены, ваше содержимое сохранено

Что удалено

• .claude/commands/openspec/ — заменён каталогом .claude/skills/;
• openspec/AGENTS.md — устарел;
• openspec/project.md — перенесите содержимое в config.yaml, затем удалите;
• блоки-маркеры OpenSpec в CLAUDE.md, AGENTS.md и других файлах.

Краткая памятка по командам

/opsx:propose      Быстрый запуск (профиль core по умолчанию)
/opsx:apply        Выполнить задачи
/opsx:archive      Завершить и архивировать

# Расширенный рабочий процесс (если включён):
/opsx:new          Создать каркас изменения
/opsx:continue     Создать следующий артефакт
/opsx:ff           Создать артефакты планирования

---

Получение помощи

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Документация: Руководство по OPSX — полный справочник по OPSX