Робочі процеси

Цей посібник описує типові моделі робочих процесів для OpenSpec та випадки їх використання. Для базового налаштування див. Початок роботи. Для довідки з команд див. Команди.

Філософія: Дії, а не фази

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

OPSX пропонує інший підхід:

Традиційний (прив'язаний до фаз):

  ПЛАНУВАННЯ ────────► РЕАЛІЗАЦІЯ ────────► ЗАВЕРШЕННЯ
      │                    │
      │   "Неможливо повернутися"  │
      └────────────────────┘

OPSX (динамічні дії):

  пропозиція ──► специфікації ──► дизайн ──► завдання ──► реалізація

Ключові принципи:

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

Налаштування: Робочі процеси OPSX керуються схемами, які визначають послідовності артефактів. Див. Налаштування для детальної інформації про створення власних схем.

Два режими

Шлях за замовчуванням (профіль core)

Нові встановлення за замовчуванням використовують core, який надає:

• /opsx:propose
• /opsx:explore
• /opsx:apply
• /opsx:archive

Типовий процес:

/opsx:propose ──► /opsx:apply ──► /opsx:archive

Розширений/Повний робочий процес (кастомний вибір)

Якщо вам потрібні явні команди для створення та побудови (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:sync, /opsx:bulk-archive, /opsx:onboard), увімкніть їх за допомогою:

openspec config profile
openspec update

Шаблони робочого процесу (Розширений режим)

Швидка функціональність

Коли ви знаєте, що хочете побудувати, і вам просто потрібно виконати:

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Приклад розмови:

You: /opsx:new add-logout-button

AI:  Створено openspec/changes/add-logout-button/
     Готово до створення: proposal

You: /opsx:ff

AI:  Створення всіх артефактів планування...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Готово до реалізації!

You: /opsx:apply

AI:  Виконання завдань...
     ✓ Додано кнопку виходу в заголовок
     ✓ Реалізовано очищення сесії
     ✓ Додано діалог підтвердження
     Всі завдання виконано!

You: /opsx:archive

AI:  ✓ Специфікації об'єднано
     ✓ Зміну заархівовано

Найкраще підходить для: Малих та середніх функціональностей, виправлення помилок, простих змін.

Дослідницький

Коли вимоги не зрозумілі або вам потрібно спочатку дослідити:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Приклад розмови:

You: /opsx:explore

AI:  Що б ви хотіли дослідити?

You: Я хочу покращити продуктивність завантаження сторінки, але не впевнений,
     де знаходяться вузькі місця.

AI:  Дозвольте мені допомогти з розслідуванням...
     [Аналізує розміри пакетів, визначає повільні запити, переглядає
     шаблони рендерингу компонентів]

     Я знайшов три основних вузьких місця:
     1. Великі неоптимізовані зображення
     2. Синхронне отримання даних у ProductList
     3. Повторні рендери через зміни контексту

     Яке з них ви хотіли б вирішити першим?

You: Давайте вирішимо проблему отримання даних.

You: /opsx:new optimize-product-list-fetching

AI:  Зміну створено. Готово до створення: proposal

You: /opsx:continue

AI:  Створення пропозиції на основі нашого дослідження...
     [Пише пропозицію, що включає результати дослідження]

     Готово до створення: specs, design
     Що ви хотіли б створити наступним?

You: /opsx:continue

AI:  Створення specs...

Найкраще підходить для: Оптимізації продуктивності, налагодження, архітектурних рішень, незрозумілих вимог.

Паралельні зміни

Робота над кількома змінами одночасно:

Зміна A: /opsx:new ──► /opsx:ff ──► /opsx:apply (виконується)
                                         │
                                    перемикання контексту
                                         │
Зміна B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Приклад розмови:

You: Я працюю над add-dark-mode, але мене відволікли на виправлення помилки

You: /opsx:new fix-login-redirect

AI:  Створено openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Артефакти планування створено

You: /opsx:apply

AI:  Робота над fix-login-redirect...
     [Реалізує виправлення]
     Всі завдання виконано!

You: /opsx:archive

AI:  ✓ fix-login-redirect заархівовано

You: Давайте повернемося до темного режиму

You: /opsx:apply add-dark-mode

AI:  Відновлення add-dark-mode...
     Продовження з завдання 2.3: Оновлення Header...

Найкраще підходить для: Паралельних потоків роботи, термінових переривань, командної співпраці.

Коли у вас є кілька завершених змін, використовуйте /opsx:bulk-archive:

You: /opsx:bulk-archive

AI:  Знайдено 3 завершені зміни:
     - add-dark-mode (всі завдання виконано)
     - fix-login-redirect (всі завдання виконано)
     - update-footer (всі завдання виконано)

     Перевірка конфліктів специфікацій...
     ⚠ add-dark-mode та update-footer обидві стосуються specs/ui/

     Перевірка кодової бази для вирішення...
     Обидві зміни реалізовано. Буде застосовано в хронологічному порядку.

     Заархівувати всі 3 зміни?

You: Так

AI:  ✓ add-dark-mode заархівовано
     ✓ fix-login-redirect заархівовано
     ✓ update-footer заархівовано
     Специфікації об'єднано в порядку: add-dark-mode → update-footer

Масове архівування визначає, коли кілька змін стосуються тих самих специфікацій, і вирішує конфлікти, перевіряючи, що фактично реалізовано.

Завершення зміни

Рекомендований процес завершення:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              перевіряє          пропонує синхронізацію
              реалізацію         якщо потрібно

Verify: Перевірка вашої роботи

/opsx:verify перевіряє реалізацію відповідно до ваших артефактів за трьома вимірами:

You: /opsx:verify

AI:  Перевірка add-auth...

     ПОВНОТА
     ✓ Всі 12 завдань у tasks.md позначено
     ✓ Всі вимоги у specs мають відповідний код
     ⚠ Сценарій "Час очікування сесії після бездіяльності" не протестовано

     КОРЕКТНІСТЬ
     ✓ Реалізація відповідає наміру специфікації
     ✓ Граничні випадки зі сценаріїв оброблено
     ✓ Стани помилок відповідають визначенням специфікації

     ЗВ'ЯЗНІСТЬ
     ✓ Архітектурні рішення відображені в структурі коду
     ✓ Конвенції іменування узгоджені з design.md
     ⚠ У design згадується "подієво-орієнтований", але реалізація використовує опитування

     ПІДСУМОК
     ─────────────────────────────
     Критичних проблем: 0
     Попереджень: 2
     Готово до архівування: Так (з попередженнями)

     Рекомендації:
     1. Додати тест для сценарію часу очікування сесії
     2. Розглянути рефакторинг на подієво-орієнтований, як у дизайні, або оновити design.md

Що перевіряє verify:

Вимір	Що перевіряється
Повнота	Всі завдання виконано, всі вимоги реалізовано, сценарії охоплено
Коректність	Реалізація відповідає наміру специфікації, граничні випадки оброблено
Зв'язність	Архітектурні рішення відображені в коді, шаблони узгоджені

Verify не блокує архівування, але виявляє проблеми, які ви, можливо, захочете вирішити спочатку.

Archive: Фіналізація зміни

/opsx:archive завершує зміну та переміщує її до архіву:

You: /opsx:archive

AI:  Архівування add-auth...

     Статус артефактів:
     ✓ proposal.md існує
     ✓ specs/ існує
     ✓ design.md існує
     ✓ tasks.md існує (12/12 завдань виконано)

     Дельта-специфікації: Ще не синхронізовано з основною
     → Бажаєте синхронізувати зараз?

You: Так

AI:  ✓ Специфікації синхронізовано до openspec/specs/auth/spec.md
     ✓ Переміщено до openspec/changes/archive/2025-01-24-add-auth/

     Зміну успішно заархівовано.

Archive запитає, якщо специфікації не синхронізовано. Він не блокує через незавершені завдання, але попередить вас.

Коли що використовувати

/opsx:ff vs /opsx:continue

Ситуація	Використовуйте
Зрозумілі вимоги, готові до побудови	/opsx:ff
Досліджуєте, хочете переглядати кожен крок	/opsx:continue
Хочете ітерувати пропозицію перед specs	/opsx:continue
Тиск часу, потрібно рухатися швидко	/opsx:ff
Складна зміна, хочете контролю	/opsx:continue

Правило: Якщо ви можете описати весь обсяг заздалегідь, використовуйте /opsx:ff. Якщо ви розумієте це по ходу, використовуйте /opsx:continue.

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

Поширене питання: коли можна оновлювати існуючу зміну, а коли слід починати нову?

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

• Той самий намір, вдосконалена реалізація
• Обсяг звужується (спочатку MVP, решта пізніше)
• Виправлення на основі навчання (кодова база не така, як ви очікували)
• Коригування дизайну на основі відкриттів під час реалізації

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

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

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

Приклад: "Додати темний режим"

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

Найкращі практики

Тримайте зміни сфокусованими

Одна логічна одиниця роботи на зміну. Якщо ви робите "додати функцію X і також рефакторити Y", розгляньте дві окремі зміни.

Чому це важливо:

• Легше переглядати та розуміти
• Чистіша історія архіву
• Можна випускати незалежно
• Простіше відкат, якщо потрібно

Використовуйте /opsx:explore для незрозумілих вимог

Перед тим, як братися за зміну, дослідіть проблемний простір:

You: /opsx:explore

AI:  Що б ви хотіли дослідити?

You: Як нам слід обробляти обмеження частоти запитів для нашого API?

AI:  Дозвольте мені дослідити ваше поточне середовище та варіанти...
     [Досліджує кодову базу, розглядає шаблони]

     Я бачу три підходи, які ми могли б використати:
     1. На основі middleware (простий, для кожного endpoint)
     2. На основі Redis (масштабований, спільний стан)
     3. Токен-відро на користувача (справедливий, складний)

     Ваш поточій стек вказує на #1 або #2. Який у вас масштаб?

Дослідження прояснює мислення перед створенням артефактів.

Перевіряйте перед архівуванням

Використовуйте /opsx:verify, щоб перевірити відповідність реалізації артефактам:

You: /opsx:verify

AI:  Перевірка add-dark-mode...

     ✓ Всі завдання у tasks.md позначено
     ✓ Вимоги у specs мають відповідний код
     ✓ Архітектурні рішення відображені в реалізації

     Готово до архівування!

Виявляє невідповідності перед закриттям зміни.

Називайте зміни зрозуміло

Добрі назви роблять openspec list корисним:

Добре:                          Уникайте:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Швидкий довідник команд

Для повних деталей команд та параметрів див. Команди.

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

Наступні кроки

• Команди - Повний довідник команд з параметрами
• Концепції - Глибоке занурення у специфікації, артефакти та схеми
• Налаштування - Створення користувацьких робочих процесів