Концепції

Цей посібник пояснює основні ідеї, що лежать в основі OpenSpec, та як вони пов'язані між собою. Для практичного використання дивіться Початок роботи та Робочі процеси.

Філософія

OpenSpec побудовано на чотирьох принципах:

fluid not rigid         — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex        — lightweight setup, minimal ceremony
brownfield-first        — works with existing codebases, not just greenfield

Чому ці принципи важливі

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

Ітеративність, а не каскадна модель. Вимоги змінюються. Розуміння поглиблюється. Те, що здавалося гарним підходом на початку, може не витримати перевірки після вивчення кодової бази. OpenSpec приймає цю реальність.

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

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

Загальна картина

OpenSpec організовує вашу роботу в двох основних сферах:

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  Source of truth    │◄─────│  Proposed modifications       │   │
│   │  How your system    │ merge│  Each change = one folder     │   │
│   │  currently works    │      │  Contains artifacts + deltas  │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Специфікації (Specs) є єдиним джерелом правди — вони описують, як ваша система працює зараз.

Зміни (Changes) є пропонованими модифікаціями — вони знаходяться в окремих папках, доки ви не будете готові їх об'єднати.

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

Робочі простори координації

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

Наведені нижче команди забезпечують перший потік налаштування для відкриття локальних переглядів пов'язаних репозиторіїв або папок.

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

Ментальна модель робочого простору:

workspace     = приватний локальний перегляд над сховищами контексту, ініціативами, репозиторіями та папками
context store = довговічний спільний контейнер контексту
initiative    = довговічний контекст координації всередині сховища контексту
link          = стабільне ім'я для репозиторію або папки, яке робочий простір може вирішити локально
change        = один запланований фрагмент роботи; реалізація належить репозиторію-власнику

Робочий простір має іншу форму, ніж проект, локальний для репозиторію:

getGlobalDataDir()/workspaces/<workspace-name>/
├── workspace.yaml                 # Запис приватного локального перегляду
├── AGENTS.md                      # Згенероване керівництво часу виконання
└── <workspace-name>.code-workspace # Згенерований файл робочого простору редактора

Стан OpenSpec, локальний для репозиторію, зберігає існуючу форму:

repo-root/
└── openspec/
    ├── specs/
    └── changes/

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

Стабільні імена посилань — це спосіб, яким робочий простір посилається на репозиторії та папки. Приватний запис робочого простору зберігає такі імена, як api, web або checkout, і відображає їх на локальні шляхи часу виконання.

# workspace.yaml
version: 1
name: platform
context: null
links:
  api: /repos/api
  web: /repos/web

Коли робочий простір відкриває ініціативу, context записує вибране прив'язування до сховища контексту та ідентифікатор ініціативи. Сховища, вибрані реєстром, залишаються портативними за ідентифікатором; сховища, вибрані за шляхом, навмисно зберігають шлях, локальний для часу виконання, оскільки workspace.yaml є приватним локальним станом.

context:
  kind: initiative
  store:
    id: platform
    selector:
      kind: registry
      id: platform
  initiative:
    id: billing-launch

Пов'язані шляхи можуть бути повними репозиторіями, папками всередині великого монорепозиторію або іншими існуючими папками. Їм не потрібен локальний для репозиторію стан openspec/, перш ніж вони зможуть брати участь у плануванні робочого простору. Подальша реалізація, перевірка або архівні робочі процеси можуть вимагати більшої готовності репозиторію, але видимість планування починається з посилання.

multi-repo:
  api      -> /repos/api
  web      -> /repos/web

large monorepo:
  billing  -> /repos/platform/services/billing
  checkout -> /repos/platform/apps/checkout

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

getGlobalDataDir()/workspaces

Це означає $XDG_DATA_HOME/openspec/workspaces, коли XDG_DATA_HOME встановлено, ~/.local/share/openspec/workspaces на Unix-подібних системах за замовчуванням та %LOCALAPPDATA%\openspec\workspaces на рідних Windows системах за замовчуванням. Рідні оболонки Windows, PowerShell та WSL2 кожна зберігають рядки шляхів для часу виконання, що запускає OpenSpec. Ця основа не перекладає між D:\repo, /mnt/d/repo та UNC WSL шляхами.

