Концепції
Цей посібник пояснює основні ідеї OpenSpec та як вони поєднуються. Для практичного використання див. Початок роботи та Робочі процеси.
Філософія
OpenSpec побудований навколо чотирьох принципів:
гнучкий, не жорсткий — без фазових воріт, працюйте над тим, що має сенс
ітеративний, не каскадний — навчайтеся під час створення, вдосконалюйте в процесі
простий, не складний — легке налаштування, мінімальна церемонія
перш за все наявний код — працює з існуючими кодовими базами, а не лише з «зеленим полем»Чому ці принципи важливі
Гнучкий, не жорсткий. Традиційні системи специфікацій замикають вас у фазах: спочатку плануєте, потім реалізуєте, і готово. OpenSpec гнучкіший — ви можете створювати артефакти в будь-якому порядку, який має сенс для вашої роботи.
Ітеративний, не каскадний. Вимоги змінюються. Розуміння поглиблюється. Те, що здавалося хорошим підходом на початку, може не витримати після знайомства з кодовою базою. OpenSpec приймає цю реальність.
Простий, не складний. Деякі фреймворки специфікацій вимагають значних налаштувань, жорстких форматів або важких процесів. OpenSpec не заважає вам. Ініціалізуйте за секунди, починайте працювати одразу, налаштовуйте лише за потреби.
Перш за все наявний код. Більшість програмної роботи — це не створення з нуля, а модифікація наявних систем. Підхід OpenSpec на основі дельт дозволяє легко описувати зміни до існуючої поведінки, а не лише описувати нові системи.
Загальна картина
OpenSpec організовує вашу роботу у дві основні області:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Джерело істини │◄─────│ Запропоновані зміни │ │
│ │ Як ваша система │ злиття│ Кожна зміна = одна папка │ │
│ │ працює зараз │ │ Містить артефакти + дельти │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Специфікації (specs) — це джерело істини. Вони описують, як ваша система поводиться зараз.
Зміни (changes) — це запропоновані модифікації. Вони живуть в окремих папках, доки ви не будете готові їх злити.
Це розділення є ключовим. Ви можете працювати над кількома змінами паралельно без конфліктів. Ви можете перевірити зміну до того, як вона вплине на основні специфікації. А коли ви архівуєте зміну, її дельти чисто зливаються в джерело істини.
Специфікації
Специфікації описують поведінку вашої системи за допомогою структурованих вимог та сценаріїв.
Структура
openspec/specs/
├── auth/
│ └── spec.md # Поведінка автентифікації
├── payments/
│ └── spec.md # Обробка платежів
├── notifications/
│ └── spec.md # Система сповіщень
└── ui/
└── spec.md # Поведінка UI та темиОрганізуйте специфікації за доменами — логічними групами, які мають сенс для вашої системи. Поширені шаблони:
- За функціональною областю:
auth/,payments/,search/ - За компонентом:
api/,frontend/,workers/ - За обмеженим контекстом:
ordering/,fulfillment/,inventory/
Формат специфікації
Специфікація містить вимоги, а кожна вимога має сценарії:
# Специфікація автентифікації
## Призначення
Автентифікація та управління сесіями для застосунку.
## Вимоги
### Вимога: Автентифікація користувача
Система SHALL видавати JWT-токен при успішному вході.
#### Сценарій: Дійсні облікові дані
- ДАНО користувач із дійсними обліковими даними
- КОЛИ користувач надсилає форму входу
- ТОДІ повертається JWT-токен
- ТА користувач перенаправляється на панель керування
#### Сценарій: Недійсні облікові дані
- ДАНО недійсні облікові дані
- КОЛИ користувач надсилає форму входу
- ТОДІ відображається повідомлення про помилку
- ТА токен не видається
### Вимога: Закінчення сесії
Система MUST завершувати сесії після 30 хвилин бездіяльності.
#### Сценарій: Тайм-аут простою
- ДАНО автентифіковану сесію
- КОЛИ проходить 30 хвилин без активності
- ТОДІ сесія стає недійсною
- ТА користувач повинен автентифікуватися повторноКлючові елементи:
| Елемент | Призначення |
|---|---|
## Призначення | Високорівневий опис області цієї специфікації |
### Вимога: | Конкретна поведінка, яку повинна мати система |
#### Сценарій: | Конкретний приклад вимоги в дії |
| SHALL/MUST/SHOULD | Ключові слова RFC 2119, що вказують на силу вимоги |
Чому специфікації структуровані саме так
Вимоги — це «що» — вони заявляють, що система повинна робити, не вказуючи реалізацію.
Сценарії — це «коли» — вони надають конкретні приклади, які можна перевірити. Хороші сценарії:
- Перевіряються (можна написати автоматичний тест для них)
- Покривають як успішний шлях, так і граничні випадки
- Використовують формат Дано/Коли/Тоді або подібний структурований формат
Ключові слова RFC 2119 (SHALL, MUST, SHOULD, MAY) передають намір:
- MUST/SHALL — абсолютна вимога
- SHOULD — рекомендовано, але можливі винятки
- MAY — необов’язково
Що таке специфікація (і чим вона не є)
Специфікація — це контракт поведінки, а не план реалізації.
Хороший вміст специфікації:
- Спостережувана поведінка, на яку покладаються користувачі або залежні системи
- Вхідні дані, вихідні дані та умови помилок
- Зовнішні обмеження (безпека, конфіденційність, надійність, сумісність)
- Сценарії, які можна протестувати або явно перевірити
Уникайте у специфікаціях:
- Назв внутрішніх класів/функцій
- Вибір бібліотек або фреймворків
- Покрокові деталі реалізації
- Детальні плани виконання (вони належать до
design.mdабоtasks.md)
Швидка перевірка:
- Якщо реалізація може змінитися без зміни зовнішньо видимої поведінки, це, ймовірно, не належить до специфікації.
Зберігайте легкість: Поступова строгість
OpenSpec прагне уникати бюрократії. Використовуйте найлегший рівень, який все ще робить зміну перевірюваною.
Полегшена специфікація (типово):
- Короткі вимоги, орієнтовані на поведінку
- Чіткий обсяг та не-цілі
- Кілька конкретних приймальних перевірок
Повна специфікація (для підвищеного ризику):
- Крос-командні або крос-репозиторні зміни
- Зміни API/контрактів, міграції, питання безпеки/конфіденційності
- Зміни, де неоднозначність може спричинити дорогу переробку
Більшість змін повинні залишатися у полегшеному режимі.
Співпраця людини та агента
У багатьох командах люди досліджують, а агенти створюють артефакти. Запланований цикл:
- Людина надає намір, контекст та обмеження.
- Агент перетворює це на вимоги та сценарії, орієнтовані на поведінку.
- Агент зберігає деталі реалізації в
design.mdтаtasks.md, а не вspec.md. - Валідація підтверджує структуру та ясність перед реалізацією.
Це зберігає специфікації читабельними для людей і послідовними для агентів.
Зміни
Зміна — це запропонована модифікація вашої системи, запакована як папка з усім необхідним для її розуміння та реалізації.
Структура зміни
openspec/changes/add-dark-mode/
├── proposal.md # Чому і що
├── design.md # Як (технічний підхід)
├── tasks.md # Контрольний список реалізації
├── .openspec.yaml # Метадані зміни (необов’язково): schema, created, skip_specs, retire_capabilities
└── specs/ # Дельта-специфікації
└── ui/
└── spec.md # Що змінюється в ui/spec.mdКожна зміна є самодостатньою. Вона має:
- Артефакти — документи, які фіксують намір, дизайн та завдання
- Дельта-специфікації — специфікації того, що додається, змінюється або видаляється
- Метадані — необов’язкова конфігурація для цієї конкретної зміни
Чому зміни — це папки
Пакування зміни як папки має кілька переваг:
Все разом. Пропозиція, дизайн, завдання та специфікації знаходяться в одному місці. Не потрібно шукати в різних місцях.
Паралельна робота. Кілька змін можуть існувати одночасно без конфліктів. Працюйте над
add-dark-mode, покиfix-auth-bugтакож у процесі.Чиста історія. При архівуванні зміни переміщуються до
changes/archive/зі збереженням повного контексту. Ви можете озирнутися і зрозуміти не тільки що змінилося, а й чому.Зручність для перевірки. Папку зміни легко перевірити — відкрийте її, прочитайте пропозицію, перевірте дизайн, подивіться на дельта-специфікації.
Артефакти
Артефакти — це документи всередині зміни, які спрямовують роботу.
Потік артефактів
пропозиція ──────► специфікації ──────► дизайн ──────► завдання ──────► реалізація
│ │ │ │
чому що як кроки
+ обсяг зміни підхід для виконанняАртефакти будуються один на одному. Кожен артефакт надає контекст для наступного.
Типи артефактів
Пропозиція (proposal.md)
Пропозиція фіксує намір, обсяг та підхід на високому рівні.
# Пропозиція: Додати темну тему
## Мета
Користувачі запросили опцію темної теми для зменшення напруження очей
під час нічного використання та для відповідності системним налаштуванням.
## Обсяг
В обсязі:
- Перемикач теми в налаштуваннях
- Визначення системних налаштувань
- Збереження налаштувань у localStorage
Поза обсягом:
- Власні колірні теми (майбутня робота)
- Перевизначення теми на рівні сторінки
## Підхід
Використання CSS-властивостей користувача для тематизації з контекстом React
для управління станом. Визначати системні налаштування при першому завантаженні,
дозволяти ручне перевизначення.Коли оновлювати пропозицію:
- Зміна обсягу (звуження або розширення)
- Уточнення наміру (краще розуміння проблеми)
- Фундаментальна зміна підходу
Специфікації (дельта-специфікації в specs/)
Дельта-специфікації описують що змінюється відносно поточних специфікацій. Див. Дельта-специфікації нижче.
Дизайн (design.md)
Дизайн фіксує технічний підхід та архітектурні рішення.
# Дизайн: Додати темну тему
## Технічний підхід
Стан теми керується через React Context, щоб уникнути передачі пропсів углиб.
CSS-властивості користувача дозволяють перемикання під час виконання без класового перемикача.
## Архітектурні рішення
### Рішення: Context замість Redux
Використання React Context для стану теми, оскільки:
- Простий бінарний стан (світла/темна)
- Немає складних переходів стану
- Уникає додавання залежності від Redux
### Рішення: CSS-властивості користувача
Використання CSS-змінних замість CSS-in-JS, оскільки:
- Працює з існуючими таблицями стилів
- Без накладних витрат під час виконання
- Нативне рішення браузера
## Потік даних
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (застосовані до :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. UI-компоненти
- [ ] 2.1 Створити компонент ThemeToggle
- [ ] 2.2 Додати перемикач на сторінку налаштувань
- [ ] 2.3 Оновити Header, додавши швидкий перемикач
## 3. Стилізація
- [ ] 3.1 Визначити палітру кольорів темної теми
- [ ] 3.2 Оновити компоненти для використання CSS-змінних
- [ ] 3.3 Протестувати коефіцієнти контрастності для доступностіНайкращі практики завдань:
- Групуйте пов’язані завдання під заголовками
- Використовуйте ієрархічну нумерацію (1.1, 1.2 тощо)
- Робіть завдання достатньо малими, щоб завершити за одну сесію
- Відмічайте завдання як виконані по мірі завершення
Дельта-специфікації
Дельта-специфікації — це ключова концепція, яка робить OpenSpec придатним для розробки у brownfield-середовищі. Вони описують що змінюється, а не повторюють всю специфікацію.
Формат
# Дельта для Auth
## ДОДАНІ Вимоги
### Вимога: Двофакторна автентифікація
Система MUST підтримувати двофакторну автентифікацію на основі TOTP.
#### Сценарій: Реєстрація 2FA
- ДАНО користувач без увімкненої 2FA
- КОЛИ користувач вмикає 2FA у налаштуваннях
- ТОДІ відображається QR-код для налаштування додатку-автентифікатора
- ТА користувач повинен підтвердити кодом перед активацією
#### Сценарій: Вхід з 2FA
- ДАНО користувач з увімкненою 2FA
- КОЛИ користувач надсилає дійсні облікові дані
- ТОДІ відображається запит OTP
- ТА вхід завершується лише після дійсного OTP
## ЗМІНЕНІ Вимоги
### Вимога: Закінчення сесії
Система MUST завершувати сесії після 15 хвилин бездіяльності.
(Раніше: 30 хвилин)
#### Сценарій: Тайм-аут простою
- ДАНО автентифіковану сесію
- КОЛИ проходить 15 хвилин без активності
- ТОДІ сесія стає недійсною
## ВИЛУЧЕНІ Вимоги
### Вимога: Запам’ятати мене
(Вилучено на користь 2FA. Користувачі повинні повторно автентифікуватися кожну сесію.)Секції дельт
| Секція | Значення | Що відбувається при архівуванні |
|---|---|---|
## ДОДАНІ Вимоги | Нова поведінка | Додається до основної специфікації |
## ЗМІНЕНІ Вимоги | Змінена поведінка | Замінює існуючу вимогу |
## ВИЛУЧЕНІ Вимоги | Застаріла поведінка | Видаляється з основної специфікації; видалення останньої вимоги вилучає можливість та видаляє її файл специфікації, якщо зміна оголошує retire_capabilities: true |
## Призначення | Для чого призначена абсолютно нова можливість | Заповнює поле Призначення новостворюваної основної специфікації; ігнорується, якщо специфікація вже існує |
Чому дельти, а не повні специфікації
Ясність. Дельта показує точно, що змінюється. Читаючи повну специфікацію, вам довелося б подумки порівнювати її з поточною версією.
Уникнення конфліктів. Дві зміни можуть торкатися одного файлу специфікації без конфліктів, якщо вони змінюють різні вимоги.
Ефективність перевірки. Рецензенти бачать зміну, а не незмінений контекст. Зосередьтеся на тому, що важливо.
Підходить для brownfield. Більшість роботи змінює існуючу поведінку. Дельти роблять модифікації першокласними, а не другорядними.
Схеми
Схеми визначають типи артефактів та їхні залежності для робочого процесу.
Як працюють схеми
# 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)Залежності — це засоби, а не бар'єри. Вони показують, що можна створити, а не що ви повинні створити наступним. Ви можете пропустити дизайн, якщо він вам не потрібен. Ви можете створити специфікації до або після дизайну — обидві залежать лише від пропозиції.
Вбудовані схеми
spec-driven (типова)
Стандартний робочий процес для розробки, що керується специфікаціями:
proposal → specs → design → tasks → implementНайкраще підходить для: більшості робіт над функціональністю, де ви хочете узгодити специфікації перед реалізацією.
Кастомні схеми
Створюйте кастомні схеми для робочого процесу вашої команди:
# Create from scratch
openspec schema init research-first
# Or fork an existing one
openspec schema fork spec-driven research-firstПриклад кастомної схеми:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Do research first
- id: proposal
generates: proposal.md
requires: [research] # Proposal informed by research
- id: tasks
generates: tasks.md
requires: [proposal] # Skip specs/design, go straight to tasksДив. Кастомізація для повних деталей щодо створення та використання кастомних схем.
Архівування
Архівування завершує зміну, з'єднуючи її дельта-специфікації з основними специфікаціями та зберігаючи зміну для історії.
Що відбувається під час архівування
Before archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
After archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Now includes 2FA requirements
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preserved for history
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdПроцес архівування
З'єднання дельт. Кожна секція дельта-специфікації (ADDED/MODIFIED/REMOVED) застосовується до відповідної основної специфікації.
Переміщення до архіву. Папка зміни переміщується до
changes/archive/з префіксом дати для хронологічного впорядкування.Збереження контексту. Усі артефакти залишаються незмінними в архіві. Ви завжди можете повернутися, щоб зрозуміти, чому було зроблено зміну.
Чому архівування важливе
Чистий стан. Активні зміни (changes/) показують лише роботу в процесі. Завершену роботу прибирають з дороги.
Аудиторський слід. Архів зберігає повний контекст кожної зміни — не лише що змінилося, але й пропозицію, яка пояснює чому, дизайн, який пояснює як, та завдання, що показують виконану роботу.
Еволюція специфікацій. Специфікації органічно ростуть міру того, як зміни архівуються. Кожне архівування з'єднує свої дельти, поступово формуючи комплексну специфікацію.
Як усе це працює разом
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Creates proposal → specs → design → tasks │
│ │ │ (based on schema dependencies) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Work through tasks, checking them off │
│ │ │◄──── Update artifacts as you learn │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Check implementation matches specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta specs merge into main specs │ │
│ │ CHANGE │ │ Change folder moves to archive/ │ │
│ └────────────────┘ │ Specs are now the updated source of truth │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Цикл вдосконалення:
- Специфікації описують поточну поведінку
- Зміни пропонують модифікації (як дельти)
- Реалізація робить зміни реальними
- Архівування з'єднує дельти зі специфікаціями
- Специфікації тепер описують нову поведінку
- Наступна зміна будується на оновлених специфікаціях
Глосарій
| Термін | Визначення |
|---|---|
| Артефакт | Документ у межах зміни (пропозиція, дизайн, завдання або дельта-специфікації) |
| Архівування | Процес завершення зміни та з'єднання її дельт з основними специфікаціями |
| Зміна | Запропонована модифікація системи, упакowana як папка з артефактами |
| Дельта-специфікація | Специфікація, яка описує зміни (ADDED/MODIFIED/REMOVED) відносно поточних специфікацій |
| Домен | Логічна групування для специфікацій (напр., auth/, payments/) |
| Вимога | Конкретна поведінка, якою система повинна володіти |
| Сценарій | Конкретний приклад вимоги, зазвичай у форматі Given/When/Then |
| Схема | Визначення типів артефактів та їхніх залежностей |
| Специфікація | Специфікація, що описує поведінку системи, містить вимоги та сценарії |
| Джерело правди | Каталог openspec/specs/, що містить поточну узгоджену поведінку |
Наступні кроки
- Початок роботи — Практичні перші кроки
- Робочі процеси — Спільні патерни та коли використовувати кожен
- Команди — Повне посилання на команди
- Кастомізація — Створення кастомних схем та налаштування вашого проєкту