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

Навички проти команд

Стара система використовувала специфічні для інструментів файли команд:

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

Є активна зміна зі старого робочого процесу?

/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

Дивіться Налаштування для деталей.

Усунення несправностей

"Legacy files detected in non-interactive mode"

Ви запускаєте в середовищі CI або неінтерактивному середовищі. Використовуйте:

bash

openspec init --force

Команди не з'являються після міграції

Перезапустіть ваше IDE. Навички визначаються при запуску.

"Unknown artifact ID in rules"

Перевірте, що ключі 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/                    # Unchanged
│   ├── changes/                  # Unchanged
│   │   └── archive/              # Unchanged
│   └── config.yaml               # NEW: Project configuration
├── .claude/
│   └── skills/                   # NEW: OPSX skills
│       ├── openspec-propose/     # default core profile
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       └── ...                   # expanded profile adds new/continue/ff/etc.
├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
└── AGENTS.md                     # OpenSpec markers removed, your content preserved

Що зникло

.claude/commands/openspec/ — замінено на .claude/skills/
openspec/AGENTS.md — застаріле
openspec/project.md — мігруйте до config.yaml, потім видаліть
Маркери OpenSpec у CLAUDE.md, AGENTS.md тощо.

Довідник команд

text

/opsx:propose      Start quickly (default core profile)
/opsx:apply        Implement tasks
/opsx:archive      Finish and archive

# Expanded workflow (if enabled):
/opsx:new          Scaffold a change
/opsx:continue     Create next artifact
/opsx:ff           Create planning artifacts

Отримання допомоги

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) ​

Ключові відмінності ​

Що зберігати, що відкидати ​

Кроки міграції ​

Потрібна допомога? Використовуйте цей промпт ​

Нові команди ​

Відображення команд зі старої версії ​

Нові можливості ​

Розуміння нової архітектури ​

Від фазової до гнучкої ​

Граф залежностей ​

Навички проти команд ​

Продовження існуючих змін ​

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

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

Визначення схеми ​

Доступні схеми ​

Користувацькі схеми ​

Усунення несправностей ​

"Legacy files detected in non-interactive mode" ​

Команди не з'являються після міграції ​

"Unknown artifact ID in rules" ​

Конфігурація не застосовується ​

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

Швидка довідка ​

Файли після міграції ​

Що зникло ​

Довідник команд ​

Отримання допомоги ​

Міграція на OPSX

Що змінюється?

Перед початком

Ваша наявна робота в безпеці

Що видаляється

Що потребує вашої уваги

Запуск міграції

Використання `openspec init`

Використання `openspec update`

Неінтерактивні / CI-середовища

Міграція project.md до config.yaml

До (project.md)

Після (config.yaml)

Ключові відмінності

Що зберігати, що відкидати

Кроки міграції

Потрібна допомога? Використовуйте цей промпт

Нові команди

Відображення команд зі старої версії

Нові можливості

Розуміння нової архітектури

Від фазової до гнучкої

Граф залежностей

Навички проти команд

Продовження існуючих змін

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

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

Визначення схеми

Доступні схеми

Користувацькі схеми

Усунення несправностей

"Legacy files detected in non-interactive mode"

Команди не з'являються після міграції

"Unknown artifact ID in rules"

Конфігурація не застосовується

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

Швидка довідка

Файли після міграції

Що зникло

Довідник команд

Отримання допомоги