Концепції
Цей гайд пояснює основні ідеї 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 більш гнучкий — ви можете створювати артефакти в будь-якому порядку, який має сенс для вашої роботи.
Ітеративність, а не водоспадок (waterfall). Вимоги змінюються. Розуміння поглиблюється. Те, що здавалося хорошим підходом на початку, може виявитися недійсним після того, як ви побачите кодову базу. OpenSpec приймає цю реальність.
Простота, а не складність. Деякісь фреймворки специфікації вимагають обширного налаштування, жорстких форматів або важких процесів. OpenSpec нічого вам не заважає. Ініціалізуйтеся за секунди, починайте працювати негайно, налаштовуючи лише за потреби.
Пріоритет існуючих систем (brownfield). Більшість роботи над програмним забезпеченням полягає не у створенні з нуля, а в модифікації існуючих систем. Підхід 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 (Зміни) — це запропоновані модифікації, які зберігаються у окремих папках до моменту злиття.
Цей поділ є ключовим. Ви можете одночасно працювати над кількома змінами без конфліктів. Ви можете переглянути зміну до того, як вона вплине на основні специфікації. І коли ви архівуєте зміну, її дельти чисто зливаються в джерело істини.
Specs (Специфікації)
Specs описують поведінку вашої системи за допомогою структурованих вимог та сценаріїв.
Структура
openspec/specs/
├── auth/
│ └── spec.md # Поведінка автентифікації
├── payments/
│ └── spec.md # Обробка платежів
├── notifications/
│ └── spec.md # Система сповіщень
└── ui/
└── spec.md # Поведінка UI та темиОрганізуйте специфікації за доменами — логічними групами, які мають сенс для вашої системи. Типові патерни:
- За областю функцій:
auth/,payments/,search/ - За компонентом:
api/,frontend/,workers/ - За обмеженим контекстом (bounded context):
ordering/,fulfillment/,inventory/
Формат Spec
Spec містить вимоги, а кожна вимога має сценарії:
markdown
# Специфікація Auth
## Мета
Управління автентифікацією та сесіями для застосунку.
## Вимоги
### Вимога: Автентифікація користувача
Система ПОВИННА видавати JWT-токен після успішного входу.
#### Сценарій: Валідні облікові дані
- ВИПРИМУВАННЯ (GIVEN) користувач з валідними обліковими даними
- КОЛИ (WHEN) користувач надсилає форму входу
- ТОДІ (THEN) повертається JWT-токен
- І користувача перенаправляють на панель керування
#### Сценарій: Невалідні облікові дані
- ВИПРИМУВАННЯ (GIVEN) невалідні облікові дані
- КОЛИ (WHEN) користувач надсилає форму входу
- ТОДІ (THEN) відображається повідомлення про помилку
- І жоден токен не видається
### Вимога: Термін дії сесії
Система ПОВИННА завершувати сесії після 30 хвилин бездіяльності.
#### Сценарій: Таймаут бездіяльності
- ВИПРИМУВАННЯ (GIVEN) автентифікована сесія
- КОЛИ (WHEN) минуло 30 хвилин без активності
- ТОДІ (THEN) сесія анулюється
- І користувач повинен повторно пройти аутентифікаціюКлючові елементи:
| Елемент | Призначення |
|---|---|
## Мета | Високорівневий опис домену цієї специфікації |
### Вимога: | Конкретна поведінка, яку має мати система |
#### Сценарій: | Конкретний приклад вимоги в дії |
| SHALL/MUST/SHOULD | Ключові слова RFC 2119, що вказують на силу вимоги |
Чому таку структурування Spec
Вимоги — це "що" — вони констатують, що має робити система, не визначаючи реалізацію.
Сценарії — це "коли" — вони надають конкретні приклади, які можна перевірити. Хороші сценарії:
- Піддаються тестуванню (ви можете написати для них автоматичний тест)
- Охоплюють як щасливий шлях, так і граничні випадки
- Використовують структуру Given/When/Then або подібну
Ключові слова RFC 2119 (SHALL, MUST, SHOULD, MAY) комунікують намір:
- MUST/SHALL — абсолютна вимога
- SHOULD — рекомендовано, але є винятки
- MAY — необов'язково
Що таке Spec (і чого це не є)
Spec — це контракт поведінки, а не план реалізації.
Хороша змістовність специфікації:
- Спостережувана поведінка, на яку покладаються користувачі або нижчорядні системи
- Входи, виходи та умови помилок
- Зовнішні обмеження (безпека, конфіденційність, надійність, сумісність)
- Сценарії, які можна протестувати або явно підтвердити
Чого слід уникати в специфікаціях:
- Внутрішні назви класів/функцій
- Вибір бібліотек чи фреймворків
- Деталі покрокової реалізації
- Детальні плани виконання (вони належать до
design.mdабоtasks.md)
Швидкий тест:
- Якщо реалізація може змінитися без зміни зовнішньо видимої поведінки, вона ймовірно не належить у специфікацію.
Зберігайте простотою: Прогресивна суворість (Progressive Rigor)
OpenSpec прагне уникати бюрократії. Використовуйте найлегший рівень, який все ще робить зміну перевірюваною.
Lite spec (стандартний):
- Короткі вимоги, орієнтовані на поведінку
- Чіткий обсяг та нецілі
- Кілька конкретних критеріїв прийняття
Full spec (для вищого ризику):
- Зміни, що стосуються кількох команд або репозиторіїв
- Зміни API/контрактів, міграції, проблеми безпеки/конфіденційності
- Зміни, де ймовірно виникне неоднозначність, яка призведе до дорогих переробок
Більшість змін мають залишатися у Lite-режимі.
Співпраця людини та Агента (Human + Agent Collaboration)
У багатьох командах люди досліджують, а агенти створюють артефакти. Запланований цикл такий:
- Людина надає намір, контекст і обмеження.
- Агент перетворює це на вимоги та сценарії, орієнтовані на поведінку.
- Агент зберігає деталі реалізації в
design.mdтаtasks.md, а не вspec.md. - Валідація підтверджує структуру та чіткість перед реалізацією.
Це робить специфікації читабельними для людей і послідовними для агентів.
Changes (Зміни)
Зміна — це запропонована модифікація вашої системи, упакована як папка з усім необхідним для розуміння та реалізації.
Структура Зміни
openspec/changes/add-dark-mode/
├── proposal.md # Чому і що
├── design.md # Як (технічний підхід)
├── tasks.md # Чекліст реалізації
├── .openspec.yaml # Метадані зміни (необов'язково)
└── specs/ # Delta специфікації
└── ui/
└── spec.md # Що змінюється в ui/spec.mdКожна зміна є самодостатньою. Вона містить:
- Artifacts (Артефакти) — документи, що фіксують намір, дизайн та завдання
- Delta specs — специфікації того, що додається, модифікується або видаляється
- Metadata — необов'язкова конфігурація для цієї конкретної зміни
Чому Зміни є Папками
Пакування змін у папці має кілька переваг:
- Все разом. Пропозиція, дизайн, завдання та специфікації знаходяться в одному місці. Не потрібно шукати в різних локаціях.
- Паралельна робота. Кілька змін можуть існувати одночасно без конфліктів. Працюйте над
add-dark-mode, поки триваєfix-auth-bug. - Чиста історія. При архівуванні зміни переміщуються до
changes/archive/з збереженим повним контекстом. Ви можете зазирнути назад і зрозуміти не лише те, що змінилося, але й чому. - Зручно для перегляду (Review-friendly). Папка зі змінами легко переглядається — відкрийте її, прочитайте пропозицію, перевірте дизайн, подивіться на дельти специфікацій.
Artifacts (Артефакти)
Артефакти — це документи всередині зміни, які спрямовують роботу.
Потік Артефактів
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeАртефакти будуються один на одного. Кожен артефакт надає контекст для наступного.
Типи Артефактів
Proposal (proposal.md)
Пропозиція фіксує намір (intent), обсяг (scope) та підхід (approach) на високому рівні.
markdown
# Пропозиція: Додати темну тему
## Намір
Користувачі висловили побажання щодо опції темної теми для зменшення напруги очей під час нічного використання та відповідності системним уподобанням.
## Обсяг
Входить у обсяг:
- Перемикач теми в налаштуваннях
- Виявлення системних уподобань
- Збереження пріоритету у localStorage
Не входить у обсяг:
- Кастомні кольорові теми (майбутня робота)
- Перевизначення тем для кожної сторінки
## Підхід
Використовувати CSS custom properties для тематизації з React context для управління станом. Виявляти системне уподобання при першому завантаженні, дозволити ручне перевизначення.Коли оновлювати пропозицію:
- Зміни обсягу (звуження або розширення)
- Уточнення наміру (краще розуміння проблеми)
- Фундаментальна зміна підходу
Specs (Delta specs у specs/)
Delta specs описують що змінюється відносно поточних специфікацій. Дивіться Delta Specs нижче.
Design (design.md)
Дизайн фіксує технічний підхід та архітектурні рішення.
markdown
# Дизайн: Додати темну тему
## Технічний Підхід
Стан теми керується через React Context, щоб уникнути prop drilling. CSS custom properties дозволяють перемикання в режимі реального часу без перемикання класів.
## Архітектурні Рішення
### Рішення: Context замість Redux
Використання React Context для стану теми, тому що:
- Простий бінарний стан (світло/темно)
- Немає складних переходів стану
- Уникаємо додавання залежності Redux
### Рішення: CSS Custom Properties
Використання змінних CSS замість CSS-in-JS, тому що:
- Працює з існуючим файлом стилів
- Відсутній накладний витрат часу в режимі реального часу
- Власне рішення браузера
## Потік Даних
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (застосовуються до :root)
```
## Зміни Файлів
- `src/contexts/ThemeContext.tsx` (новий)
- `src/components/ThemeToggle.tsx` (новий)
- `src/styles/globals.css` (змінено)Коли оновлювати дизайн:
- Реалізація виявляє, що підхід не спрацює
- Знайдено краще рішення
- Змінюються залежності або обмеження
Tasks (tasks.md)
Завдання — це чекліст реалізації — конкретні кроки з чекбоксами.
markdown
# Завдання
## 1. Інфраструктура теми
- [ ] 1.1 Створити ThemeContext зі станом light/dark
- [ ] 1.2 Додати CSS custom properties для кольорівів
- [ ] 1.3 Реалізувати збереження у localStorage
- [ ] 1.4 Додати виявлення системних уподобань
## 2. UI Компоненти
- [ ] 2.1 Створити компонент ThemeToggle
- [ ] 2.2 Додати перемикач на сторінку налаштувань
- [ ] 2.3 Оновити Header, щоб включити швидкий перемикач
## 3. Стилізація
- [ ] 3.1 Визначити палітру кольорівів темної теми
- [ ] 3.2 Оновити компоненти для використання CSS variables
- [ ] 3.3 Тестувати коефіцієнти контрастності для доступностіНайкращі практики виконання завдань:
- Групуйте пов'язані завдання під заголовками
- Використовуйте ієрархічне нумерування (1.1, 1.2 тощо)
- Тримайте завдання достатньо малими, щоб виконати їх за одну сесію
- Завершуйте завдання після виконання
Delta Specs (Дельта Специфікації)
Delta specs — це ключова концепція, яка робить OpenSpec робочим для розробки на існуючій базах (brownfield development). Вони описують що змінюється, а не повторюють всю специфікацію.
Формат
markdown
# Дельта для Auth
## ДОДАНО ВИМОГИ (ADDED Requirements)
### Вимога: Двофакторна автентифікація
Система ПОВИННА підтримувати двофакторну автентифікацію на основі TOTP.
#### Сценарій: Реєстрація 2FA
- ВИПРИМУВАННЯ (GIVEN) користувач без увімкненої 2FA
- КОЛИ (WHEN) користувач вмикає 2FA в налаштуваннях
- ТОДІ (THEN) відображається QR-код для налаштування програми аутентифікатора
- І користувач повинен підтвердити за допомогою коду перед активацією
#### Сценарій: Вхід з 2FA
- ВИПРИМУВАННЯ (GIVEN) користувач із увімкненою 2FA
- КОЛИ (WHEN) користувач надсилає валідні облікові дані
- ТОДІ (THEN) відображається виклик OTP
- І вхід завершується лише після валідного OTP
## ЗМІНЕНО ВИМОГИ (MODIFIED Requirements)
### Вимога: Термін дії сесії
Система ПОВИННА завершувати сесії після 15 хвилин бездіяльності.
(Раніше: 30 хвилин)
#### Сценарій: Таймаут бездіяльності
- ВИПРИМУВАННЯ (GIVEN) автентифікована сесія
- КОЛИ (WHEN) минуло 15 хвилин без активності
- ТОДІ (THEN) сесія анулюється
## ВИДАЛЕНО ВИМОГИ (REMOVED Requirements)
### Вимога: Запам'ятати мене
(Застаріла на користь 2FA. Користувачі повинні повторно пройти аутентифікацію при кожній сесії.)Секції Дельти
| Секція | Значення | Що відбувається при архівуванні |
|---|---|---|
## ДОДАНО ВИМОГИ | Нова поведінка | Додається до основної специфікації |
## ЗМІНЕНО ВИМОГИ | Змінена поведінка | Замінює існуючу вимогу |
## ВИДАЛЕНО ВИМОГИ | Застаріла поведінка | Видаляється з основної специфікації |
Чому Дельти, а не Повні Специфікації
Чіткість. Дельта показує рівно, що змінюється. Читаючи повну специфікацію, вам довелося б подумки порівнювати її з поточною версією.
Уникнення конфліктів. Дві зміни можуть торкатися одного файлу специфікації без конфлікту, якщо вони модифікують різні вимоги.
Ефективність перегляду. Переглядачі бачать зміну, а не незмінний контекст. Фокус на тому, що важливо.
Відповідність brownfield. Більшість роботи змінює існуючу поведінку. Дельти роблять модифікації першокласними, а не другорядними думками.
Схеми
Схеми визначають типи артефактів та їх залежності для робочого процесу (workflow).
Як працюють схеми
yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # No dependencies, can create first
- id: specs
generates: specs/**/*.md
requires: [proposal] # Needs proposal before creating
- id: design
generates: design.md
requires: [proposal] # Can create in parallel with specs
- id: tasks
generates: tasks.md
requires: [specs, design] # Needs both specs and design firstАртефакти формують граф залежностей:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Залежності є уможливлювачами (enablers), а не блокувальними гейтами. Вони показують, що можливо створити, а не те, що ви мусите створити далі. Ви можете пропустити дизайн, якщо він вам не потрібен. Ви можете створити specs до або після дизайну — обидва залежать лише від proposal.
Вбудовані схеми
spec-driven (за замовчуванням)
Стандартний робочий процес для специфікаційного розроблення:
proposal → specs → design → tasks → implementНайкраще підходить для: Більшості функціональних завдань, де ви хочете узгодити специфікації до реалізації.
Кастомні схеми (Custom Schemas)
Створіть кастомні схеми для робочого процесу вашої команди:
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 для отримання повної інформації про створення та використання кастомних схем.
Архівування (Archive)
Архівування завершує зміну шляхом злиття її дельта-специфікацій (delta specs) у головні специфікації, зберігаючи цю зміну для історії.
Що відбувається при архівуванні
До архівування:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── 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/) показують лише роботу в процесі. Завершена робота виводиться з поля зору.
Аудитний слід (Audit trail). Архів зберігає повний контекст кожної зміни — не просто те, що змінилося, а й пропозицію, яка пояснює чому, дизайн, який пояснює як, та завдання, які показують виконану роботу.
Еволюція специфікацій. Специфікації розвиваються органічно, коли змінюються архівуються. Кожен архів зливає свої дельти, нарощуючи комплексну специфікацію з часом.
Як це все працює разом
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Створює proposal → specs → design → tasks │
│ │ │ (на основі залежностей схеми) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Виконує завдання, відмічаючи їх │
│ │ │◄──── Оновлюйте артефакти, коли щось дізнаєтеся │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Перевіряє, чи реалізація відповідає специфікаціям │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Дельта-специфікації зливаються в головні специфікації │ │
│ │ CHANGE │ │ Папка змін переміщується до archive/ │ │
│ └────────────────┘ │ Специфікації тепер є оновленим джерелом істини │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Що таке доброчесний цикл (The virtuous cycle):
- Специфікації описують поточну поведінку.
- Зміни пропонують модифікації (як дельти).
- Реалізація робить зміни реальними.
- Архівування зливає дельти у специфікації.
- Специфікації тепер описують нову поведінку.
- Наступна зміна будується на оновлених специфікаціях.
Глосарій (Glossary)
| Термін | Визначення |
|---|---|
| Artifact | Документ у межах зміни (пропозиція, дизайн, завдання або дельта-специфікації). |
| Archive | Процес завершення зміни та злиття її дельт у головні специфікації. |
| Change | Запропонована модифікація системи, упакована як папка зі артефактами. |
| Delta spec | Специфікація, яка описує зміни (ADDED/MODIFIED/REMOVED) відносно поточних специфікацій. |
| Domain | Логічна група для специфікацій (наприклад, auth/, payments/). |
| Requirement | Конкретна поведінка, яку має мати система. |
| Scenario | Конкретний приклад вимоги, зазвичай у форматі Given/When/Then. |
| Schema | Визначення типів артефактів та їх залежностей. |
| Spec | Специфікація, що описує поведінку системи і містить вимоги та сценарії. |
| Source of truth | Директорія openspec/specs/, яка містить поточну узгоджену поведінку. |
Наступні кроки (Next Steps)
- Getting Started - Практичні перші кроки
- Workflows - Поширені шаблони та коли їх використовувати
- Commands - Повна довідка команд
- Customization - Створення кастомних схем та конфігурація вашого проєкту