OpenSpec

Приклади та рецепти ​

Реальні зміни, від початку до кінця. Кожен рецепт показує команди, які ви вводите, і те, що ви побачите у відповідь, щоб ви могли зіставити свою ситуацію з шаблоном і скопіювати його. Тут використовуються стандартні основні команди (propose, explore, apply, update, sync, archive); там, де допомагає розширений набір, це зазначено.

Нагадування перед початком: слеш-команди, як-от /opsx:propose, вводяться у чат AI-асистента, а команди openspec — у терміналі. Якщо це для вас нове, спочатку прочитайте Як працюють команди. У наведених нижче транскриптах You: і AI: — це чат, а рядки, що починаються з $, — термінал.

Ще не впевнені, що саме будуєте? Більшість цих рецептів стають гострішими, якщо спочатку скористатися /opsx:explore, щоб обміркувати ідею. Рецепт 3 показує це в дії, а посібник Спочатку дослідіть наводить усі аргументи.

Рецепт 1: Невелика функція, швидкий шлях ​

Коли використовувати: ви знаєте, чого хочете, і це автономний шматок роботи. Це найпоширеніший рецепт.

Весь процес — це три команди. Запропонуйте, реалізуйте, заархівуйте.

text
You: /opsx:propose add-logout-button

AI:  Створено openspec/changes/add-logout-button/
     ✓ proposal.md — чому і що
     ✓ specs/      — нова вимога та її сценарії
     ✓ design.md   — технічний підхід
     ✓ tasks.md    — контрольний список реалізації
     Готово до реалізації. Запустіть /opsx:apply.

Тепер прочитайте план. Відкрийте пропозицію та дельта-специфікацію. Це саме той момент, для якого створено OpenSpec: виявити неправильне припущення, поки воно ще є одним абзацом, а не 400 рядками коду. Якщо щось не так, відредагуйте будь-який артефакт безпосередньо, а потім продовжуйте.

text
You: /opsx:apply

AI:  Виконую завдання...
     ✓ 1.1 Додати кнопку виходу до заголовка
     ✓ 1.2 Очищати сесію після натискання
     ✓ 1.3 Додати діалог підтвердження
     Усі завдання виконано!

You: /opsx:archive

AI:  Архівую add-logout-button...
     ✓ Специфікації об'єднано в openspec/specs/auth/spec.md
     ✓ Переміщено до openspec/changes/archive/2026-06-22-add-logout-button/
     Готово. Можна братися за наступну зміну.

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

Рецепт 2: Виправлення помилки ​

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

Виправлення помилок працюють так само, як функції. Різниця в тому, як ви формулюєте пропозицію: опишіть правильну поведінку, а не просто «виправити помилку».

text
You: /opsx:propose fix-login-redirect-loop

AI:  Створено openspec/changes/fix-login-redirect-loop/
     Пропозиція фіксує поточну неправильну поведінку та бажану
     поведінку. Дельта-специфікація МОДИФІКУЄ вимогу до
     перенаправлення, роблячи її точною та придатною для тестування.
     Готово до реалізації.

Оскільки виправлення потрапляє як MODIFIED вимога з новим сценарієм, наступна людина (або наступний AI-сеанс) бачить не лише те, що ви виправили, а й що означає «правильно». Потім /opsx:apply та /opsx:archive як зазвичай.

Порада: для виправлення гарний сценарій — це регресійний тест, описаний прозою. «GIVEN незалогінений користувач, WHEN він надсилає дійсні облікові дані, THEN він потрапляє на панель керування і не перенаправляється знову». Напишіть це, і реалізація отримає чітку ціль.

Рецепт 3: Дослідження перед тим, як взятися до роботи ​

Коли використовувати: у вас є проблема, але ще немає плану. Ви не впевнені, що будувати, або який підхід правильний.

Почніть із /opsx:explore. Це партнер для роздумів без жодної структури та створення артефактів. Він читає вашу кодову базу і допомагає вирішити.

text
You: /opsx:explore

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

You: Завантаження сторінок здається повільним, але я не знаю, куди йде час.

AI:  Давайте подивимося... Я знайшов три ймовірні причини:
     1. Великі неоптимізовані зображення на сторінці списку товарів
     2. Синхронне отримання даних, яке блокує рендеринг
     3. Повторні рендеринги, спричинені змінами контексту
     З якої почати?

You: З отримання даних.

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

AI:  Створено зміну з пропозицією, яка враховує те, що ми щойно
     знайшли. Готово до реалізації.

Дослідження прояснює ваше мислення до того, як ви витратите на це окрему зміну. Коли розуміння викристалізується, запропонуйте, і AI перенесе контекст далі.

Рецепт 4: Жонглювання двома змінами одночасно ​

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

Зміни — це незалежні папки, тому паралельна робота не конфліктує. Почніть виправлення, відвантажте його, а потім поверніться до функції там, де зупинилися.

text
You: Я на півдорозі до add-dark-mode, але зараз потрібно виправити помилку входу.

You: /opsx:propose fix-login-redirect

