Миграция на OPSX

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

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

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

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

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

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

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

Процесс миграции разработан с учетом сохранности ваших данных:

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

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

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

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

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

Claude Code: .claude/commands/openspec/
Cursor: .cursor/commands/openspec-*.md
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)
И другие (Augment, Continue, Amazon Q и т.д.)

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

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

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

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

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

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

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

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

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

Компромисс:

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

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

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

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

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

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

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

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

bash

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)

Что происходит, когда вы соглашаетесь:

Удаляются устаревшие каталоги слэш-команд
Маркеры 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 пропускает запросы и автоматически принимает очистку.

Миграция 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
Свободный markdown	Структурированный YAML
Один блок текста	Раздельный контекст и правила для каждого артефакта
Непонятно, когда используется	Контекст появляется во ВСЕХ артефактах; правила — только в соответствующих
Нет выбора схемы	Явное поле `schema:` устанавливает рабочий процесс по умолчанию

Что оставить, что отбросить

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

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

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

Переместите в rules: вместо этого

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

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

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

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

Создайте config.yaml (если еще не создан через init):
yaml
```
schema: spec-driven
```

Добавьте свой контекст (будьте кратки — это попадает в каждый запрос):

yaml

context: |
  Ваш контекст проекта здесь.
  Сосредоточьтесь на том, что ИИ действительно нужно знать.

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

yaml

rules:
  proposal:
    - Ваши рекомендации для предложений
  specs:
    - Ваши правила написания спецификаций

Удалите project.md, когда перенесете все полезное.

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

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

Если вы не уверены, как выжать суть из вашего project.md, спросите вашего ИИ-ассистента:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

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

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

Доступность команд зависит от профиля:

По умолчанию (профиль 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
`/openspec:proposal`	`/opsx:propose` (по умолчанию) или `/opsx:new` затем `/opsx:ff` (расширенный)
`/openspec:apply`	`/opsx:apply`
`/openspec:archive`	`/opsx:archive`

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

Эти возможности являются частью набора команд расширенного рабочего процесса.

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

/opsx:continue

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

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

/opsx:explore

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

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

От фаз к гибкости

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

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Если вы находитесь на этапе реализации и понимаете, что дизайн неверен?
Всё плохо. Фазовые ворота не позволяют легко вернуться назад.

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

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

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

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

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

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

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

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

.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
└── ...

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

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

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

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

/opsx:apply add-my-feature

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

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

/opsx:continue add-my-feature

Показывает, что можно создать на основе того, что уже существует.

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

bash

openspec status --change add-my-feature

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

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

yaml

# Required: Default schema for new changes
schema: spec-driven

# Optional: Project context (max 50KB)
# Injected into ALL artifact instructions
context: |
  Your project background, tech stack,
  conventions, and constraints.

# Optional: Per-artifact rules
# Only injected into matching artifacts
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

Разрешение схемы

При определении используемой схемы 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. Навыки обнаруживаются при запуске.

"Неизвестный ID артефакта в правилах"

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

spec-driven: proposal, specs, design, tasks

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

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/
│       └── ...                   # расширенный профиль добавляет 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) ​

Ключевые различия ​

Что оставить, что отбросить ​

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

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

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

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

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

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

От фаз к гибкости ​

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

Навыки vs Команды ​

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

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

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

Разрешение схемы ​

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

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

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

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

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

"Неизвестный ID артефакта в правилах" ​

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

project.md не был мигрирован ​

Хотите увидеть, что будет очищено? ​

Краткая справочная информация ​

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

Что исчезло ​

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

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

Миграция на OPSX

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

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

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

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

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

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

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

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

Неинтерактивные / CI-окружения

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

До (project.md)

После (config.yaml)

Ключевые различия

Что оставить, что отбросить

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

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

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

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

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

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

От фаз к гибкости

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

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

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

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

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

Разрешение схемы

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

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

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

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

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

"Неизвестный ID артефакта в правилах"

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

project.md не был мигрирован

Хотите увидеть, что будет очищено?

Краткая справочная информация

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

Что исчезло

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

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