Перехід на 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, які замінюються:

Що	Чому
Застарілі каталоги/файли слеш-команд	Замінені новою системою навичок (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: .clinerules/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)

Що відбудеться, коли ви скажете "так":

Застарілі каталоги слеш-команд видаляються
Маркери 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

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

Це 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 у specs")
Критерії огляду ("пропозиції мають включати плани відкоту")
Це з'являється лише для відповідного артефакту, зберігаючи інші запити легшими

Повністю опустіть

Загальні кращі практики, які ШІ вже знає
Багатослівні пояснення, які можна підсумувати
Історичний контекст, який не впливає на поточну роботу

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

Створіть 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" належить до правил specs, а не до глобального контексту)

Опустіть усе загальне, що моделі ШІ вже знають. Будьте безжалісні до лаконічності.

ШІ допоможе вам визначити, що є важливим, а що можна скоротити.

Нові команди

Доступність команд залежить від профілю:

За замовчуванням (профіль 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 використовує новий стандарт навичок (skills):

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Навички розпізнаються кількома інструментами ШІ-кодування та надають більш багату метадані.

Codex у OPSX працює лише з навичками. 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. Навички виявляються під час запуску.

«Невідомий 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/
│       ├── 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 ​

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

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

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

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

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

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

«Невідомий ID артефакту в правилах» ​

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

Файл project.md не мігрував ​

Хочете переглянути, що буде очищено? ​

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

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

Що було видалено ​

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

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

Перехід на OPSX

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

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

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

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

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

Виконання міграції

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

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

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

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

До (project.md)

Після (config.yaml)

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

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

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

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

Нові команди

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

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

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

Від фазової блокування до гнучкості

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

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

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

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

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

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

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

Власні схеми

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

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

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

«Невідомий ID артефакту в правилах»

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

Файл project.md не мігрував

Хочете переглянути, що буде очищено?

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

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

Що було видалено

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

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