Міграція до OPSX

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

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

OPSX замінює старий процес із фіксованими фазами на гнучкий підхід, заснований на діях. Ось ключова зміна:

Аспект	Легасі	OPSX
Командi	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`	За замовчуванням: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:update`, `/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
Devin Desktop, раніше 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 тепер використовує канонічний шлях .agents/skills/openspec-*. Файли SKILL.md, керовані OpenSpec, під колишнім шляхом .codex/skills узгоджуються лише після того, як замінники існують; власні файли та розбіжні копії залишаються на місці. Якщо непомічене дерево .agents вже містить навички OpenSpec, OpenSpec зберігає наявний рендеринг Codex ($openspec-*) або загальний (/openspec-*) замість того, щоб вгадувати зі спадкового каталогу. Оберіть codex явно за допомогою openspec init, щоб перемкнути власність. Очищення спадкових prompt-файлів все одно цільово діє лише на файли з дозвільного списку 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, update, sync, archive).
Мігровані встановлення зберігають ваші раніше встановлені робочі процеси, записуючи профіль custom, коли це необхідно.

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

Запустіть це, якщо ви хочете додати нові інструменти або переналаштувати, які інструменти налаштовано:

bash

openspec init

Команда init виявляє спадкові файли та проводить вас через очищення:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (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 пропускає запитання та автоматично приймає очищення.

Це включає очищення prompt-файлів Codex, керованих OpenSpec, у глобальному каталозі prompt-файлів Codex. Очищення цільово діє лише на спадкові prompt-файли Codex із дозвільного списку OpenSpec, видаляє їх лише після того, як замінники .agents/skills/openspec-* існують, і зберігає всі інші файли.

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

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

Перемістіть у rules:

Форматування, специфічне для артефакту («використовуйте Given/When/Then у специфікаціях»)
Критерії перегляду («пропозиції повинні містити план відкату»)
Вони з'являються лише для відповідного артефакту, що робить інші запити легшими

Повністю залишіть поза межами

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

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

Створіть config.yaml (якщо він ще не створений init):
yaml
```
schema: spec-driven
```
Додайте ваш контекст (будьте лаконічні — це потрапляє в кожен запит):
yaml
```
context: |
  Your project background goes here.
  Focus on what the AI genuinely needs to know.
```

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

yaml

rules:
  proposal:
    - Your proposal-specific guidance
  specs:
    - Your spec-writing rules

Видаліть 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.

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

Нові команди

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

Типовий (профіль core):

Команда	Призначення
`/opsx:propose`	Створити зміну та згенерувати артефакти планування за один крок
`/opsx:explore`	Розібратися в ідеях без структури
`/opsx:apply`	Реалізувати завдання з tasks.md
`/opsx:update`	Внести зміни в артефакти планування зміни та зберегти їх узгодженими
`/opsx:sync`	Об'єднати дельта-специфікації в основні специфікації
`/opsx:archive`	Завершити та архівувати зміну

Розширений робочий процес (власний вибір):

Команда	Призначення
`/opsx:new`	Почати новий каркас зміни
`/opsx:continue`	Створити наступний артефакт (по одному)
`/opsx:ff`	Швидке просування — створити артефакти планування одразу
`/opsx:verify`	Перевіритi, що реалізація відповідає специфікаціям
`/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  │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    будь-який порядок           │
         └───────────────────────────────────────────────┘

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

Артефакти утворюють орієнтований граф. Залежності є засобами сприяння, а не шлюзами:

                        пропозиція
                       (кореневий вузол)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           специфікації                 дизайн
        (вимагає:                    (вимагає:
         пропозицію)                  пропозицію)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         завдання
                     (вимагає:
                     специфікації, дизайн)

Коли ви виконуєте /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
└── ...

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

В OPSX Codex працює лише з навичками. OpenSpec більше не генерує власні файли підказок для Codex; натомість використовуйте згенеровані директорії .agents/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: |
  Your project background, tech stack,
  conventions, and constraints.

# Необов'язково: Правила для окремих артефактів
# Вставляються тільки у відповідні артефакти
rules:
  proposal:
    - Додати план відкату
  specs:
    - Використовувати формат Given/When/Then
  design:
    - Документувати стратегії відкатів
  tasks:
    - Розбивати на частини тривалістю не більше 2 годин

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

При визначенні схеми OPSX перевіряє в такому порядку:

Прапорець CLI: --schema <name> (найвищий пріоритет)
Метадані зміни: .openspec.yaml у директорії зміни
Конфігурація проєкту: openspec/config.yaml
За замовчуванням: spec-driven

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

Схема	Артефакти	Найкраще підходить
`spec-driven`	пропозиція → специфікації → дизайн → завдання	Більшість проєктів

Перелік усіх доступних схем:

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-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-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 ​

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

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

Спеціальні схеми ​

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

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

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

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

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

project.md не перенесено ​

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

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

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

Що зникло ​

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

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

Міграція до OPSX

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

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

Ваші наявні дані в безпеці

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

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

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

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

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

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

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

До (project.md)

Після (config.yaml)

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

Що зберегти, що прибрати

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

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

Нові команди

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

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

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

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

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

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

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

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

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

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

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

Спеціальні схеми

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

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

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

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

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

project.md не перенесено

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

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

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

Що зникло

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

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