OpenSpec все ще може читати старіші кореневі каталоги бета-версій робочих просторів як вхідні дані для сумісності, але керовані робочі простори тепер використовують кореневий запис workspace.yaml, наведений вище. Папка робочого простору залишається авторитетною для свого власного приватного локального перегляду.

Видимість робочого простору не є обов'язком щодо зміни. Налаштуйте робочий простір, коли OpenSpec повинен знати, які репозиторії або папки є релевантними; створіть зміну пізніше, коли ви будете готові планувати функцію, виправлення, проект або інший фрагмент роботи.

Корисні команди:

# Кероване налаштування
openspec workspace setup

# Автоматизаційно-дружнє налаштування
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex-cli

# Переглянути відомі робочі простори з локального реєстру
openspec workspace list
openspec workspace ls

# Додати або відремонтувати посилання для вибраного робочого простору
openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace relink api-service /new/path/to/api

# Перевірити, що ця машина може вирішити
openspec workspace doctor
openspec workspace doctor --workspace platform

# Оновити керівництво робочого простору та навички агента
openspec workspace update
openspec workspace update --workspace platform --tools codex,claude

# Відкрити пов'язаний набір робіт
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

# Відкрити ініціативу як перегляд локального робочого простору
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative billing-launch --store-path /repos/platform-context

workspace setup завжди створює робочий простір у стандартному місці робочого простору, записує його в локальний реєстр, показує розташування робочого простору та вимагає принаймні одного пов'язаного репозиторію або папки. Інтерактивне налаштування запитує бажаний відкривач і може встановити навички OpenSpec для вибраних агентів. Неінтерактивне налаштування зберігає лише тоді, коли надано --opener codex-cli, --opener claude, --opener github-copilot або --opener editor.

Навички робочого простору встановлюються лише в кореневому каталозі робочого простору. Активний глобальний профіль визначає, які навички робочого процесу генеруються; --tools вибирає, які агенти їх отримують. Налаштування та оновлення робочого простору не створюють файли команд з косою рискою, навіть коли глобальна доставка включає команди. Запустіть openspec workspace update, щоб оновити керівництво робочого простору та додати, оновити або видалити керовані каталоги навичок робочого простору без редагування пов'язаних репозиторіїв або папок.

OpenSpec також підтримує кореневі файли відкриття робочого простору: керований блок керівництва OpenSpec у AGENTS.md та локальний для машини файл <workspace-name>.code-workspace для відкриттів VS Code та GitHub Copilot-in-VS-Code. Керований робочий простір не є репозиторієм, тому OpenSpec не створює стандартний .gitignore робочого простору або стандартний каталог робочого простору рівня changes/.

Підтримуваний робочий простір VS Code спочатку перелічує дійсні пов'язані репозиторії або папки, потім контекст ініціативи, якщо він прикріплений, потім файли робочого простору OpenSpec. VS Code відображає ці записи як багатокореневий робочий простір.

workspace open відкриває пов'язаний набір робіт зі збереженим бажаним відкривачем, якщо не передано --agent <tool> або --editor для того одного сеансу. Передача обох замін відкривача є помилкою. Відкриття кореневого робочого простору робить пов'язані репозиторії та папки видимими для дослідження та контексту; реалізація починається після того, як користувач явно попросить про роботу з реалізацією.

workspace link та workspace relink записують лише існуючі папки; вони не створюють, копіюють, переміщують, ініціалізують або редагують пов'язаний репозиторій або папку. Після успішного з'єднання або перепідключення OpenSpec оновлює кероване керівництво та файл робочого простору VS Code.

Команди робочого простору, яким потрібен один робочий простір, можуть запускатися з будь-якого місця за допомогою --workspace <name>. Якщо ви запускаєте їх усередині папки робочого простору або підкаталогу, OpenSpec використовує поточний робочий простір. Якщо доступні кілька відомих робочих просторів, і ви не передаєте --workspace <name>, людські команди показують засіб вибору; --json та --no-interactive завершуються помилкою зі структурованим статусом замість запиту.

