Робочий процес OPSX

Зворотній зв'язок вітається на Discord.

Що це таке?

OPSX тепер є стандартним робочим процесом для OpenSpec.

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

Чому це існує

Старий робочий процес OpenSpec працює, але він заблокований:

• Інструкції зашиті в код — заховані в TypeScript, ви не можете їх змінити
• Все або нічого — одна велика команда створює все, не можна перевірити окремі частини
• Фіксована структура — однаковий робочий процес для всіх, без можливості налаштування
• Чорна скринька — коли вивід ШІ поганий, ви не можете налаштувати підказки

OPSX відкриває його. Тепер кожен може:

1. Експериментувати з інструкціями — редагувати шаблон, бачити, чи краще працює ШІ
2. Тестувати поетапно — перевіряти інструкції для кожного артефакту окремо
3. Налаштовувати робочі процеси — визначати власні артефакти та залежності
4. Швидко ітерувати — змінювати шаблон, тестувати негайно, без перезбірки

Старий робочий процес:                OPSX:
┌────────────────────────┐           ┌────────────────────────┐
│  Зашитий в пакеті      │           │  schema.yaml           │◄── Ви редагуєте це
│  (неможливо змінити)   │           │  templates/*.md        │◄── Або це
│        ↓               │           │        ↓               │
│  Чекати на новий випуск│           │  Негайний ефект        │
│        ↓               │           │        ↓               │
│  Сподіватися, що буде  │           │  Тестуйте самі         │
│  краще                 │           │                        │
└────────────────────────┘           └────────────────────────┘

Це для всіх:

• Команди — створюйте робочі процеси, які відповідають вашому реальному способу роботи
• Досвідчені користувачі — налаштовуйте підказки для кращого виводу ШІ для вашого коду
• Учасники OpenSpec — експериментуйте з новими підходами без випусків

Ми всі ще вчимося, що працює найкраще. OPSX дозволяє нам вчитися разом.

Досвід користувача

Проблема лінійних робочих процесів: Ви "на етапі планування", потім "на етапі реалізації", потім "готово". Але реальна робота так не працює. Ви реалізуєте щось, розумієте, що ваш дизайн був неправильним, потрібно оновити специфікації, продовжувати реалізацію. Лінійні етапи борються з тим, як робота насправді відбувається.

Підхід OPSX:

• Дії, а не етапи — створюйте, реалізовуйте, оновлюйте, архівуйте — робіть будь-яку з них у будь-який час
• Залежності — це можливості — вони показують, що можливо, а не що потрібно робити далі

  proposal ──→ specs ──→ design ──→ tasks ──→ implement

Встановлення

# Переконайтеся, що встановлено openspec — навички генеруються автоматично
openspec init

Це створює навички в .claude/skills/ (або еквіваленті), які автоматично виявляють асистенти кодування ШІ.

За замовчуванням OpenSpec використовує профіль робочого процесу core (propose, explore, apply, archive). Якщо ви хочете розширені команди робочого процесу (new, continue, ff, verify, sync, bulk-archive, onboard), налаштуйте їх за допомогою openspec config profile та застосуйте за допомогою openspec update.

Під час встановлення вам запропонують створити конфігурацію проєкту (openspec/config.yaml). Це необов'язково, але рекомендується.

Конфігурація проєкту

Конфігурація проєкту дозволяє встановити значення за замовчуванням та вставляти контекст, специфічний для проєкту, в усі артефакти.

Створення конфігурації

Конфігурація створюється під час openspec init або вручну:

# openspec/config.yaml
schema: spec-driven

context: |
  Технологічний стек: TypeScript, React, Node.js
  Конвенції API: RESTful, JSON-відповіді
  Тестування: Vitest для модульних тестів, Playwright для e2e
  Стиль: ESLint з Prettier, строгий TypeScript

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

Поля конфігурації

Поле	Тип	Опис
schema	string	Схема за замовчуванням для нових змін (наприклад, spec-driven)
context	string	Контекст проєкту, що вставляється в інструкції кожного артефакту
rules	object	Правила для кожного артефакту, з індексацією за ID артефакту

Як це працює

Пріоритет схеми (від найвищого до найнижчого):

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

Вставка контексту:

• Контекст додається на початок інструкцій кожного артефакту
• Обгортається тегами <context>...</context>
• Допомагає ШІ зрозуміти конвенції вашого проєкту

Вставка правил:

• Правила вставляються тільки для відповідних артефактів
• Обгортаються тегами <rules>...</rules>
• З'являються після контексту, перед шаблоном

ID артефактів за схемою

spec-driven (за замовчуванням):

• proposal — Пропозиція зміни
• specs — Специфікації
• design — Технічний дизайн
• tasks — Завдання реалізації

Валідація конфігурації

• Невідомі ID артефактів у rules генерують попередження
• Назви схем перевіряються за наявними схемами
• Контекст має обмеження розміру 50KB
• Невалідний YAML повідомляється з номерами рядків

Усунення проблем

"Unknown artifact ID in rules: X"

• Перевірте, що ID артефактів відповідають вашій схемі (див. список вище)
• Запустіть openspec schemas --json, щоб побачити ID артефактів для кожної схеми

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

• Переконайтеся, що файл знаходиться за шляхом openspec/config.yaml (не .yml)
• Перевірте синтаксис YAML за допомогою валідатора
• Зміни конфігурації набувають чинності негайно (перезапуск не потрібен)

Контекст занадто великий:

• Контекст обмежений 50KB
• Підсумуйте або посилайтеся на зовнішню документацію замість цього

Команди

Команда	Що вона робить
/opsx:propose	Створює зміну та генерує артефакти планування за один крок (шлях за замовчуванням)
/opsx:explore	Обмірковує ідеї, досліджує проблеми, уточнює вимоги
/opsx:new	Починає нову зміну (розширений робочий процес)
/opsx:continue	Створює наступний артефакт (розширений робочий процес)
/opsx:ff	Прискорює створення артефактів планування (розширений робочий процес)
/opsx:apply	Реалізує завдання, оновлюючи артефакти за потреби
/opsx:verify	Перевіряє реалізацію відповідно до артефактів (розширений робочий процес)
/opsx:sync	Синхронізує дельта-специфікації з основною (розширений робочий процес, необов'язковий)
/opsx:archive	Архівує при завершенні
/opsx:bulk-archive	Архівує кілька завершених змін (розширений робочий процес)
/opsx:onboard	Керований огляд зміни від початку до кінця (розширений робочий процес)

Використання

Дослідити ідею

/opsx:explore

Обмірковуйте ідеї, досліджуйте проблеми, порівнюйте варіанти. Структура не потрібна — просто партнер для мислення. Коли інсайти кристалізуються, переходьте до /opsx:propose (за замовчуванням) або /opsx:new//opsx:ff (розширений).

Розпочати нову зміну

/opsx:propose

Створює зміну та генерує артефакти планування, необхідні перед реалізацією.

Якщо ви увімкнули розширені робочі процеси, ви можете натомість використовувати:

/opsx:new        # тільки каркас
/opsx:continue   # створювати по одному артефакту
/opsx:ff         # створити всі артефакти планування одразу

Створювати артефакти

/opsx:continue

Показує, що готове до створення на основі залежностей, потім створює один артефакт. Використовуйте повторно для поетапного нарощування вашої зміни.

/opsx:ff add-dark-mode

Створює всі артефакти планування одразу. Використовуйте, коли ви маєте чітке уявлення про те, що створюєте.

Реалізувати (гнучка частина)

/opsx:apply

Опрацьовує завдання, відмічаючи їх виконання. Якщо ви працюєте з кількома змінами одночасно, ви можете запустити /opsx:apply <name>; інакше він має визначити з розмови та запропонувати вибір, якщо не може визначити.

Завершити

/opsx:archive   # Перейти до архіву при завершенні (пропонує синхронізувати специфікації за потреби)

Коли оновлювати, а коли починати заново

Ви завжди можете редагувати свою пропозицію або специфікації перед реалізацією. Але коли вдосконалення стає "іншою роботою"?

Що фіксує пропозиція

Пропозиція визначає три речі:

1. Намір — Яку проблему ви вирішуєте?
2. Обсяг — Що входить/не входить до обсягу?
3. Підхід — Як ви це вирішите?

Питання: що змінилося і наскільки?

Оновлюйте існуючу зміну, коли:

Той самий намір, вдосконалена реалізація

• Ви виявили крайні випадки, які не враховували
• Підхід потребує коригування, але мета не змінилася
• Реалізація показала, що дизайн був дещо неправильним

Обсяг звужується

• Ви зрозуміли, що повний обсяг занадто великий, хочете випустити MVP спочатку
• "Додати темний режим" → "Додати перемикач темного режиму (системні налаштування у v2)"

Коригування на основі навчання

• Кодова база не структурована так, як ви думали
• Залежність не працює, як очікувалося
• "Використовувати CSS-змінні" → "Натомість використовувати префікс dark: від Tailwind"

Починайте нову зміну, коли:

Намір фундаментально змінився

• Сама проблема тепер інша
• "Додати темний режим" → "Додати комплексну систему тем з кастомними кольорами, шрифтами, відступами"

Обсяг вибухнув

• Зміна виросла настільки, що це фактично інша робота
• Оригінальна пропозиція була б невпізнаваною після оновлень
• "Виправити помилку входу" → "Переписати систему автентифікації"

Оригінал можна завершити

• Оригінальну зміну можна позначити як "виконану"
• Нова робота є самостійною, не вдосконаленням
• Завершити "Додати темний режим MVP" → Архівувати → Нова зміна "Покращити темний режим"

Евристики

                        ┌─────────────────────────────────────┐
                        │     Це та сама робота?              │
                        └──────────────┬──────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
             Той самий намір?   >50% перекриття?   Чи можна оригінал
             Та сама проблема?  Той самий обсяг?    позначити як "виконаний"
                    │                  │           без цих змін?
                    │                  │                  │
          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
          │                 │  │             │   │               │
         ТАК               НІ ТАК           НІ  НІ              ТАК
          │                 │  │             │   │               │
          ▼                 ▼  ▼             ▼   ▼               ▼
       ОНОВИТИ          НОВА ОНОВИТИ       НОВА ОНОВИТИ          НОВА

Тест	Оновлення	Нова зміна
Ідентичність	"Те саме, вдосконалене"	"Інша робота"
Перекриття обсягу	>50% перекриття	<50% перекриття
Завершення	Не може бути "виконаним" без змін	Можна завершити оригінал, нова робота самостійна
Історія	Ланцюжок оновлень розповідає зрозумілу історію	Патчі більше заплутають, ніж прояснять

Принцип

Оновлення зберігає контекст. Нова зміна забезпечує ясність.

Обирайте оновлення, коли історія вашого мислення цінна. Обирайте нову зміну, коли почати заново було б зрозуміліше, ніж виправляти.

Уявіть це як гілки git:

• Продовжуйте комітити, працюючи над тією ж функцією
• Починайте нову гілку, коли це справді нова робота
• Іноді зливайте часткову функцію та починайте заново для фази 2

Що відрізняється?

	Спадщина (/openspec:proposal)	OPSX (/opsx:*)
Структура	Великий документ-пропозиція	Окремі артефакти з залежностями
Робочий процес	Лінійні фази: план → реалізація → архів	Гнучкі дії — робіть що завгодно, коли завгодно
Ітерація	Незручно повертатися	Оновлюйте артефакти по мірі навчання
Налаштування	Фіксована структура	Керована схемою (визначайте власні артефакти)

Ключове розуміння: робота не є лінійною. OPSX припиняє прикидатися, що це так.

Глибоке занурення в архітектуру

Цей розділ пояснює, як працює OPSX "під капотом" та як він порівнюється зі старим робочим процесом. Приклади в цьому розділі використовують розширений набір команд (new, continue тощо); користувачі за замовчуванням core можуть відобразити той самий процес на propose → apply → archive.

Філософія: Фази проти Дій

┌─────────────────────────────────────────────────────────────────────────────┐
│                         СТАРИЙ РОБОЧИЙ ПРОЦЕС                                │
│                    (Прив'язаний до фаз, Все-або-нічого)                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐             │
│   │   ПЛАНУВАННЯ │ ───► │  РЕАЛІЗАЦІЯ  │ ───► │  АРХІВУВАННЯ │             │
│   │     ФАЗА     │      │     ФАЗА     │      │     ФАЗА     │             │
│   └──────────────┘      └──────────────┘      └──────────────┘             │
│         │                     │                     │                       │
│         ▼                     ▼                     ▼                       │
│   /openspec:proposal   /openspec:apply      /openspec:archive              │
│                                                                             │
│   • Створює ВСІ артефакти одразу                                          │
│   • Не можна повернутися для оновлення специфікацій під час реалізації      │
│   • Ворота фаз забезпечують лінійне просування                              │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                         РОБОЧИЙ ПРОЦЕС OPSX                                  │
│                      (Гнучкі дії, Ітеративний)                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│              ┌────────────────────────────────────────────┐                 │
│              │           ДІЇ (не фази)                   │                 │
│              │                                            │                 │
│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
│              │    │          │           │           │    │                 │
│              │    └──────────┴───────────┴───────────┘    │                 │
│              │              у будь-якому порядку           │                 │
│              └────────────────────────────────────────────┘                 │
│                                                                             │
│   • Створюйте артефакти по одному АБО швидко перемотуйте вперед            │
│   • Оновлюйте специфікації/дизайн/завдання під час реалізації              │
│   • Залежності забезпечують прогрес, фази не існують                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Архітектура компонентів

Старий робочий процес використовує жорстко закодовані шаблони в TypeScript:

┌─────────────────────────────────────────────────────────────────────────────┐
│                   КОМПОНЕНТИ СТАРОГО РОБОЧОГО ПРОЦЕСУ                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Жорстко закодовані шаблони (рядки TypeScript)                              │
│                    │                                                        │
│                    ▼                                                        │
│   Специфічні для інструменту конфігуратори/адаптери                         │
│                    │                                                        │
│                    ▼                                                        │
│   Згенеровані файли команд (.claude/commands/openspec/*.md)                 │
│                                                                             │
│   • Фіксована структура, немає усвідомлення артефактів                      │
│   • Зміни вимагають модифікації коду + перезбірки                           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

OPSX використовує зовнішні схеми та графовий рушій залежностей:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         КОМПОНЕНТИ OPSX                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Визначення схем (YAML)                                                   │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  name: spec-driven                                                  │   │
│   │  artifacts:                                                         │   │
│   │    - id: proposal                                                   │   │
│   │      generates: proposal.md                                         │   │
│   │      requires: []              ◄── Залежності                       │   │
│   │    - id: specs                                                      │   │
│   │      generates: specs/**/*.md  ◄── Шаблони glob                     │   │
│   │      requires: [proposal]      ◄── Дозволяє після proposal          │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   Рушій графа артефактів                                                   │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • Топологічне сортування (порядок залежностей)                     │   │
│   │  • Визначення стану (наявність у файловій системі)                  │   │
│   │  • Генерація збагачених інструкцій (шаблони + контекст)             │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   Файли навичок (.claude/skills/openspec-*/SKILL.md)                        │
│                                                                             │
│   • Сумісність між редакторами (Claude Code, Cursor, Windsurf)              │
│   • Навички запитують CLI для структурованих даних                          │
│   • Повністю налаштовується через файли схем                                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Модель графа залежностей

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

                              proposal
                             (кореневий вузол)
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
                    ▼                           ▼
                 specs                       design
              (потребує:                  (потребує:
               proposal)                   proposal)
                    │                           │
                    └─────────────┬─────────────┘
                                  │
                                  ▼
                               tasks
                           (потребує:
                           specs, design)
                                  │
                                  ▼
                          ┌──────────────┐
                          │    ФАЗА      │
                          │   APPLY      │
                          │ (потребує:   │
                          │  tasks)      │
                          └──────────────┘

