OpenSpec

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

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

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

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

OPSX використовує інший підхід:

text
Traditional (phase-locked):

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

OPSX (fluid actions):

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

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

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

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

Workflow at a Glance ​

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

mermaid
flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

Штучний інтелект керує робочим процесом, тоді як CLI забезпечує детермінований каркас, статус та інструкції щодо артефактів:

mermaid
sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

Два режими ​

Типовий швидкий шлях (профіль core) ​

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

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

Типовий потік:

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optional)

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

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

text
You: /opsx:explore

AI:  What would you like to explore?

You: Our search results feel stale. I'm not sure if it's caching,
     indexing, or the query itself.

AI:  Let me look... [reads the search service and cache layer]
     It's the index: it only rebuilds nightly, so edits don't show
     up until the next day. Two options: rebuild on write (simple,
     more load) or a short-TTL cache invalidation (more moving parts,
     less load). Given your write volume is low, rebuild-on-write is
     the cleaner fix. Want to scope it?

You: Yes.

You: /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), увімкніть їх за допомогою:

bash
openspec config profile
openspec update

Патерни робочого процесу (розширений режим) ​

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

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

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

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

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

AI:  Created openspec/changes/add-logout-button/
     Ready to create: proposal

You: /opsx:ff

AI:  Creating all planning artifacts...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

You: /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

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

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

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

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

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

text
You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

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

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...

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

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

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

text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

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

text
You: I'm working on add-dark-mode but got pulled into a bug fix

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Created planning artifacts

You: /opsx:apply

AI:  Working on fix-login-redirect...
     [Implements the fix]
     All tasks complete!

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect

You: Let's get back to dark mode

You: /opsx:apply add-dark-mode

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

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

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

text
You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (all tasks done)
     - fix-login-redirect (all tasks done)
     - update-footer (all tasks done)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will apply in chronological order.

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

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

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

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

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validates          prompts to sync
              implementation     if needed

Verify: перевірте свою роботу ​

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

text
You: /opsx:verify

AI:  Verifying add-auth...

     COMPLETENESS
     ✓ All 12 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Session timeout after inactivity" not tested

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "event-driven" but implementation uses polling

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for session timeout scenario
     2. Consider refactoring to event-driven as designed, or update design.md

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

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

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

Archive: фіналізуйте зміну ​

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

text
You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

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

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

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

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

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

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

Часте питання: коли оновлення наявної зміни є прийнятним, а коли варто почати нову?

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

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

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

  • Намір фундаментально змінився
  • Обсяг вибухнув у зовсім іншу роботу
  • Початкову зміну можна позначити як "виконано" самостійно
  • Патчі заплутали б більше, ніж прояснили
text
                     ┌─────────────────────────────────────┐
                     │     Is this the same work?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Same intent?      >50% overlap?      Can original
          Same problem?     Same scope?        be "done" without
                 │                  │          these changes?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

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

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

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

Зосереджуйте зміни на одній меті ​

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

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

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

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

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

text
You: /opsx:explore

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

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

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

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

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

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

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

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

text
You: /opsx:verify

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

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

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

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

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

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

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

Короткий довідник команд ​

Повні відомості про команди та опції див. у Commands.

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

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