Концепції
Цей посібник пояснює основні ідеї, на яких побудовано OpenSpec, та те, як вони взаємопов'язуються. Для отримання практичних рекомендацій з використання перейдіть до розділів Початок роботи та Робочі процеси.
Філософія
OpenSpec побудовано навколо чотирьох принципів:
Гнучкість, а не жорсткість — відсутність фазових шлюзів, робота над тим, що має сенс
Ітеративність, а не каскадна модель — навчання в процесі розробки, постійне вдосконалення
Простота, а не складність — легка налаштування, мінімум формальностей
Броунфілд-орієнтованість — працює з наявними кодовыми базами, а не лише з новими проєктами, розробленими з нуля (грінфілд)Чому ці принципи важливі
Гнучкість, а не жорсткість. Традиційні системи специфікацій прив'язують вас до фаз: спочатку ви плануєте, потім реалізуєте, потім робота вважається завершеною. OpenSpec є більш гнучким — ви можете створювати артефакти в будь-якому порядку, який зручний для вашої роботи.
Ітеративність, а не каскадна модель. Вимоги змінюються. Розуміння завдання поглиблюється. Те, що на початку здавалося хорошим підходом, може не витримувати перевірки після ознайомлення з кодовою базою. OpenSpec приймає цю реальність.
Простота, а не складність. Деякі фреймворки для роботи зі специфікаціями вимагають масштабної налаштування, жорстких форматів або обтяжливих процесів. OpenSpec не втручається у ваш робочий процес. Ініціалізація займає лічені секунди, ви можете почати роботу одразу, а налаштовувати систему можна лише за потреби.
Броунфілд-орієнтованість. Більшість робіт у сфері розробки програмного забезпечення полягає не в створенні систем з нуля, а в модифікації існуючих. Підхід OpenSpec, заснований на delta-змінах, дозволяє легко специфікувати зміни до існуючої поведінки систем, а не лише описувати нові системи.
Загальна картина
OpenSpec організовує вашу роботу на два основні області:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Джерело правди │◄─────│ Запропоновані модифікації │ │
│ │ Як ваша система │ злиття│ Кожна зміна = окрема папка │ │
│ │ працює зараз │ │ Містить артефакти + дельти │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Специфікації (Specs) є джерелом правди — вони описують, як ваша система працює зараз.
Зміни (Changes) — це запропоновані модифікації, які зберігаються в окремих папках, доки ви не будете готові їх злити.
Це розділення є ключовим. Ви можете працювати над кількома змінами паралельно без конфліктів. Ви можете перевірити зміну, перш ніж вона вплине на основні специфікації. А коли ви архівуєте зміну, її дельти безпроблемно зливаються в джерело правди.
Специфікації (Specs)
Специфікації описують поведінку вашої системи за допомогою структурованих вимог та сценаріїв.
Структура
openspec/specs/
├── auth/
│ └── spec.md # Поведінка автентифікації
├── payments/
│ └── spec.md # Обробка платежів
├── notifications/
│ └── spec.md # Система сповіщень
└── ui/
└── spec.md # Поведінка інтерфейсу та темиОрганізовуйте специфікації за доменами — логічними групуваннями, які мають сенс для вашої системи. Типові патерни:
- За областю функціоналу:
auth/,payments/,search/ - За компонентом:
api/,frontend/,workers/ - За обмеженим контекстом:
ordering/,fulfillment/,inventory/
Формат специфікації
Специфікація містить вимоги, а кожна вимога має сценарії:
markdown
# Специфікація автентифікації
## Мета
Автентифікація та керування сеансами для застосунку.
## Вимоги
### Вимога: Автентифікація користувача
Система ПОВИННА видавати JWT-токен після успішного входу.
#### Сценарій: Дійсні облікові дані
- ДАНО користувача з дійсними обліковими даними
- КОЛИ користувач надсилає форму входу
- ТОДІ повертається JWT-токен
- І користувача перенаправляється на інформаційну панель
#### Сценарій: Недійсні облікові дані
- ДАНО недійсні облікові дані
- КОЛИ користувач надсилає форму входу
- ТОДІ відображається повідомлення про помилку
- І жоден токен не видається
### Вимога: Завершення сеансу
Система ПОВИННА завершувати сеанси після 30 хвилин бездіяльності.
#### Сценарій: Таймаут бездіяльності
- ДАНО автентифікований сеанс
- КОЛИ минає 30 хвилин без активності
- ТОДІ сеанс анулюється
- І користувач має пройти автентифікацію повторноКлючові елементи:
| Елемент | Призначення |
|---|---|
## Purpose | Загальний опис домену цієї специфікації |
### Requirement: | Конкретна поведінка, яку повинна мати система |
#### Scenario: | Конкретний приклад роботи вимоги в дії |
| 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. - Валідація підтверджує структуру та зрозумілість перед початком реалізації.
Це зберігає специфікації читабельними для людей та узгодженими для агентів.
Зміни (Changes)
Зміна (Changes) — це запропонована модифікація вашої системи, упакована в папку з усім необхідним для її розуміння та реалізації.
Структура зміни
openspec/changes/add-dark-mode/
├── proposal.md # Чому та що
├── design.md # Як (технічний підхід)
├── tasks.md # Чекліст реалізації
├── .openspec.yaml # Метадані зміни (необов'язково): схема, дата створення, skip_specs
└── specs/ # Дельти специфікацій
└── ui/
└── spec.md # Що змінюється в ui/spec.mdКожна зміна є автономною. Вона містить:
- Артефакти (Artifacts) — документи, що фіксують намір, дизайн та завдання
- Дельти специфікацій (Delta specs) — специфікації того, що додається, змінюється або видаляється
- Метадані (Metadata) — необов'язкова конфігурація для цієї конкретної зміни
Чому зміни є папками
Упаковка зміни в папку має кілька переваг:
- Все в одному місці. Пропозиція, дизайн, завдання та специфікації зберігаються в одному місці. Не потрібно шукати їх у різних локаціях.
- Паралельна робота. Кілька змін можуть існувати одночасно без конфліктів. Ви можете працювати над
add-dark-mode, покиfix-auth-bugтакож в процесі реалізації. - Чиста історія. Після архівації зміни переміщуються до
changes/archive/з повним збереженням контексту. Ви можете переглянути історію та зрозуміти не тільки те, що змінилося, але й чому. - Зручність для перевірки. Папку зміни легко перевірити — відкрийте її, прочитайте пропозицію, перевірте дизайн, перегляньте дельти специфікацій.
Артефакти (Artifacts)
Артефакти (Artifacts) — це документи всередині зміни, що керують роботою.
Потік артефактів
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-контекст, щоб уникнути передачі пропсів через всі компоненти. CSS-змінні дозволяють перемикати тему під час роботи без перемикання класів.
## Архітектурні рішення
### Рішення: Контекст замість Redux
Використовуємо React-контекст для керування станом теми, оскільки:
- Простий бінарний стан (світла/темна)
- Немає складних переходів стану
- Уникаємо додавання залежності 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 тощо)
- Робіть завдання достатньо малими, щоб завершити їх за один сеанс роботи
- Відмічайте завдання виконаними по мірі їх завершення
Дельта-специфікації (Delta Specs)
Дельта-специфікації (Delta Specs) є ключовою концепцією, яка дозволяє OpenSpec працювати при броунфілд-розробці (розробці існуючих проєктів). Вони описують що змінюється, а не повторюють всю специфікацію повністю.
Формат
markdown
# Дельта для специфікації автентифікації
## ДОДАНІ вимоги
### Вимога: Двофакторна автентифікація
Система ПОВИННА підтримувати двофакторну автентифікацію на основі TOTP.
#### Сценарій: Підключення 2FA
- ДАНО користувача без увімкненої 2FA
- КОЛИ користувач увімкнює 2FA в налаштуваннях
- ТОДІ відображається QR-код для налаштування в застосунку для автентифікації
- І користувач має підтвердити дію кодом перед активацією
#### Сценарій: Вхід з 2FA
- ДАНО користувача з увімкненою 2FA
- КОЛИ користувач надсилає дійсні облікові дані
- ТОДІ відображається запит одноразового пароля
- І вхід завершується лише після введення дійсного OTP
## ЗМІНЕНІ вимоги
### Вимога: Завершення сеансу
Система ПОВИННА завершувати сеанси після 15 хвилин бездіяльності.
(Раніше: 30 хвилин)
#### Сценарій: Таймаут бездіяльності
- ДАНО автентифікований сеанс
- КОЛИ минає 15 хвилин без активності
- ТОДІ сеанс анулюється
## ВИДАЛЕНІ вимоги
### Вимога: Запам'ятати мене
(Застаріла на користь 2FA. Користувачі повинні проходити автентифікацію заново при кожному сеансі.)Розділи дельти
| Розділ | Значення | Що відбувається під час архівації |
|---|---|---|
## ADDED Requirements | Нова поведінка | Додається до основної специфікації |
## MODIFIED Requirements | Змінена поведінка | Замінює існуючу вимогу |
## REMOVED Requirements | Застаріла поведінка | Видаляється з основної специфікації |
Чому дельти замість повних специфікацій
Чіткість. Дельта показує точно, що змінюється. Читаючи повну специфікацію, вам довелося б порівнювати її з поточною версією вручну.
Уникнення конфліктів. Дві зміни можуть торкатися одного файлу специфікації без конфліктів, якщо вони змінюють різні вимоги.
Ефективність перевірки. Перевіряючі бачать саму зміну, а не незмінений контекст. Увага зосереджується на тому, що важливо.
Придатність для броунфілд-розробки. Більшість робіт змінює існуючу поведінку. Дельти роблять модифікації першокласними об'єктами, а не післядумкою.
Схеми
Схеми визначають типи артефактів та їхні залежності для робочого процесу.
Як працюють схеми
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
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
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Див. Customization для повної інформації про створення та використання користувацьких схем.
Архів
Архівування завершує зміну шляхом об'єднання її дельта-специфікацій з основними специфікаціями та збереження зміни для історії.
Що відбувається під час архівування
До архівування:
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 │
│ │
│ ┌────────────────┐ │
│ │ 1. ПОЧАТОК │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ ЗМІНИ │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. СТВОРЕННЯ │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ АРТЕФАКТІВ │ Створює proposal → specs → design → tasks │
│ │ │ (на основі залежностей схеми) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. РЕАЛІЗАЦІЯ │ /opsx:apply │
│ │ ЗАВДАНЬ │ Виконуйте завдання, відмічаючи їх │
│ │ │◄──── Оновлюйте артефакти у міру навчання │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. ПЕРЕВІРКА │ /opsx:verify (необов'язково) │
│ │ РОБОТИ │ Перевірте, чи реалізація відповідає специфікаціям │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. АРХІВУВАННЯ│────►│ Дельта-специфікації об'єднуються з основними │ │
│ │ ЗМІНИ │ │ Папка зміни переміщується до archive/ │ │
│ └────────────────┘ │ Специфікації тепер є оновленим джерелом │ │
│ │ істини │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Добрий цикл:
- Специфікації описують поточну поведінку
- Зміни пропонують модифікації (як дельти)
- Реалізація робить зміни реальними
- Архівування об'єднує дельти зі специфікаціями
- Специфікації тепер описують нову поведінку
- Наступна зміна базується на оновлених специфікаціях
Глосарій
| Термін | Визначення |
|---|---|
| Артефакт | Документ у межах зміни (пропозиція, дизайн, завдання або дельта-специфікації) |
| Архів | Процес завершення зміни та об'єднання її дельт з основними специфікаціями |
| Зміна | Запропонована модифікація системи, упакована як папка з артефактами |
| Дельта-специфікація | Специфікація, що описує зміни (ADDED/MODIFIED/REMOVED) відносно поточних специфікацій |
| Домен | Логічна група для специфікацій (наприклад, auth/, payments/) |
| Вимога | Конкретна поведінка, яку система повинна мати |
| Сценарій | Конкретний приклад вимоги, зазвичай у форматі Given/When/Then |
| Схема | Визначення типів артефактів та їхніх залежностей |
| Специфікація | Специфікація, що описує поведінку системи, містить вимоги та сценарії |
| Джерело істини | Директорія openspec/specs/, що містить поточну погоджену поведінку |
Наступні кроки
- Getting Started - Практичні перші кроки
- Workflows - Поширені шаблони та коли їх використовувати
- Commands - Повний довідник команд
- Customization - Створення користувацьких схем та налаштування проєкту