Прямі команди робочого простору підтримують вивід JSON для скриптів. Відповіді JSON зберігають основні дані в об'єктах workspace, workspaces або link та повідомляють про попередження або помилки в масивах status. Здорові об'єкти використовують status: [].

Специфікації (Specs)

Специфікації описують поведінку вашої системи за допомогою структурованих вимог та сценаріїв.

Структура

openspec/specs/
├── auth/
│   └── spec.md           # Поведінка автентифікації
├── payments/
│   └── spec.md           # Обробка платежів
├── notifications/
│   └── spec.md           # Система сповіщень
└── ui/
    └── spec.md           # Поведінка UI та теми

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

• За областю функціональності: auth/, payments/, search/
• За компонентом: api/, frontend/, workers/
• За обмеженим контекстом: ordering/, fulfillment/, inventory/

Формат специфікації

Специфікація містить вимоги, і кожна вимога має сценарії:

# Специфікація автентифікації

## Призначення
Автентифікація та керування сеансами для програми.

## Вимоги

### Вимога: Автентифікація користувача
Система ПОВИННА видавати JWT-токен після успішного входу.

#### Сценарій: Дійсні облікові дані
- GIVEN користувач з дійсними обліковими даними
- WHEN користувач надсилає форму входу
- THEN повертається JWT-токен
- AND користувача перенаправляється на панель керування

#### Сценарій: Недійсні облікові дані
- GIVEN недійсні облікові дані
- WHEN користувач надсилає форму входу
- THEN відображається повідомлення про помилку
- AND токен не видається

### Вимога: Закінчення терміну дії сеансу
Система МАЄ закінчувати термін дії сеансів після 30 хвилин бездіяльності.

#### Сценарій: Час очікування простою
- GIVEN автентифікований сеанс
- WHEN минає 30 хвилин без активності
- THEN сеанс стає недійсним
- AND користувач повинен пройти повторну автентифікацію

Ключові елементи:

Елемент	Призначення
## Призначення	Опис домену цієї специфікації на високому рівні
### Вимога:	Конкретна поведінка, яку повинна мати система
#### Сценарій:	Конкретний приклад вимоги в дії
ПОВИННА/МАЄ/СЛІД	Ключові слова RFC 2119, що вказують на силу вимоги

Чому структурувати специфікації саме так

Вимоги — це "що" — вони вказують, що система повинна робити, без визначення реалізації.

Сценарії — це "коли" — вони надають конкретні приклади, які можна перевірити. Хороші сценарії:

• Підлягають тестуванню (для них можна написати автоматизований тест)
• Охоплюють як щасливий шлях, так і граничні випадки
• Використовують Given/When/Then або подібний структурований формат

Ключові слова RFC 2119 (ПОВИННА, МАЄ, СЛІД, МОЖЕ) передають намір:

• МАЄ/ПОВИННА — абсолютна вимога
• СЛІД — рекомендовано, але є винятки
• МОЖЕ — необов'язково

Що є специфікацією (і що не є)

Специфікація — це контракт поведінки, а не план реалізації.

Хороший вміст специфікації:

• Спостережувана поведінка, на яку покладаються користувачі або суміжні системи
• Вхідні дані, вихідні дані та умови помилок
• Зовнішні обмеження (безпека, конфіденційність, надійність, сумісність)
• Сценарії, які можна протестувати або явно підтвердити

Уникати в специфікаціях:

• Внутрішніх імен класів/функцій
• Вибору бібліотек або фреймворків
• Покрокових деталей реалізації
• Детальних планів виконання (вони належать до design.md або tasks.md)

Швидкий тест:

• Якщо реалізація може змінюватися без зміни зовнішньо видимої поведінки, вона, ймовірно, не належить до специфікації.

Зберігайте легкість: Прогресивна строгість

OpenSpec прагне уникнути бюрократії. Використовуйте найлегший рівень, який все ще робить зміну перевіреною.

Легка специфікація (за замовчуванням):

• Короткі вимоги, що ставлять поведінку на перше місце
• Чітка область та не-цілі
• Кілька конкретних перевірок прийняття

Повна специфікація (для вищого ризику):

• Міжкомандні або міжрепозиторні зміни
• Зміни API/контрактів, міграції, питання безпеки/конфіденційності
• Зміни, де двозначність, ймовірно, призведе до дорогого перероблення

