Міграція на 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

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

Це TypeScript монорепо, що використовує React та Node.js.
Ми використовуємо Jest для тестування та дотримуємося суворих правил ESLint.
Наш API є RESTful та задокументований в docs/api.md.

## Конвенції

- Усі публічні API повинні підтримувати зворотну сумісність
- Нові функції повинні включати тести
- Використовуйте формат Given/When/Then для специфікацій

Після (config.yaml)

yaml

schema: spec-driven

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

rules:
  proposal:
    - Включайте план відкоту для ризикованих змін
  specs:
    - Використовуйте формат Given/When/Then для сценаріїв
    - Посилайтеся на існуючі патерни перед вигадуванням нових
  design:
    - Включайте діаграми послідовності для складних потоків

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

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

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

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

.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

# Обов'язково: Схема за замовчуванням для нових змін
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) ​

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

Що залишити, що відкинути ​

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

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

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

Відповідність команд від застарілих ​

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

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

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

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

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

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

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

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

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

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

Власні схеми ​

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

"Виявлено застарілі файли в неінтерактивному режимі" ​

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

"Невідомий ідентифікатор артефакту в правилах" ​

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

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

Хочете побачити, що буде очищено? ​

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

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

Що видалено ​

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

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

Міграція на OPSX

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

Перш ніж почати

Ваша існуюча робота в безпеці

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

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

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

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

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

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

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

До (project.md)

Після (config.yaml)

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

Що залишити, що відкинути

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

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

Нові команди

Відповідність команд від застарілих

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

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

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

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

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

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

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

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

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

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

Власні схеми

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

"Виявлено застарілі файли в неінтерактивному режимі"

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

"Невідомий ідентифікатор артефакту в правилах"

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

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

Хочете побачити, що буде очищено?

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

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

Що видалено

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

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