Робочий процес OPSX
Ми раді отримати ваші відгуки у Discord.
Що це таке?
OPSX тепер є стандартним робочим процесом для OpenSpec.
Це гнучкий, ітеративний робочий процес для змін у OpenSpec. Жодних жорстких фаз — лише дії, які ви можете виконувати будь-коли.
Чому це існує
Легасійний робочий процес OpenSpec працює, але він заблокований:
- Інструкції захардкоджені — заховані в TypeScript, ви не можете їх змінити
- Усе або нічого — одна велика команда створює все, неможливо протестувати окремі частини
- Фіксована структура — однаковий робочий процес для всіх, без налаштування
- Чорна скринька — коли вихідні дані ШІ погані, ви не можете підкоригувати промпти
OPSX відкриває це. Тепер будь-хто може:
- Експериментувати з інструкціями — редагувати шаблон і перевірити, чи ШІ працює краще
- Тестувати гранулярно — валідувати інструкції кожного артефакта незалежно
- Налаштовувати робочі процеси — визначати власні артефакти та залежності
- Швидко ітерувати — змінити шаблон, одразу протестувати, без пересборки
Легасійний робочий процес: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Захардкоджено в пакеті│ │ schema.yaml │◄── Ви редагуєте це
│ (не можна змінити) │ │ templates/*.md │◄── Або це
│ ↓ │ │ ↓ │
│ Чекайте на новий реліз│ │ Миттєвий ефект │
│ ↓ │ │ ↓ │
│ Сподівайтеся, що краще│ │ Протестуйте самі │
└────────────────────────┘ └────────────────────────┘Це для всіх:
- Команди — створюйте робочі процеси, які відповідають вашому реальному способу роботи
- Досвідчені користувачі — коригуйте промпти, щоб отримувати кращі результати ШІ для вашого коду
- Контриб'ютори OpenSpec — експериментуйте з новими підходами без релізів
Ми всі ще вчимося, що працює найкраще. OPSX дозволяє нам вчитися разом.
Користувацький досвід
Проблема лінійних робочих процесів: Ви «на етапі планування», потім «на етапі реалізації», потім «готово». Але реальна робота не працює так. Ви реалізовуєте щось, розумієте, що ваш дизайн неправильний, потрібно оновити специфікації, продовжити реалізацію. Лінійні етапи суперечать тому, як робота відбувається насправді.
Підхід OPSX:
- Дії, а не етапи — створити, реалізувати, оновити, архівувати — робіть будь-яку з них будь-коли
- Залежності — це засоби — вони показують, що можливо, а не що потрібно зробити далі
proposal ──→ specs ──→ design ──→ tasks ──→ implementНалаштування
# Переконайтеся, що openspec встановлено — навички генеруються автоматично
openspec initЦе створює навички в .claude/skills/ (або еквівалент), які асистенти ШІ для кодування автоматично виявляють.
За замовчуванням OpenSpec використовує профіль робочого процесу core (propose, explore, apply, update, sync, archive). Якщо ви хочете розширені команди робочого процесу (new, continue, ff, verify, bulk-archive, onboard), налаштуйте їх через openspec config profile і застосуйте через openspec update.
Під час налаштування вас запитують про створення конфігурації проєкту (openspec/config.yaml). Це необов'язково, але рекомендовано.
Конфігурація проєкту
Конфігурація проєкту дозволяє встановити значення за замовчуванням та ін'єктувати контекст, специфічний для проєкту, у всі артефакти.
Створення конфігурації
Конфігурація створюється під час openspec init або вручну:
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flowsПоля конфігурації
| Поле | Тип | Опис |
|---|---|---|
schema | string | Схема за замовчуванням для нових змін (наприклад, spec-driven) |
context | string | Контекст проєкту, ін'єктований у інструкції всіх артефактів |
rules | object | Правила для кожного артефакта, індексовані за ID артефакта |
Як це працює
Пріоритет схем (від найвищого до найнижчого):
- Прапор CLI (
--schema <name>) - Метадані зміни (
.openspec.yamlу каталозі зміни) - Конфігурація проєкту (
openspec/config.yaml) - Значення за замовчуванням (
spec-driven)
Ін'єктування контексту:
- Контекст додається на початку інструкцій кожного артефакта
- Обгорнутий у теги
<context>...</context> - Допомагає ШІ зрозуміти конвенції вашого проєкту
Ін'єктування правил:
- Правила ін'єктуються лише для відповідних артефактів
- Обгорнуті в теги
<rules>...</rules> - З'являються після контексту, перед шаблоном
ID артефактів за схемою
spec-driven (за замовчуванням):
proposal— Пропозиція зміниspecs— Специфікаціїdesign— Технічний дизайнtasks— Завдання реалізації
Валідація конфігурації
- Невідомі ID артефактів у
rulesгенерують попередження - Назви схем валідуються за наявними схемами
- Контекст має обмеження розміру 50 КБ
- Невалідний YAML повідомляється з номерами рядків
Вирішення проблем
"Невідомий ID артефакта в rules: X"
- Перевірте, що ID артефактів відповідають вашій схемі (див. список вище)
- Виконайте
openspec schemas --json, щоб побачити ID артефактів для кожної схеми
Конфігурація не застосовується:
- Переконайтеся, що файл розташований у
openspec/config.yaml(не.yml) - Перевірте синтаксис YAML за допомогою валідатора
- Зміни конфігурації застосовуються миттєво (перезапуск не потрібен)
Контекст надто великий:
- Контекст обмежений 50 КБ
- Замість цього стисло описуйте або додавайте посилання на зовнішню документацію
Команди
| Команда | Що вона робить |
|---|---|
/opsx:propose | Створює зміну та генерує артефакти планування за один крок (шлях за замовчуванням) |
/opsx:explore | Розглядає ідеї, досліджує проблеми, уточнює вимоги |
/opsx:new | Починає новий каркас зміни (розширений робочий процес) |
/opsx:continue | Створює наступний артефакт (розширений робочий процес) |
/opsx:ff | Швидко створює всі артефакти планування (розширений робочий процес) |
/opsx:apply | Реалізує завдання, оновлюючи артефакти за потреби |
/opsx:update | Вносить зміни в артефакти планування зміни та зберігає їх узгодженими |
/opsx:verify | Валідує реалізацію за артефактами (розширений робочий процес) |
/opsx:sync | Об'єднує дельта-специфікації в основні специфікації (необов'язково) |
/opsx:archive | Архівує, коли закінчено |
/opsx:bulk-archive | Архівує кілька завершених змін (розширений робочий процес) |
/opsx:onboard | Керівний огляд зміни від початку до кінця (розширений робочий процес) |
Використання
Дослідження ідеї
/opsx:exploreРозглядайте ідеї, досліджуйте проблеми, порівнюйте варіанти. Структура не потрібна — просто партнер для думок. Коли інсайти кристалізуються, переходьте до /opsx:propose (за замовчуванням) або /opsx:new//opsx:ff (розширений).
Початок нової зміни
/opsx:proposeСтворює зміну та генерує артефакти планування, необхідні перед реалізацією.
Якщо ви увімкнули розширені робочі процеси, ви можете замість цього використовувати:
/opsx:new # лише каркас
/opsx:continue # створювати по одному артефакту
/opsx:ff # створити всі артефакти планування одразуСтворення артефактів
/opsx:continueПоказує, що готово до створення на основі залежностей, потім створює один артефакт. Використовуйте повторно, щоб поступово будувати вашу зміну.
/opsx:ff add-dark-modeСтворює всі артефакти планування одразу. Використовуйте, коли у вас чітке уявлення про те, що ви будуєте.
Реалізація (гнучка частина)
/opsx:applyПроймає завдання, відмічаючи їх по ходу. Якщо ви працюєте з кількома змінами одночасно, ви можете виконати /opsx:apply <name>; інакше команда повинна визначити з контексту розмови та запитати вас обрати, якщо не може визначити.
Оновлення зміни
/opsx:update add-dark-mode - we're storing the theme in a cookie nowВносить зміни в існуючі артефакти планування зміни та зберігає їх узгодженими — у будь-якому напрямку (редагування дизайну може вплинути назад на пропозицію). Лише артефакти планування: ніколи не редагує код і ніколи не створює відсутні артефакти (це робить /opsx:continue). Кожне редагування спочатку підтверджується вами. Якщо зміна вже була реалізована, команда рекомендує /opsx:apply, щоб код догнав переглянутий план. Якщо ваша правка змінює інтенцію зміни, почніть знову — див. Коли оновлювати, а коли починати заново.
Синхронізація дельта-специфікацій
/opsx:syncОб'єднує дельта-специфікації поточної зміни в основні openspec/specs/ без архівування — зміна залишається активною. Вона застосовує весь дельта: вимога під ## REMOVED видаляється з основної специфікації, а перейменована — перейменовується на місці, тоді як контент, який дельта не згадує, залишається недоторканим. Синхронізація необов'язкова — при архівуванні вас спитають про синхронізацію, якщо ви цього ще не зробили. Користуйтеся нею, коли хочете оновити основні специфікації перед архівуванням, коли паралельна зміна потребує будувати на специфікаціях, які щойно додала ця, або коли хочете переглянути об'єднану основну специфікацію перед архівуванням.
Завершення
/opsx:archive # Перемістити в архів, коли закінчено (запитає про синхронізацію специфікацій за потреби)Коли оновлювати, а коли починати заново
Ви завжди можете редагувати свою пропозицію або специфікації перед реалізацією. Але коли вдосконалення стає «це інша робота»?
Що фіксує пропозиція
Пропозиція визначає три речі:
- Інтенція — Яку проблему ви вирішуєте?
- Діапазон — Що входить/не входить в межі?
- Підхід — Як ви будете її вирішувати?
Питання в тому: що змінилося і наскільки?
Оновлюйте існуючу зміну, коли:
Та сама інтенція, вдосконалена реалізація
- Ви виявляєте граничні випадки, які не враховували
- Підхід потребує коригування, але ціль не змінилася
- Реалізація виявляє, що дизайн був трохи неточним
Діапазон звужується
- Ви розумієте, що повний діапазон занадто великий, хочете спочатку випустити MVP
- «Додати темну тему」 → 「Додати перемикач темної теми (системні налаштування у v2)」
Правки на основі навчання
- Кодова база не структурована так, як ви думали
- Залежність не працює так, як очікувалося
- 「Використовувати CSS-змінні」 → 「Використовувати префікс dark: Tailwind замість цього」
Починайте нову зміну, коли:
Інтенція фундаментально змінилася
- Сама проблема тепер інша
- 「Додати темну тему」 → 「Додати комплексну систему тем із кастомними кольорами, шрифтами, відступами」
Діапазон вибухнув
- Зміна зросла настільки, що це фактично інша робота
- Оригінальна пропозиція буде нерозпізнаваною після оновлень
- 「Виправити баг входу」 → 「Переписати систему аутентифікації」
Оригінал можна завершити
- Оригінальну зміну можна позначити як 「завершено」
- Нова робота стоїть окремо, це не вдосконалення
- Завершити 「Додати темну тему MVP」 → Архівувати → Нова зміна 「Покращити темну тему」
Евристики
┌─────────────────────────────────────┐
│ Це та сама робота? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Та сама інтенція? >50% перетин? Чи можна
Та сама проблема? Та сам діапазон? позначити оригінал
│ │ як "завершено" без
│ │ цих змін?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
ТАК НІ ТАК НІ НІ ТАК
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
ОНОВИТИ НОВЕ ОНОВИТИ НОВЕ ОНОВИТИ НОВЕ| Критерій | Оновити | Нова зміна |
|---|---|---|
| Ідентичність | 「Та сама річ, вдосконалена」 | 「Інша робота」 |
| Перетин діапазону | >50% перетину | <50% перетину |
| Завершеність | Не можна позначити як 「завершено」 без змін | Можна завершити оригінал, нова робота стоїть окремо |
| Історія | Ланцюжок оновлень розповідає узгоджену історію | Платчі заплутують більше, ніж прояснюють |
Принцип
Оновлення зберігає контекст. Нова зміна забезпечує чіткість.
Обирайте оновлення, коли історія вашого мислення цінна. Обирайте нову зміну, коли початок з чистого аркуша буде чіткішим за латання.
Уявіть це як гілки git:
- Продовжуйте комітити, працюючи над тією ж функцією
- Починайте нову гілку, коли це дійсно нова робота
- Іноді об'єднайте часткову функцію та почніть заново для фази 2
Що змінилося?
Легасі (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| Структура | Один великий документ пропозиції | Дискретні артефакти з залежностями |
| Робочий процес | Лінійні фази: планування → реалізація → архівування | Гнучкі дії — робіть будь-що будь-коли |
| Ітерація | Незручно повертатися назад | Оновлюйте артефакти по мірі отримання знань |
| Кастомізація | Фіксована структура | На основі схем (визначайте власні артефакти) |
Ключова ідея: робота не є лінійною. OPSX перестає робити вигляд, що так.
Глибоке занурення в архітектуру
Цей розділ пояснює, як OPSX працює зсередини, та чим він відрізняється від застарілого робочого процесу. Приклади в цьому розділі використовують розширений набір команд (new, continue тощо); користувачі стандартного режиму core можуть зіставити той самий потік з propose → apply → sync → archive.
Філософія: Фази проти Дій
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW │
│ (Phase-Locked, All-or-Nothing) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ │
│ │ PHASE │ │ PHASE │ │ PHASE │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Creates ALL artifacts at once │
│ • Can't go back to update specs during implementation │
│ • Phase gates enforce linear progression │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX WORKFLOW │
│ (Fluid Actions, Iterative) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Create artifacts one at a time OR fast-forward │
│ • Update specs/design/tasks during implementation │
│ • Dependencies enable progress, phases don't exist │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Архітектура компонентів
Застарілий робочий процес використовує жорстко закодовані шаблони в TypeScript:
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Hardcoded Templates (TypeScript strings) │
│ │ │
│ ▼ │
│ Tool-specific configurators/adapters │
│ │ │
│ ▼ │
│ Generated Command Files (.claude/commands/openspec/*.md) │
│ │
│ • Fixed structure, no artifact awareness │
│ • Change requires code modification + rebuild │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX використовує зовнішні схеми та рушій графу залежностей:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Schema Definitions (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Artifact Graph Engine │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Topological sort (dependency ordering) │ │
│ │ • State detection (filesystem existence) │ │
│ │ • Rich instruction generation (templates + context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Cross-editor compatible (Claude Code, Cursor, Devin) │
│ • Skills query CLI for structured data │
│ • Fully customizable via schema files │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Модель графу залежностей
Артефакти утворюють орієнтований ациклічний граф (DAG). Залежності є сприятливими факторами, а не бар’єрами:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY PHASE │
│ (requires: │
│ tasks) │
└──────────────┘Переходи станів:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Missing All deps File exists
dependencies are DONE on filesystemПотік інформації
Застарілий робочий процес — агент отримує статичні інструкції:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Static instructions: │
│ • Create proposal.md │
│ • Create tasks.md │
│ • Create design.md │
│ • Create delta spec files │
│ │
│ No awareness of what exists or │
│ dependencies between artifacts │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one goOPSX — агент запитує насичений контекст:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1: Query current state │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── First ready │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", │ │
│ │ "missingDeps": ["specs", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Get rich instructions for ready artifact │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Read dependencies → Create ONE artifact → Show what's unlocked │
└──────────────────────────────────────────────────────────────────────────┘Модель ітерації
Застарілий робочий процес — ітерації незручні:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "Wait, the design is wrong"
│ │
│ ├── Options:
│ │ • Edit files manually (breaks context)
│ │ • Abandon and start over
│ │ • Push through and fix later
│ │
│ └── No official "go back" mechanism
│
└── Creates ALL artifacts at onceOPSX — природна ітерація:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "The design is wrong"
│ │ │
│ │ ▼
│ │ Just edit design.md
│ │ and continue!
│ │ │
│ │ ▼
│ │ /opsx:apply picks up
│ │ where you left off
│ │
│ └── Creates ONE artifact, shows what's unlocked
│
└── Scaffolds change, waits for directionКористувацькі схеми
Створюйте власні робочі процеси за допомогою команд керування схемами:
# Створити нову схему з нуля (інтерактивно)
openspec schema init my-workflow
# Або відгалузити існуючу схему як вихідну точку
openspec schema fork spec-driven my-workflow
# Перевірити структуру вашої схеми
openspec schema validate my-workflow
# Побачити, звідки береться схема (корисно для налагодження)
openspec schema which my-workflowСхеми зберігаються в openspec/schemas/ (локально для проєкту, під контролем версій) або ~/.local/share/openspec/schemas/ (глобально для користувача).
Структура схеми:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.mdПриклад schema.yaml:
name: research-first
artifacts:
- id: research # Додається перед пропозицією
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Тепер залежить від research
- id: tasks
generates: tasks.md
requires: [proposal]Граф залежностей:
research ──► proposal ──► tasksПідсумок
| Аспект | Застарілий | OPSX |
|---|---|---|
| Шаблони | Жорстко закодовані TypeScript | Зовнішні YAML + Markdown |
| Залежності | Немає (всі одразу) | DAG з топологічним сортуванням |
| Стан | Ментальна модель на основі фаз | Наявність у файловій системі |
| Налаштування | Редагувати вихідний код, перезбирати | Створити schema.yaml |
| Ітерація | Заблоковано фазами | Гнучко, редагуйте що завгодно |
| Підтримка редакторів | Специфічні для інструменту конфігуратори/адаптери | Єдиний каталог навичок |
Схеми
Схеми визначають, які артефакти існують і їхні залежності. Наразі доступні:
- spec-driven (типово): proposal → specs → design → tasks
# Список доступних схем
openspec schemas
# Переглянути всі схеми з їхніми джерелами визначення
openspec schema which --all
# Створити нову схему інтерактивно
openspec schema init my-workflow
# Створити гілку наявної схеми для кастомізації
openspec schema fork spec-driven my-workflow
# Валідувати структуру схеми перед використанням
openspec schema validate my-workflowПоради
- Використовуйте
/opsx:explore, щоб обміркувати ідею, перш ніж вносити зміни /opsx:ff, коли ви точно знаєте, що потрібно,/opsx:continue, коли досліджуєте- Під час
/opsx:apply, якщо щось не так — виправте артефакт, а потім продовжуйте - Завдання відстежують прогрес за допомогою галочок у
tasks.md - Перевіряйте статус у будь-який момент:
openspec status --change "name"
Зворотний зв'язок
Це досить сире рішення. Це свідомо — ми вчимося, що працює.
Знашли баг? Маєте ідеї? Приєднуйтесь до нас у Discord або відкрийте issue на GitHub.