Концепції
Цей посібник пояснює основні ідеї OpenSpec та як вони поєднуються між собою. Щодо практичного використання, див. Початок роботи та Робочі процеси.
Філософія
OpenSpec побудований навколо чотирьох принципів:
гнучкий, а не жорсткий — без фазових перевірок, працюйте над тим, що має сенс
ітеративний, а не каскадний — навчайтесь під час розробки, вдосконалюйте по ходу
простий, а не складний — легке налаштування, мінімум формальностей
для наявних кодових баз — працює з існуючим кодом, а не лише з новими проєктамиЧому ці принципи важливі
Гнучкий, а не жорсткий. Традиційні системи специфікацій прив'язують вас до фаз: спочатку ви плануєте, потім реалізуєте, і все. OpenSpec більш гнучкий — ви можете створювати артефакти в будь-якому порядку, який має сенс для вашої роботи.
Ітеративний, а не каскадний. Вимоги змінюються. Розуміння поглиблюється. Те, що здавалося добрим підходом на початку, може не витримати після того, як ви побачите кодову базу. OpenSpec приймає цю реальність.
Простий, а не складний. Деякі фреймворки для специфікацій вимагають значних налаштувань, жорстких форматів або важких процесів. OpenSpec не заважає вам. Ініціалізація за секунди, починайте працювати негайно, налаштовуйте лише за потреби.
Для наявних кодових баз. Більша частина роботи з програмним забезпеченням — це не створення з нуля, а модифікація існуючих систем. Підхід OpenSpec, заснований на дельтах, спрощує специфікацію змін до існуючої поведінки, а не лише опис нових систем.
Загальна картина
OpenSpec організовує вашу роботу в два основні напрямки:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Джерело правди │◄─────│ Запропоновані зміни │ │
│ │ Як ваша система │ merge│ Кожна зміна = одна тека │ │
│ │ працює зараз │ │ Містить артефакти + дельти │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs (специфікації) — це джерело правди — вони описують, як ваша система працює наразі.
Changes (зміни) — це запропоновані модифікації — вони зберігаються в окремих теках, поки ви не будете готові об'єднати їх.
Цей поділ є ключовим. Ви можете працювати над кількома змінами паралельно без конфліктів. Ви можете переглянути зміну, перш ніж вона вплине на основні специфікації. А коли ви архівуєте зміну, її дельти чисто об'єднуються з джерелом правди.
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/
Формат специфікації
Специфікація містить вимоги, і кожна вимога має сценарії:
markdown
# Специфікація автентифікації
## Мета
Автентифікація та керування сесіями для додатку.
## Вимоги
### Вимога: Автентифікація користувача
Система ПОВИННА видавати JWT-токен після успішного входу.
#### Сценарій: Дійсні облікові дані
- ДАНО користувача з дійсними обліковими даними
- КОЛИ користувач надсилає форму входу
- ТОДІ повертається JWT-токен
- І користувач перенаправляється на панель керування
#### Сценарій: Недійсні облікові дані
- ДАНО недійсні облікові дані
- КОЛИ користувач надсилає форму входу
- ТОДІ відображається повідомлення про помилку
- І токен не видається
### Вимога: Завершення сесії
Система ПОВИННА завершувати сесії після 30 хвилин бездіяльності.
#### Сценарій: Час простою
- ДАНО автентифіковану сесію
- КОЛИ проходить 30 хвилин без активності
- ТОДІ сесія стає недійсною
- І користувач повинен пройти автентифікацію зановоКлючові елементи:
| Елемент | Призначення |
|---|---|
## Мета | Загальний опис домену цієї специфікації |
### Вимога: | Конкретна поведінка, яку система повинна мати |
#### Сценарій: | Конкретний приклад вимоги в дії |
| SHALL/MUST/SHOULD | Ключові слова RFC 2119, що вказують на силу вимоги |
Чому специфікації структуровані саме так
Вимоги — це "що" — вони вказують, що система повинна робити, не визначаючи реалізацію.
Сценарії — це "коли" — вони надають конкретні приклади, які можна перевірити. Добрі сценарії:
- Є тестованими (для них можна написати автоматизований тест)
- Охоплюють як основний шлях, так і крайні випадки
- Використовують формат Given/When/Then або подібну структуровану форму
Ключові слова RFC 2119 (SHALL, MUST, SHOULD, MAY) передають намір:
- MUST/SHALL — абсолютна вимога
- SHOULD — рекомендовано, але є винятки
- MAY — опціонально
Що таке специфікація (і чим вона не є)
Специфікація — це контракт поведінки, а не план реалізації.
Добрий вміст специфікації:
- Спостережувана поведінка, на яку покладаються користувачі або зовнішні системи
- Входи, виходи та умови помилок
- Зовнішні обмеження (безпека, конфіденційність, надійність, сумісність)
- Сценарії, які можна перевірити або явно валідувати
Уникайте в специфікаціях:
- Внутрішніх назв класів/функцій
- Вибору бібліотек або фреймворків
- Покрокових деталей реалізації
- Детальних планів виконання (вони належать до
design.mdабоtasks.md)
Швидкий тест:
- Якщо реалізація може змінитися без зміни зовнішньої видимої поведінки, вона, ймовірно, не належить до специфікації.
Зберігайте легкість: прогресивна строгість
OpenSpec прагне уникнути бюрократії. Використовуйте найлегший рівень, який все ще дозволяє зробити зміну перевірюваною.
Легка специфікація (за замовчуванням):
- Короткі вимоги з фокусом на поведінку
- Чіткий обсяг та цілі, що не входять до нього
- Кілька конкретних перевірок прийнятності
Повна специфікація (для вищого ризику):
- Зміни між командами або між репозиторіями
- Зміни API/контрактів, міграції, проблеми безпеки/конфіденційності
- Зміни, де неоднозначність може призвести до дорогого переділювання
Більшість змін мають залишатися в легкому режимі.
Співпраця людини та агента
У багатьох командах люди досліджують, а агенти створюють артефакти. Передбачуваний цикл:
- Людина надає намір, контекст та обмеження.
- Агент перетворює це на вимоги з фокусом на поведінку та сценарії.
- Агент зберігає деталі реалізації в
design.mdтаtasks.md, а не вspec.md. - Валідація підтверджує структуру та ясність перед реалізацією.
Це робить специфікації зрозумілими для людей та узгодженими для агентів.
Changes (Зміни)
Зміна — це запропонована модифікація вашої системи, упакована як тека з усім необхідним для розуміння та реалізації.
Структура зміни
openspec/changes/add-dark-mode/
├── proposal.md # Чому і що
├── design.md # Як (технічний підхід)
├── tasks.md # Чек-лист реалізації
├── .openspec.yaml # Метадані зміни (опціонально)
└── specs/ # Дельта-специфікації
└── ui/
└── spec.md # Що змінюється в ui/spec.mdКожна зміна є автономною. Вона має:
- Артефакти — документи, що фіксують намір, дизайн та завдання
- Дельта-специфікації — специфікації того, що додається, змінюється або видаляється
- Метадані — опціональна конфігурація для цієї конкретної зміни
Чому зміни — це теки
Упакування зміни як теки має кілька переваг:
Все разом. Пропозиція, дизайн, завдання та специфікації знаходяться в одному місці. Не потрібно шукати в різних місцях.
Паралельна робота. Кілька змін можуть існувати одночасно без конфліктів. Працюйте над
add-dark-mode, покиfix-auth-bugтакож у роботі.Чиста історія. При архівації зміни переміщуються до
changes/archive/зі збереженням повного контексту. Ви можете озирнутися і зрозуміти не лише що змінилося, але й чому.Зручність перегляду. Теку зміни легко переглядати — відкрийте її, прочитайте пропозицію, перевірте дизайн, перегляньте дельти специфікацій.
Артефакти
Артефакти — це документи в межах зміни, які керують роботою.
Потік артефактів
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeАртефакти будуються один на одному. Кожен артефакт надає контекст для наступного.
Типи артефактів
Пропозиція (proposal.md)
Пропозиція фіксує намір, обсяг та підхід на загальному рівні.
markdown
# Пропозиція: Додати темний режим
## Намір
Користувачі просили опцію темного режиму для зменшення навантаження на очі
під час нічного використання та відповідності системним налаштуванням.
## Обсяг
В обсязі:
- Перемикач теми в налаштуваннях
- Виявлення системних уподобань
- Збереження уподобання в localStorage
Поза обсягом:
- Користувацькі кольорові теми (майбутня робота)
- Перевизначення теми для окремих сторінок
## Підхід
Використовувати CSS-кастомні властивості для теми з контекстом React
для керування станом. Виявляти системні уподобання при першому завантаженні,
дозволяти ручне перевизначення.Коли оновлювати пропозицію:
- Змінюється обсяг (звужується або розширюється)
- Уточнюється намір (краще розуміння проблеми)
- Підхід кардинально змінюється
Специфікації (дельта-специфікації в specs/)
Дельта-специфікації описують що змінюється відносно поточних специфікацій. Див. Дельта-специфікації нижче.
Дизайн (design.md)
Дизайн фіксує технічний підхід та архітектурні рішення.
markdown
# Дизайн: Додати темний режим
## Технічний підхід
Стан теми керується через React Context для уникнення прокидання пропсів.
CSS-кастомні властивості дозволяють перемикання в часі виконання без перемикання класів.
## Архітектурні рішення
### Рішення: Контекст замість 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`)
Завдання — це **чек-лист реалізації** — конкретні кроки з прапорцями.
```markdown
# Завдання
## 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 придатним для розробки в існуючих проєктах. Вони описують **що змінюється**, а не переказують всю специфікацію.
### Формат
```markdown
# Дельта для Auth
## ДОДАНІ вимоги
### Вимога: Двофакторна аутентифікація
Система ПОВИННА підтримувати двофакторну аутентифікацію на основі TOTP.
#### Сценарій: Реєстрація 2FA
- ДАНО користувач без увімкненої 2FA
- КОЛИ користувач увімкне 2FA в налаштуваннях
- ТОДІ відображається QR-код для налаштування додатка-аутентифікатора
- І користувач повинен підтвердити кодом перед активацією
#### Сценарій: Вхід з 2FA
- ДАНО користувач з увімкненою 2FA
- КОЛИ користувач надає дійсні облікові дані
- ТОДІ пред'являється запит OTP
- І вхід завершується лише після дійсного OTP
## ЗМІНЕНІ вимоги
### Вимога: Завершення сесії
Система ПОВИННА завершувати сесії через 15 хвилин бездіяльності.
(Раніше: 30 хвилин)
#### Сценарій: Тайм-аут бездіяльності
- ДАНО автентифікована сесія
- КОЛИ проходить 15 хвилин без активності
- ТОДІ сесія стає недійсною
## ВИДАЛЕНІ вимоги
### Вимога: Запам'ятати мене
(Застаріло на користь 2FA. Користувачі повинні повторно проходити аутентифікацію в кожній сесії.)
```
### Розділи дельти
| Розділ | Значення | Що відбувається при архівації |
|---------|---------|------------------------|
| `## ДОДАНІ вимоги` | Нова поведінка | Додається до основної специфікації |
| `## ЗМІНЕНІ вимоги` | Змінена поведінка | Замінює існуючу вимогу |
| `## ВИДАЛЕНІ вимоги` | Застаріла поведінка | Видаляється з основної специфікації |
### Чому дельти, а не повні специфікації
**Чіткість.** Дельта показує саме те, що змінюється. Читаючи повну специфікацію, вам довелося б ментально порівнювати її з поточною версією.
**Уникнення конфліктів.** Дві зміни можуть стосуватися того самого файлу специфікації без конфлікту, якщо вони модифікують різні вимоги.
**Ефективність перегляду.** Рецензенти бачать зміну, а не незмінний контекст. Фокус на тому, що має значення.
**Відповідність для існуючих проєктів.** Більша частина роботи модифікує існуючу поведінку. Дельти роблять модифікації першокласними, а не другорядними.
## Схеми
Схеми визначають типи артефактів та їхні залежності для робочого процесу.
### Як працюють схеми
```yaml
# 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
(потребує: (потребує:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(потребує:
specs, design)
```
**Залежності є можливостями, а не блокуваннями.** Вони показують, що можна створити, а не те, що ви повинні створити наступним. Ви можете пропустити дизайн, якщо він вам не потрібен. Ви можете створити специфікації до або після дизайну — обидва залежать лише від пропозиції.
### Вбудовані схеми
**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, перейти до завдань
```
Дивіться [Налаштування](customization.md) для повних деталей щодо створення та використання користувацьких схем.
## Архівація
Архівація завершує зміну, зливаючи її дельта-специфікації з основними специфікаціями та зберігаючи зміну для історії.
### Що відбувається при архівації
```
До архівації:
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 (core) або /opsx:new (expanded) │
│ │ ЗМІНУ │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. СТВОРИТИ │ /opsx:ff або /opsx:continue (expanded workflow) │
│ │ АРТЕФАКТИ │ Створює proposal → specs → design → tasks │
│ │ │ (на основі залежностей схеми) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. РЕАЛІЗУВАТИ│ /opsx:apply │
│ │ ЗАВДАННЯ │ Виконувати завдання, відмічаючи їх │
│ │ │◄──── Оновлювати артефакти по мірі навчання │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. ПЕРЕВІРИТИ │ /opsx:verify (опціонально) │
│ │ РОБОТУ │ Перевірити, що реалізація відповідає специфікаціям │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. АРХІВУВАТИ │────►│ Дельта-специфікації зливаються з основними │ │
│ │ ЗМІНУ │ │ Папка зміни переміщується до archive/ │ │
│ └────────────────┘ │ Специфікації тепер є оновленим джерелом │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```
**Добрий цикл:**
1. Специфікації описують поточну поведінку
2. Зміни пропонують модифікації (у вигляді дельт)
3. Реалізація робить зміни реальними
4. Архівація зливає дельти зі специфікаціями
5. Специфікації тепер описують нову поведінку
6. Наступна зміна базується на оновлених специфікаціях
## Глосарій
| Термін | Визначення |
|------|------------|
| **Артефакт** | Документ у межах зміни (пропозиція, дизайн, завдання або дельта-специфікація) |
| **Архівація** | Процес завершення зміни та злиття її дельт у основні специфікації |
| **Зміна** | Пропонована модифікація системи, упакована у папку з артефактами |
| **Дельта-специфікація** | Специфікація, що описує зміни (ДОДАНО/ЗМІНЕНО/ВИДАЛЕНО) відносно поточних специфікацій |
| **Домен** | Логічна групування для специфікацій (наприклад, `auth/`, `payments/`) |
| **Вимога** | Конкретна поведінка, яку система повинна мати |
| **Сценарій** | Конкретний приклад вимоги, зазвичай у форматі Given/When/Then |
| **Схема** | Визначення типів артефактів та їх залежностей |
| **Специфікація** | Документ, що описує поведінку системи, містить вимоги та сценарії |
| **Джерело правди** | Директорія `openspec/specs/`, що містить поточну узгоджену поведінку |
## Наступні кроки
- [Початок роботи](getting-started.md) - Практичні перші кроки
- [Робочі процеси](workflows.md) - Поширені патерни та коли використовувати кожен
- [Команди](commands.md) - Повний довідник команд
- [Налаштування](customization.md) - Створення власних схем та конфігурація вашого проєкту