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

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

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

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

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

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

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

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

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

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

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

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

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

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

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

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

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

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

Рецепт 3: Дослідження перед фіксацією змін

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

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

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

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

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

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

Рецепт 4: Робота з двома змінами одночасно

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

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

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

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

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

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

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

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

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Порожню дельта зазначте явно, встановивши skip_specs: true у файлі .openspec.yaml зміни:

schema: spec-driven
skip_specs: true

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

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

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

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

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

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

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

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

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

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

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

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

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

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

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

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

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

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

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

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

Куди рухатися далі

• Спочатку дослідження: рекомендований спосіб початку роботи, якщо ви не впевнені
• Робочі процеси: наведені вище шаблони з підказками, коли використовувати кожен з них
• Команди: детальний опис усіх слэш-команд
• Початок роботи: офіційне покрокове керівництво з реалізації першої зміни
• Концепції: пояснення, чому компоненти взаємодіють саме так, а не інакше