Переход на 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-команд	Заменяются новой системой навыков
`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, sync, 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)

Что произойдёт, когда вы скажете «да»:

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

Миграция 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, спросите вашего ИИ-ассистента:

Я мигрирую со старого 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
`/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) против Команд (Commands)

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

.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 без проблем.

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

/opsx:apply add-my-feature

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

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

/opsx:continue add-my-feature

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

Нужно увидеть статус?

bash

openspec status --change add-my-feature

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

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

yaml

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

# Необязательно: Контекст проекта (макс. 50KB)
# Внедряется во ВСЕ инструкции артефактов
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) ​

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

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

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

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

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

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

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

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

От фиксированных фаз к гибким действиям ​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что удалено ​

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

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

Переход на OPSX

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

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

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

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

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

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

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

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

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

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

До (project.md)

После (config.yaml)

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

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

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

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

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

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

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

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

От фиксированных фаз к гибким действиям

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

Навыки (Skills) против Команд (Commands)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что удалено

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

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