Концепції

Цей посібник пояснює основні ідеї 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 є постійним домом для планування.

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

text

workspace = де живуть пов'язані міжрепозиторні зміни
link      = стабільне ім'я для репозиторію або папки, з яким робочий простір може планувати
change    = одна функція, виправлення, проєкт або інша запланована частина роботи

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

text

workspace-folder/
├── changes/                       # Планування на рівні робочого простору
└── .openspec-workspace/
    ├── workspace.yaml             # Спільна ідентичність робочого простору та імена посилань
    └── local.yaml                 # Локальні шляхи цієї машини

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

text

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

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

Стабільні імена посилань — це спосіб, яким планування робочого простору посилається на репозиторії та папки. Спільний стан робочого простору зберігає імена на кшталт api, web або checkout; кожна машина зіставляє ці імена зі своїми локальними шляхами у .openspec-workspace/local.yaml.

yaml

# .openspec-workspace/workspace.yaml
version: 1
name: platform
links:
  api: {}
  web: {}

yaml

# .openspec-workspace/local.yaml
version: 1
paths:
  api: /repos/api
  web: /repos/web

Робочі простори, створені OpenSpec, за замовчуванням виключають .openspec-workspace/local.yaml з переносного стану співпраці. .openspec-workspace/workspace.yaml залишається переносним, оскільки зберігає ім'я робочого простору та стабільні імена посилань, а не абсолютні шляхи клонування одного користувача.

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

text

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

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

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

text

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 також зберігає локальний для машини реєстр за адресою:

text

getGlobalDataDir()/workspaces/registry.yaml

Реєстр зіставляє імена робочих просторів з їхніми розташуваннями, щоб подальші глобальні команди могли перераховувати або вибирати відомі робочі простори з будь-якого місця. Це лише індекс. Кожна папка робочого простору залишається авторитетною для власних .openspec-workspace/workspace.yaml та .openspec-workspace/local.yaml, тому застарілі записи реєстру можуть бути повідомлені та виправлені без переозначення самого робочого простору.

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

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

bash

# Інтерактивне налаштування
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

# Перегляд відомих робочих просторів з локального реєстру
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 open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

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

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

Керований робочий простір VS Code включає корінь координації як . плюс дійсні пов'язані репозиторії або папки як додаткові корені. 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: [].

Специфікації

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

Структура

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

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

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

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

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

markdown

# Auth Specification

Призначення

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

Вимоги

Вимога: Автентифікація користувача

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

Сценарій: Дійсні облікові дані

ЗАДАНО користувача з дійсними обліковими даними
КОЛИ користувач надсилає форму входу
ТОДІ повертається JWT-токен
І користувача перенаправляється на панель керування

Сценарій: Недійсні облікові дані

ЗАДАНО недійсні облікові дані
КОЛИ користувач надсилає форму входу
ТОДІ відображається повідомлення про помилку
І токен не видається

Вимога: Закінчення терміну дії сеансу

Система ПОВИННА завершувати сеанси після 30 хвилин бездіяльності.

Сценарій: Тайм-аут через бездіяльність

ЗАДАНО автентифікований сеанс
КОЛИ минає 30 хвилин без активності
ТОДІ сеанс стає недійсним
І користувач повинен пройти автентифікацію повторно


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

| Елемент | Призначення |
|---------|-------------|
| `## Purpose` | Опис домену цієї специфікації на високому рівні |
| `### Requirement:` | Конкретна поведінка, яку система повинна мати |
| `#### Scenario:` | Конкретний приклад вимоги в дії |
| SHALL/MUST/SHOULD | Ключові слова RFC 2119, що вказують на силу вимоги |

### Навіть структурувати специфікації таким чином

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

**Сценарії — це "коли"** — вони надають конкретні приклади, які можна перевірити. Добрі сценарії:
- Піддаються тестуванню (для них можна написати автоматизований тест)
- Охоплюють як основний шлях, так і граничні випадки
- Використовують структурований формат Given/When/Then або подібний

**Ключові слова RFC 2119** (SHALL, MUST, SHOULD, MAY) передають намір:
- **MUST/SHALL** — абсолютна вимога
- **SHOULD** — рекомендація, але є винятки
- **MAY** — необов'язково

### Що таке специфікація (і чим вона не є)

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

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

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

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

### Зберігайте легкість: Поступова суворість

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