Більшість змін повинні залишатися в легкому режимі.

Співпраця Людина + Агент

У багатьох командах люди досліджують, а агенти створюють артефакти. Передбачений цикл:

1. Людина надає намір, контекст та обмеження.
2. Агент перетворює це на вимоги та сценарії, що ставлять поведінку на перше місце.
3. Агент зберігає деталі реалізації в design.md та tasks.md, а не в spec.md.
4. Валідація підтверджує структуру та чіткість до реалізації.

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

Зміни

Зміна — це запропонована модифікація вашої системи, упакована у вигляді папки з усім необхідним для її розуміння та реалізації.

Структура зміни

openspec/changes/add-dark-mode/
├── proposal.md           # Why and what
├── design.md             # How (technical approach)
├── tasks.md              # Implementation checklist
├── .openspec.yaml        # Change metadata (optional)
└── specs/                # Delta specs
    └── ui/
        └── spec.md       # What's changing in ui/spec.md

Кожна зміна є самодостатньою. Вона містить:

• Артефакти — документи, що фіксують намір, дизайн та завдання
• Дельта-специфікації — специфікації того, що додається, змінюється або видаляється
• Метадані — необов'язкова конфігурація для конкретної зміни

Чому зміни — це папки

Упаковка зміни у вигляді папки має кілька переваг:

1. Все в одному місці. Пропозиція, дизайн, завдання та специфікації зберігаються в одному місці. Не потрібно шукати по різних локаціях.

2. Паралельна робота. Кілька змін можуть існувати одночасно без конфліктів. Можна працювати над add-dark-mode, поки fix-auth-bug також у процесі.

3. Чиста історія. Після архівації зміни переміщуються до changes/archive/ зі збереженням повного контексту. Можна озирнутися назад і зрозуміти не лише що змінилося, а й чому.

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

Артефакти

Артефакти — це документи в межах зміни, які спрямовують роботу.

Потік артефактів

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
  чому            що            як          кроки
+ обсяг         змінюється    підхід       до виконання

Артефакти ґрунтуються один на одному. Кожен артефакт надає контекст для наступного.

Типи артефактів

Пропозиція (proposal.md)

Пропозиція фіксує намір, обсяг та підхід на високому рівні.

# Proposal: Add Dark Mode

Призначення

Користувачі запитали опцію темного режиму для зменшення навантаження на очі під час вечірнього використання та відповідності системних налаштувань.

Обсяг

В обсязі:

• Перемикач теми в налаштуваннях
• Виявлення системних налаштувань
• Збереження вподобання в localStorage

Поза обсягом:

• Спеціальні кольорові теми (майбутня робота)
• Перевизначення теми для окремих сторінок

Підхід

Використання власних властивостей CSS для тематизації з React context для керування станом. Виявлення системних налаштувань під час першого завантаження, дозвіл ручного перевизначення.

**Коли оновлювати пропозицію:**
- Зміни обсягу (звуження або розширення)
- Уточнення призначення (краще розуміння проблеми)
- Фундаментальна зміна підходу

#### Специфікації (дельта-специфікації в `specs/`)

