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

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

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

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

OPSX має інший підхід:

Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

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

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

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

Два Режими

Стандартний Швидкий Шлях (core profile)

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

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

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

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (необов'язково)

Почніть з дослідження (звичка, яку варто сформувати)

/opsx:explore є частиною стандартного профілю, а не розширеним доповненням. Це крок, який слід зробити, коли у вас є проблема, але ще немає плану, що, як правило, і трапляється.

Ви: /opsx:explore

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

Ви: Наші результати пошуку здаються застарілими. Я не впевнений, чи це кешування, індексація, чи сам запит.

ШІ: Дайте мені подивитися... [читає сервіс пошуку та рівень кешу]
Це індекс: він перебудовується лише щоночі, тому зміни не відображаються до наступного дня. Є два варіанти: rebuild on write (просто, більше навантаження) або короткочасне скасування кешу (більше елементів, менше навантаження). Зважаючи на низький обсяг ваших записів, rebuild-on-write є чистішим рішенням. Чи хочете ви його обмежити?

Ви: Так.

Ви: /opsx:propose rebuild-search-index-on-write

Explore не створює артефактів і не пише код. Це безкоштовна розмова без ризиків, яка перетворює невизначене занепокоєння на чітку зміну, щоб подальша пропозиція була гострою. Уже знаєте, що саме хочете? Пропустіть цей крок і переходьте прямо до /opsx:propose. Повний посібник: Explore First.

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

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

openspec config profile
openspec update

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

Швидка Функція (Quick Feature)

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

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

Приклад діалогу:

Ви: /opsx:new add-logout-button

ШІ: Створено openspec/changes/add-logout-button/
Готовий створити: proposal

Ви: /opsx:ff

ШІ: Створюю всі планувальні артефакти...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Готовий до реалізації!

Ви: /opsx:apply

ШІ: Працюю над завданнями...
     ✓ Додано кнопку виходу з системи в заголовок
     ✓ Реалізовано очищення сесії
     ✓ Додано діалогове вікно підтвердження
     Усі завдання виконані!

Ви: /opsx:archive

ШІ: ✓ Зібрано специфікації
     ✓ Зархівовано зміну

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

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

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

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

Приклад діалогу:

Ви: /opsx:explore

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

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

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

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

     Що ви хотіли б вирішити в першу чергу?

Ви: Давайте займемося проблемою отримання даних.

Ви: /opsx:new optimize-product-list-fetching

ШІ: Створено зміну. Готовий створити: proposal

Ви: /opsx:continue

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

     Готовий створити: specs, design
     Що хотіли б далі?

Ви: /opsx:continue

ШІ: Створюю специфікації...

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

Паралельні Зміни (Parallel Changes)

Працюйте над кількома змінами одночасно:

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

Приклад діалогу:

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

Ви: /opsx:new fix-login-redirect

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

Ви: /opsx:ff

ШІ: ✓ Створено планувальні артефакти

Ви: /opsx:apply

ШІ: Працюю над fix-login-redirect...
     [Реалізує виправлення]
     Усі завдання виконані!

Ви: /opsx:archive

ШІ: ✓ Зархівовано fix-login-redirect

Ви: Повертаємося до dark mode.

Ви: /opsx:apply add-dark-mode

ШІ: Відновлюю add-dark-mode...
     Починаючи з завдання 2.3: Оновлення заголовка...

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

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

Ви: /opsx:bulk-archive

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

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

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

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

Ви: Так

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

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

Завершення Зміни (Completing a Change)

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

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

Verify: Перевірте Свою Роботу (Check Your Work)

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

Ви: /opsx:verify

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

     ПОДОВІДНІСТЬ (COMPLETENESS)
     ✓ Усі 12 завдань у tasks.md перевірені
     ✓ Всі вимоги в specs мають відповідний код
     ⚠ Сценарій "Таймаут сесії після неактивності" не протестовано

     ПРАВИЛЬНІСТЬ (CORRECTNESS)
     ✓ Реалізація відповідає задуму специфікації
     ✓ Оброблені граничні випадки зі сценаріїв
     ✓ Стани помилок відповідають визначенням у специфікації

     ЗЛІМКОВІСТЬ (COHERENCE)
     ✓ Рішення дизайну відображені в структурі коду
     ✓ Назви узгоджуються з design.md
     ⚠ Дизайн згадує "event-driven", але реалізація використовує polling

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

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

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

Вимір	Що валідується
Повнота (Completeness)	Усі завдання виконані, всі вимоги реалізовані, сценарії охоплені
Правильність (Correctness)	Реалізація відповідає задуму специфікації, оброблені граничні випадки
Злімовкість (Coherence)	Рішення дизайну відображені в коді, патерни узгоджені

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

Archive: Фіналізуйте Зміну (Finalize the Change)

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

Ви: /opsx:archive

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

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

     Delta specs: Ще не синхронізовано з основним репозиторієм
     → Чи бажаєте ви синхронізувати зараз?

Ви: Так

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

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

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

Коли Що Використовувати (When to Use What)

/opsx:ff проти /opsx:continue

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

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

Коли Оновлювати проти Початкового Створення (When to Update vs Start Fresh)

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

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

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

Почніть нову зміну, коли:

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

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

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

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

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

Зберігайте Фокус Змін (Keep Changes Focused)

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

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

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

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

Перш ніж зобов'язатися щодо змін, дослідіть просторовий простір проблеми:

Ви: /opsx:explore

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

Ви: Як нам слід обробляти обмеження швидкості (rate limiting) для нашого API?

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

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

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

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

Перевірте Перед Архівуванням (Verify Before Archiving)

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

Ви: /opsx:verify

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

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

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

Це виявляє невідповідності, перш ніж ви закриєте зміну.

Чітко Називайте Зміни (Name Changes Clearly)

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

Добре:                          Уникати:
add-dark-mode                  feature-1
fix-login-redirect             оновлення
optimize-product-query         зміни
implement-2fa                  wip

Швидкий посібник команд

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

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

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

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