AI:  Створено openspec/changes/fix-login-redirect/. Готово до реалізації.

You: /opsx:apply

AI:  Виправлення реалізовано. Усі завдання виконано.

You: /opsx:archive

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

You: Повертаюся до темної теми.

You: /opsx:apply add-dark-mode

AI:  Відновлюю add-dark-mode. Продовжую з завдання 2.3: Оновити заголовок...

Вказуючи назву зміни в /opsx:apply add-dark-mode, ви спрямовуєте AI на конкретну зміну, коли їх активно кілька. Оскільки завдання відстежують завершення в tasks.md, AI точно знає, на чому ви зупинилися.

Коли кілька змін завершуються одночасно, розширена команда /opsx:bulk-archive архівує їх разом і вирішує конфлікти специфікацій, перевіряючи, що фактично реалізовано. Див. Робочі процеси.

Рецепт 5: Рефакторинг без зміни поведінки ​

Коли використовувати: ви переструктуровуєте код, а зовнішньо видима поведінка повинна залишатися незмінною.

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

text
You: /opsx:propose refactor-payment-module

AI:  Створено зміну. Пропозиція визначає мету (розділити
     платіжний модуль, без зміни поведінки), а дизайн фіксує
     нову структуру. Жодних змін специфікацій, оскільки поведінка ідентична.
     Готово до реалізації.

Оголосіть порожню дельту явно, встановивши skip_specs: true у .openspec.yaml зміни:

yaml
schema: spec-driven
skip_specs: true

Без цього маркера openspec validate відхиляє зміну з нульовою кількістю дельт (тому пропущений етап специфікацій все одно буде виявлено); з ним валідація проходить, а openspec status показує етап специфікацій як явно пропущений, а не як очікуваний. Якщо з'ясується, що рефакторинг все ж змінює поведінку, видаліть skip_specs з .openspec.yaml і напишіть дельта-специфікації — валідація розглядає маркер разом з файлами специфікацій як конфлікт, тому застарілий маркер не може залишатися непоміченим.

Архівування зміни з маркером не потребує додаткових прапорців (немає дельт для об'єднання). Незалежно від цього, прапорець --skip-specs вказує термінальній команді явно пропустити крок специфікацій:

bash
$ openspec archive refactor-payment-module --skip-specs

Цей самий прапорець стане в пригоді для інструментів, CI та змін лише в документації. Принцип: специфікації описують поведінку, тому якщо поведінка не змінилася, специфікація теж не повинна. Див. Концепції.

Рецепт 6: Покроковий контроль (розширені команди) ​

Коли використовувати: складна або ризикована зміна, де ви хочете переглянути кожен артефакт перед тим, як рухатися далі.

Основна команда /opsx:propose формує чернетку всього одразу. Якщо ви віддаєте перевагу проходити крок за кроком, увімкніть розширені команди:

bash
$ openspec config profile      # вибрати розширені робочі процеси
$ openspec update              # застосувати їх до цього проєкту

Тепер ви можете створювати каркас і будувати поступово:

text
You: /opsx:new add-2fa

AI:  Створено openspec/changes/add-2fa/. Готово до створення: proposal.

You: /opsx:continue

AI:  Створено proposal.md. Тепер доступні: specs, design.

You: /opsx:continue

AI:  Створено specs/auth/spec.md. Тепер доступний: design.

Переглядайте кожен артефакт одразу після створення, вільно редагуйте та продовжуйте, коли задоволені. Якщо ви хочете, щоб решта артефактів планування була створена однією командою, /opsx:ff прискорено проходить через них. Перед архівуванням /opsx:verify перевіряє, чи реалізація дійсно відповідає специфікаціям. Див. Робочі процеси.

Рецепт 7: Практичне вивчення всього циклу ​

Коли використовувати: ви встановили OpenSpec і хочете відчути робочий процес на власному коді, а не на іграшковому прикладі.

Увімкніть розширені команди (див. Рецепт 6), а потім:

text
You: /opsx:onboard

AI:  Ласкаво просимо до OpenSpec! Я проведу вас через повну зміну,
     використовуючи вашу реальну кодову базу. Дозвольте мені пошукати
     невелике, безпечне покращення, яке ми можемо зробити разом...

/opsx:onboard знаходить реальне (невелике) покращення, створює для нього зміну, реалізує та архівує її, розповідаючи про кожен крок. Це займає від 15 до 30 хвилин і залишає вам реальну зміну, яку можна зберегти або відкинути. Це найм'якший спосіб навчитися. Див. Команди.

Перевірка роботи з терміналу ​

У будь-який час з терміналу ви можете перевірити стан справ:

bash
$ openspec list                      # активні зміни
$ openspec show add-dark-mode        # одна зміна в деталях
$ openspec validate add-dark-mode    # перевірити структуру
$ openspec view                      # інтерактивна панель

Це інструменти для читання та перевірки. Пропонування та реалізація, як і раніше, відбуваються через слеш-команди в чаті. Детальніше — у довідці CLI.

Куди йти далі ​