Дельта-специфікації описують **що змінюється** відносно поточних специфікацій. Див. [Дельта-специфікації](#delta-specs) нижче.

#### Дизайн (`design.md`)

Дизайн фіксує **технічний підхід** та **архітектурні рішення**.

````markdown
# Дизайн: Додати темний режим

## Технічний підхід
Стан теми керується через React Context, щоб уникнути "prop drilling".
Власні властивості CSS дозволяють перемикання під час виконання без перемикання класів.

## Архітектурні рішення

### Рішення: Context замість Redux
Використання React Context для стану теми, тому що:
- Простий бінарний стан (світла/темна)
- Немає складних змін стану
- Уникаємо додавання залежності від Redux

### Рішення: Власні властивості CSS
Використання змінних CSS замість CSS-in-JS, тому що:
- Працює з існуючими таблицями стилів
- Немає накладних витрат під час виконання
- Нативне рішення браузера

## Потік даних

ThemeProvider (контекст) │ ▼ ThemeToggle ◄──► localStorage │ ▼ Змінні CSS (застосовуються до :root)

## Зміни у файлах
- `src/contexts/ThemeContext.tsx` (новий)
- `src/components/ThemeToggle.tsx` (новий)
- `src/styles/globals.css` (змінений)

Коли оновлювати дизайн:

• Реалізація показує, що підхід не працює
• Знайдено краще рішення
• Змінюються залежності або обмеження

Завдання (tasks.md)

Завдання — це контрольний список реалізації — конкретні кроки з прапорцями.

# Завдання

## 1. Інфраструктура теми
- [ ] 1.1 Створити ThemeContext зі станом світла/темної
- [ ] 1.2 Додати власні властивості CSS для кольорів
- [ ] 1.3 Реалізувати збереження в localStorage
- [ ] 1.4 Додати виявлення системних налаштувань

## 2. Компоненти інтерфейсу
- [ ] 2.1 Створити компонент ThemeToggle
- [ ] 2.2 Додати перемикач на сторінку налаштувань
- [ ] 2.3 Оновити Header для включення швидкого перемикача

## 3. Стилізація
- [ ] 3.1 Визначити палітру кольорів темної теми
- [ ] 3.2 Оновити компоненти для використання змінних CSS
- [ ] 3.3 Протестувати коефіцієнти контрастності для доступності

Найкращі практики для завдань:

• Групуйте пов'язані завдання під заголовками
• Використовуйте ієрархічну нумерацію (1.1, 1.2 тощо)
• Робіть завдання достатньо малими, щоб завершити за один сеанс
• Відмічайте завдання прапорцями після їх виконання

Дельта-специфікації

Дельта-специфікації — це ключова концепція, що робить OpenSpec придатним для роботи з існуючим кодом (brownfield). Вони описують що змінюється, а не повторюють усю специфікацію повністю.

Формат

# Дельта для Auth

## ДОДАНІ Вимоги

### Вимога: Двофакторна автентифікація
Система ПОВИННА підтримувати двофакторну автентифікацію на основі TOTP.

#### Сценарій: Реєстрація 2FA
- GIVEN користувач без увімкненої 2FA
- WHEN користувач увімкнює 2FA в налаштуваннях
- THEN відображається QR-код для налаштування додатку-автентифікатора
- AND користувач повинен підтвердити кодом перед активацією

#### Сценарій: Вхід з 2FA
- GIVEN користувач з увімкненою 2FA
- WHEN користувач надсилає дійсні облікові дані
- THEN пропонується запит OTP
- AND вхід завершується лише після дійсного OTP

## ЗМІНЕНІ Вимоги

### Вимога: Закінчення сеансу
Система ПОВИННА завершувати сеанси після 15 хвилин бездіяльності.
(Попередньо: 30 хвилин)

#### Сценарій: Тайм-аут бездіяльності
- GIVEN автентифікований сеанс
- WHEN минає 15 хвилин без активності
- THEN сеанс анулюється

## ВИДАЛЕНІ Вимоги

### Вимога: "Запам'ятати мене"
(Застаріла на користь 2FA. Користувачі повинні повторно автентифікуватися кожного сеансу.)

Розділи дельти

Розділ	Значення	Що відбувається під час архівації
## ADDED Requirements	Нова поведінка	Додається до основної специфікації
## MODIFIED Requirements	Змінена поведінка	Замінює існуючу вимогу
## REMOVED Requirements	Застаріла поведінка	Видаляється з основної специфікації

Чому дельти замість повних специфікацій

Ясність. Дельта показує точно, що змінюється. Читаючи повну специфікацію, вам довелося б порівнювати її ментально з поточною версією.

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

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

Підходить для brownfield. Більша частина роботи змінює існуючу поведінку. Дельти роблять модифікації першокласними, а не вторинними.

Схеми

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

Як працюють схеми

# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # Немає залежностей, можна створити першим

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # Потрібна пропозиція перед створенням

  - id: design
    generates: design.md
    requires: [proposal]      # Можна створити паралельно зі специфікаціями

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # Потрібні і специфікації, і дизайн

Артефакти утворюють граф залежностей:

                    proposal
                   (кореневий вузол)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (requires:                  (requires:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (requires:
                specs, design)

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

Вбудовані схеми

spec-driven (за замовчуванням)

Стандартний робочий процес для розробки на основі специфікацій:

proposal → specs → design → tasks → implement

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

Власні схеми

Створюйте власні схеми для робочого процесу вашої команди:

# Створити з нуля
openspec schema init research-first

# Або розгалузити існуючу
openspec schema fork spec-driven research-first

Приклад власної схеми:

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # Спочатку дослідження

  - id: proposal
    generates: proposal.md
    requires: [research]   # Пропозиція на основі дослідження

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # Пропускаємо специфікації/дизайн, переходимо одразу до завдань

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

Архівація

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

Що відбувається під час архівації

Перед архівацією:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ об'єднання
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


Після архівації:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # Тепер включає вимоги 2FA
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # Збережено для історії
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

Процес архівації

1. Об'єднання дельт. Кожен розділ дельта-специфікації (ДОДАНІ/ЗМІНЕНІ/ВИДАЛЕНІ) застосовується до відповідної основної специфікації.

2. Переміщення до архіву. Папка зміни переміщується до changes/archive/ з датою-префіксом для хронологічного порядку.

3. Збереження контексту. Всі артефакти залишаються незмінними в архіві. Ви завжди можете переглянути, щоб зрозуміти, чому було внесено зміну.

Чому архівація важлива

Чистий стан. Активні зміни (changes/) показують лише роботу в процесі. Завершена робота переміщується з шляху.

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

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

Як це все пов'язано

┌──────────────────────────────────────────────────────────────────────────────┐
│                              ПОТІК OPENSPEC                                  │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. ПОЧАТОК    │  /opsx:propose (ядро) або /opsx:new (розширений)        │
│   │     ЗМІНИ      │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. СТВОРЕННЯ  │  /opsx:ff або /opsx:continue (розширений робочий процес)│
│   │     АРТЕФАКТІВ │  Створює пропозицію → специфікації → дизайн → завдання  │
│   │                │  (на основі залежностей схеми)                           │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. РЕАЛІЗАЦІЯ │  /opsx:apply                                            │
│   │     ЗАВДАНЬ     │  Опрацьовувати завдання, відмічаючи їх прапорцями       │
│   │                │◄──── Оновлюйте артефакти по мірі отримання знань        │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. ПЕРЕВІРКА  │  /opsx:verify (необов'язково)                           │
│   │     РОБОТИ     │  Перевірити, чи відповідає реалізація специфікаціям     │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. АРХІВАЦІЯ  │────►│  Дельта-специфікації об'єднуються в основні │    │
│   │     ЗМІНИ      │     │  Папка зміни переміщується до archive/       │    │
│   └────────────────┘     │  Специфікації тепер є оновленим джерелом     │    │
│                          │  істини                                       │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Позитивний цикл:

1. Специфікації описують поточну поведінку
2. Зміни пропонують модифікації (як дельти)
3. Реалізація робить зміни реальними
4. Архівація об'єднує дельти в специфікації
5. Специфікації тепер описують нову поведінку
6. Наступна зміна будується на оновлених специфікаціях

Глосарій

Термін	Визначення
Артефакт	Документ у межах зміни (пропозиція, дизайн, завдання або дельта-специфікації)
Архівування	Процес завершення зміни та злиття її дельт в основні специфікації
Зміна	Запропонована модифікація системи, оформлена як папка з артефактами
Дельта-специфікація	Специфікація, що описує зміни (ДОДАНО/ЗМІНЕНО/ВИДАЛЕНО) відносно поточних специфікацій
Домен	Логічне угруповання для специфікацій (наприклад, auth/, payments/)
Вимога	Конкретна поведінка, яку повинна мати система
Сценарій	Конкретний приклад вимоги, зазвичай у форматі Given/When/Then
Схема	Визначення типів артефактів та їхніх залежностей
Специфікація	Документ, що описує поведінку системи, містить вимоги та сценарії
Єдине джерело істини	Каталог openspec/specs/, що містить поточну узгоджену поведінку

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

• Початок роботи — Практичні перші кроки
• Робочі процеси — Поширені патерни та коли кожен використовувати
• Команди — Повний довідник команд
• Кастомізація — Створення власних схем та налаштування проєкту