Миграция на OPSX

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

Что изменилось?

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

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

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

Прежде чем начать

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

Процесс миграции разработан с упором на сохранность данных:

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

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

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

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

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

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

Миграция определяет, какие инструменты у вас настроены, и очищает их устаревшие файлы.

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

Что требует вашего внимания

Один файл требует ручной миграции:

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

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

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

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

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

Компромисс:

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

Технологический стек и ключевые соглашения
Неочевидные ограничения, которые должен знать ИИ
Правила, которые часто игнорировались раньше

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

Запуск миграции

И openspec init, и openspec update определяют устаревшие файлы и проводят вас через одинаковый процесс очистки. Используйте команду, которая подходит для вашей ситуации:

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

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

Запустите эту команду, если хотите добавить новые инструменты или перенастроить уже настроенные:

bash

openspec init

Команда init определяет устаревшие файлы и проводит вас через процесс очистки:

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

Теперь OpenSpec использует навыки агентов (agent skills) — формирующийся стандарт среди ИИ-инструментов для написания кода. Это упрощает вашу настройку, сохраняя при этом всю функциональность, как и раньше.

Файлы для удаления
Нет пользовательского контента для сохранения:
  • .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)

Что происходит, если вы ответите утвердительно:

Устаревшие директории slash-команд удаляются
Маркеры OpenSpec удаляются из CLAUDE.md, AGENTS.md и т.д. (ваш контент остаётся)
Файл openspec/AGENTS.md удаляется
Новые навыки устанавливаются в .claude/skills/
Файл openspec/config.yaml создаётся со схемой по умолчанию

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

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

bash

openspec update

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

Неинтерактивные среды / среды CI

Для миграций по скриптам:

bash

openspec init --force --tools claude

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

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

Миграция project.md в config.yaml

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

До (project.md)

markdown

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

После (config.yaml)

yaml

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

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

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

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

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

Хорошие кандидаты для секции context:

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

Перенесите в секцию rules: вместо этого

Форматирование для отдельных артефактов («используйте формат Given/When/Then в спецификациях»)
Критерии ревью («предложения должны включать планы отката»)
Они появляются только для соответствующего артефакта, делая остальные запросы более лёгкими

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

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

Шаги миграции

Создайте config.yaml (если он ещё не был создан командой init):
yaml
```
schema: spec-driven
```
Добавьте ваш контекст (будьте лаконичны — он будет добавляться в каждый запрос):
yaml
```
context: |
  Your project background goes here.
  Focus on what the AI genuinely needs to know.
```

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

yaml

rules:
  proposal:
    - Your proposal-specific guidance
  specs:
    - Your spec-writing rules

Удалите 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:archive`	Завершить и архивировать изменение

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

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

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

Соответствие старых команд новым (OPSX)

Старая команда	Аналог в 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, команда проверяет, что готово к созданию, и предлагает следующий артефакт. Вы также можете создать несколько готовых артефактов в любом порядке.

Навыки (skills) против команд

Устаревшая система использовала файлы команд, специфичные для каждого инструмента:

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

OPSX использует формирующийся стандарт навыков (skills):

.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; вместо этого используйте сгенерированные директории .codex/skills/openspec-*.

Продолжение существующих изменений

Ваши незавершенные изменения беспрепятственно работают с командами OPSX.

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

/opsx:apply add-my-feature

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

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

/opsx:continue add-my-feature

Показывает, что готово к созданию, на основе уже существующих объектов.

Нужно посмотреть статус?

bash

openspec status --change add-my-feature

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

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

yaml

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

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

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

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

При определении используемой схемы OPSX проверяет параметры в следующем порядке:

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

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

Схема	Артефакты	Лучше всего подходит для
`spec-driven`	proposal → specs → design → tasks	Большинства проектов

Посмотреть список всех доступных схем:

bash

openspec schemas

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

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

bash

openspec schema init my-workflow

Или создайте ответвление от существующей:

bash

openspec schema fork spec-driven my-workflow

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

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

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

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

bash

openspec init --force

Команды не отображаются после миграции

Перезапустите IDE. Навыки определяются при запуске.

«Неизвестный идентификатор артефакта в правилах»

Убедитесь, что ключи в вашем блоке rules: совпадают с идентификаторами артефактов вашей схемы:

spec-driven: proposal, specs, design, tasks

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

bash

openspec schemas --json

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

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

Файл project.md не был перенесен

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

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

Запустите команду init и отклоните запрос на очистку — вы увидите полную сводку по обнаруженным объектам без внесения каких-либо изменений.

Краткая справка

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

project/
├── openspec/
│   ├── specs/                    # Без изменений
│   ├── changes/                  # Без изменений
│   │   └── archive/              # Без изменений
│   └── config.yaml               # НОВЫЙ: Конфигурация проекта
├── .claude/
│   └── skills/                   # НОВЫЙ: Навыки OPSX
│       ├── openspec-propose/     # стандартный основной профиль
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-sync-specs/
│       └── ...                   # расширенный профиль добавляет 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 и т.д.

Шпаргалка по командам

text

/opsx:propose      Быстрый старт (стандартный основной профиль)
/opsx:apply        Реализация задач
/opsx:archive      Завершение и архивация

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

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

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

Миграция на OPSX ​

Что изменилось? ​

Прежде чем начать ​

Ваши существующие работы в безопасности ​

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

Что требует вашего внимания ​

Запуск миграции ​

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

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

Неинтерактивные среды / среды CI ​

Миграция project.md в config.yaml ​

До (project.md) ​

После (config.yaml) ​

Ключевые отличия ​

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

Шаги миграции ​

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

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

Соответствие старых команд новым (OPSX) ​

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

Понимание новой архитектуры ​

От фазовой блокировки к гибкости ​

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

Навыки (skills) против команд ​

Продолжение существующих изменений ​

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

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

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

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

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

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

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

Команды не отображаются после миграции ​

«Неизвестный идентификатор артефакта в правилах» ​

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

Файл project.md не был перенесен ​

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

Краткая справка ​

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

Что было удалено ​

Шпаргалка по командам ​

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

Миграция на OPSX

Что изменилось?

Прежде чем начать

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

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

Что требует вашего внимания

Запуск миграции

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

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

Неинтерактивные среды / среды CI

Миграция project.md в config.yaml

До (project.md)

После (config.yaml)

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

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

Шаги миграции

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

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

Соответствие старых команд новым (OPSX)

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

Понимание новой архитектуры

От фазовой блокировки к гибкости

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

Навыки (skills) против команд

Продолжение существующих изменений

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

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

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

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

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

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

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

Команды не отображаются после миграции

«Неизвестный идентификатор артефакта в правилах»

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

Файл project.md не был перенесен

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

Краткая справка

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

Что было удалено

Шпаргалка по командам

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