**Легка специфікація (за замовчуванням):**
- Короткі вимоги, орієнтовані на поведінку
- Чіткий обсяг і не-цілі
- Кілька конкретних перевірок прийняття

**Повна специфікація (для вищого ризику):**
- Зміни, що стосуються кількох команд або репозиторіїв
- Зміни API/контрактів, міграції, питання безпеки/конфіденційності
- Зміни, де двозначність, ймовірно, призведе до дорогого перероблення

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

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

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

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

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

## Зміни

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

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

openspec/changes/add-dark-mode/ ├── proposal.md # Чому і що ├── design.md # Як (технічний підхід) ├── tasks.md # Чекліст реалізації ├── .openspec.yaml # Метадані зміни (опціонально) └── specs/ # Дельта-специфікації └── ui/ └── spec.md # Що змінюється в ui/spec.md


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

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

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

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

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

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

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

## Артефакти

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

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

proposal ──────► specs ──────► design ──────► tasks ──────► implement │ │ │ │ why what how steps

scope changes approach to take


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

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

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

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

```markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.

## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage

Out of scope:
- Custom color themes (future work)
- Per-page theme overrides

## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.

Коли оновлювати пропозицію:

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

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

Дельта-специфікації описують що змінюється відносно поточних специфікацій. Див. Дельта-специфікації нижче.

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

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

markdown

# Design: Add Dark Mode

## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.

## Architecture Decisions

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution

## Data Flow
```
ThemeProvider (context)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS Variables (applied to :root)
```

## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)

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

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

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

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

markdown

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibility

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

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

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

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

Формат

markdown

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation

#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)

Секції дельт

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

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

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

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

Ефективність рев'ю. Рецензенти бачать зміну, а не незмінений контекст. Фокус на тому, що має значення.

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

Схеми

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

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

yaml

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

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

  - id: design
    generates: design.md
    requires: [proposal]      # Можна створити паралельно з specs

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # Потрібні обидва: specs та design

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

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

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

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

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

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

proposal → specs → design → tasks → implement

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

Власні схеми

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

bash

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

# Або форкнути існуючу
openspec schema fork spec-driven research-first

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

yaml

# 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]   # Пропускаємо specs/design, переходимо одразу до tasks

Дивіться Налаштування для отримання повної інформації про створення та використання власних схем.

Архівування

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

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

До архівування:

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

Процес архівування

Об'єднання дельт. Кожна секція дельта-специфікації (ADDED/MODIFIED/REMOVED) застосовується до відповідної основної специфікації.
Переміщення до архіву. Папка зміни переміщується до changes/archive/ з датою-префіксом для хронологічного впорядкування.
Збереження контексту. Усі артефакти залишаються незмінними в архіві. Ви завжди можете переглянути, щоб зрозуміти, чому була внесена зміна.

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

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

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

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

Як все працює разом

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

Порядний цикл:

Специфікації описують поточну поведінку
Зміни пропонують модифікації (у вигляді дельт)
Реалізація втілює зміни в життя
Архівування об'єднує дельти у специфікації
Специфікації тепер описують нову поведінку
Наступна зміна ґрунтується на оновлених специфікаціях

Глосарій

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

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

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

Концепції ​

Філософія ​

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

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

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

Специфікації ​

Структура ​

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

Призначення ​

Вимоги ​

Вимога: Автентифікація користувача ​

Сценарій: Дійсні облікові дані ​

Сценарій: Недійсні облікові дані ​

Вимога: Закінчення терміну дії сеансу ​

Сценарій: Тайм-аут через бездіяльність ​

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

Дизайн (design.md) ​

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

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

Формат ​

Секції дельт ​

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

Схеми ​

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

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

Власні схеми ​

Архівування ​

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

Процес архівування ​

Чому архівування важливе ​

Як все працює разом ​

Глосарій ​

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

Концепції

Філософія

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

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

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

Специфікації

Структура

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

Призначення

Вимоги

Вимога: Автентифікація користувача

Сценарій: Дійсні облікові дані

Сценарій: Недійсні облікові дані

Вимога: Закінчення терміну дії сеансу

Сценарій: Тайм-аут через бездіяльність

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

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

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

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

Формат

Секції дельт

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

Схеми

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

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

Власні схеми

Архівування

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

Процес архівування

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

Як все працює разом

Глосарій

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