Переходи стану:

   ЗАБЛОКОВАНО ────────────────► ГОТОВО ────────────────► ВИКОНАНО
      │                           │                       │
   Відсутні                   Всі залежності           Файл існує
   залежності                  ВИКОНАНІ                 у файловій системі

Потік інформації

Старий робочий процес — агент отримує статичні інструкції:

  Користувач: "/openspec:proposal"
           │
           ▼
  ┌─────────────────────────────────────────┐
  │  Статичні інструкції:                   │
  │  • Створити proposal.md                 │
  │  • Створити tasks.md                    │
  │  • Створити design.md                   │
  │  • Створити specs/<capability>/spec.md  │
  │                                         │
  │  Немає усвідомлення того, що існує або │
  │  залежностей між артефактами            │
  └─────────────────────────────────────────┘
           │
           ▼
  Агент створює ВСІ артефакти одразу

OPSX — агент запитує збагачений контекст:

  Користувач: "/opsx:continue"
           │
           ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Крок 1: Запит поточного стану                                          │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec status --change "add-auth" --json                      │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "artifacts": [                                                  │  │
  │  │      {"id": "proposal", "status": "done"},                         │  │
  │  │      {"id": "specs", "status": "ready"},      ◄── Перший готовий   │  │
  │  │      {"id": "design", "status": "ready"},                          │  │
  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
  │  │    ]                                                               │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  Крок 2: Отримати збагачені інструкції для готового артефакту            │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec instructions specs --change "add-auth" --json          │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "template": "# Специфікація\n\n## ДОДАНІ вимоги...",            │  │
  │  │    "dependencies": [{"id": "proposal", "path": "...", "done": true}│  │
  │  │    "unlocks": ["tasks"]                                            │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  Крок 3: Прочитати залежності → Створити ОДИН артефакт → Показати, що   │
  │  розблоковано                                                            │
  └──────────────────────────────────────────────────────────────────────────┘

Модель ітерації

Старий робочий процес — незручно для ітерацій:

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │/proposal│ ──► │ /apply  │ ──► │/archive │
  └─────────┘     └─────────┘     └─────────┘
       │               │
       │               ├── "Зачекайте, дизайн неправильний"
       │               │
       │               ├── Варіанти:
       │               │   • Редагувати файли вручну (ламає контекст)
       │               │   • Відмовитися і почати заново
       │               │   • Продовжити і виправити пізніше
       │               │
       │               └── Немає офіційного механізму "повернутися назад"
       │
       └── Створює ВСІ артефакти одразу

OPSX — природна ітерація:

  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
      │                │                  │
      │                │                  ├── "Дизайн неправильний"
      │                │                  │
      │                │                  ▼
      │                │            Просто відредагуйте design.md
      │                │            і продовжуйте!
      │                │                  │
      │                │                  ▼
      │                │         /opsx:apply підхоплює
      │                │         там, де ви зупинилися
      │                │
      │                └── Створює ОДИН артефакт, показує, що розблоковано
      │
      └── Створює каркас зміни, чекає на вказівки

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

Створюйте робочі процеси за допомогою команд керування схемами:

# Створити нову схему з нуля (інтерактивно)
openspec schema init my-workflow

# Або розгалузити існуючу схему як початкову точку
openspec schema fork spec-driven my-workflow

# Перевірити структуру вашої схеми
openspec schema validate my-workflow

# Подивитися, звідки розв'язується схема (корисно для налагодження)
openspec schema which my-workflow

Схеми зберігаються в openspec/schemas/ (локально для проекту, під контролем версій) або ~/.local/share/openspec/schemas/ (глобально для користувача).

Структура схеми:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

Приклад schema.yaml:

name: research-first
artifacts:
  - id: research        # Додано перед proposal
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]  # Тепер залежить від research

  - id: tasks
    generates: tasks.md
    requires: [proposal]

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

   research ──► proposal ──► tasks

Підсумок

Аспект	Старий	OPSX
Шаблони	Жорстко закодовані TypeScript	Зовнішні YAML + Markdown
Залежності	Немає (все одразу)	DAG з топологічним сортуванням
Стан	Ментальна модель, заснована на фазах	Наявність у файловій системі
Налаштування	Редагувати джерело, перебудовувати	Створити schema.yaml
Ітерація	Прив'язана до фаз	Гнучка, редагуйте будь-що
Підтримка редактора	Специфічні для інструменту конфігуратори/адаптери	Єдиний каталог навичок

Схеми

Схеми визначають, які артефакти існують та їхні залежності. Наразі доступні:

• spec-driven (за замовчуванням): пропозиція → специфікації → дизайн → завдання

# List available schemas
openspec schemas

# See all schemas with their resolution sources
openspec schema which --all

# Create a new schema interactively
openspec schema init my-workflow

# Fork an existing schema for customization
openspec schema fork spec-driven my-workflow

# Validate schema structure before use
openspec schema validate my-workflow

Поради

• Використовуйте /opsx:explore, щоб обміркувати ідею перед тим, як впроваджувати зміни
• /opsx:ff — коли ви вже знаєте, що хочете зробити, /opsx:continue — під час дослідження
• Під час /opsx:apply, якщо щось не так — виправте артефакт, а потім продовжуйте
• Завдання відстежують прогрес за допомогою прапорців у файлі tasks.md
• Перевіряйте статус у будь-який час: openspec status --change "name"

Зворотній зв'язок

Це грубо. Це навмисно — ми вчимося, що працює.

Знайшли помилку? Маєте ідеї? Приєднуйтесь до нас на Discord або створіть issue на GitHub.