Початок роботи

Цей посібник пояснює, як працює OpenSpec після його встановлення та ініціалізації. Інструкції з встановлення дивіться в основному README.

Як це працює

OpenSpec допомагає вам та вашому AI-асистенту для кодування домовитися про те, що потрібно побудувати, перш ніж буде написано жодного рядка коду.

Стандартний швидкий шлях (профіль core):

/opsx:propose ──► /opsx:apply ──► /opsx:archive

Розширений шлях (вибір користувацького робочого процесу):

/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Стандартний глобальний профіль — core, який включає propose, explore, apply та archive. Ви можете увімкнути розширені команди робочого процесу за допомогою openspec config profile, а потім openspec update.

Що створює OpenSpec

Після запуску openspec init ваш проект має таку структуру:

openspec/
├── specs/              # Джерело правди (поведінка вашої системи)
│   └── <domain>/
│       └── spec.md
├── changes/            # Запропоновані оновлення (одна папка на зміну)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Дельта-специфікації (що змінюється)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Конфігурація проекту (необов'язково)

Дві ключові директорії:

• specs/ - Джерело правди. Ці специфікації описують поточну поведінку вашої системи. Організовані за доменами (наприклад, specs/auth/, specs/payments/).

• changes/ - Запропоновані модифікації. Кожна зміна отримує власну папку з усіма пов'язаними артефактами. Коли зміна завершена, її специфікації зливаються з основною директорією specs/.

Розуміння артефактів

Кожна папка зміни містить артефакти, які керують роботою:

Артефакт	Призначення
proposal.md	"Чому" та "що" - фіксує намір, обсяг та підхід
specs/	Дельта-специфікації, що показують ДОДАНІ/ЗМІНЕНІ/ВИДАЛЕНІ вимоги
design.md	"Як" - технічний підхід та архітектурні рішення
tasks.md	Чек-лист реалізації з позначками

Артефакти будуються один на одному:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            оновлюйте, коли навчаєтесь

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

Як працюють дельта-специфікації

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

Формат

Дельта-специфікації використовують секції для вказівки типу зміни:

# Дельта для Auth

## ДОДАНІ вимоги

### Вимога: Двофакторна автентифікація
Система ПОВИННА вимагати другий фактор під час входу.

#### Сценарій: Потрібен OTP
- ДАНО користувач з увімкненим 2FA
- КОЛИ користувач надає дійсні облікові дані
- ТОДІ відображається запит на OTP

## ЗМІНЕНІ вимоги

### Вимога: Час бездіяльності сесії
Система ПОВИННА завершувати сесії через 30 хвилин бездіяльності.
(Раніше: 60 хвилин)

#### Сценарій: Час бездіяльності
- ДАНО автентифікована сесія
- КОЛИ проходить 30 хвилин без активності
- ТОДІ сесія стає недійсною

## ВИДАЛЕНІ вимоги

### Вимога: Запам'ятати мене
(Застаріло на користь 2FA)

Що відбувається при архівації

Коли ви архівуєте зміну:

1. ДОДАНІ вимоги додаються до основної специфікації
2. ЗМІНЕНІ вимоги замінюють існуючу версію
3. ВИДАЛЕНІ вимоги видаляються з основної специфікації

Папка зміни переміщується до openspec/changes/archive/ для аудиту історії.

Приклад: Ваша перша зміна

Розглянемо додавання темного режиму до додатку.

1. Початок зміни (Стандартний)

Ви: /opsx:propose add-dark-mode

AI:  Створено openspec/changes/add-dark-mode/
     ✓ proposal.md — чому ми це робимо, що змінюється
     ✓ specs/       — вимоги та сценарії
     ✓ design.md    — технічний підхід
     ✓ tasks.md     — чек-лист реалізації
     Готово до реалізації!

Якщо ви увімкнули розширений профіль робочого процесу, ви також можете зробити це двома кроками: /opsx:new, а потім /opsx:ff (або /opsx:continue поступово).

2. Що створюється

proposal.md - Фіксує намір:

# Пропозиція: Додати темний режим

## Намір
Користувачі просили опцію темного режиму для зменшення напруги очей
під час використання вночі.

## Обсяг
- Додати перемикач теми в налаштуваннях
- Підтримувати визначення системних уподобань
- Зберігати уподобання в localStorage

## Підхід
Використовувати CSS-кастомні властивості для тематизації з контекстом React
для керування станом.

specs/ui/spec.md - Дельта, що показує нові вимоги:

# Дельта для UI

## ДОДАНІ вимоги

### Вимога: Вибір теми
Система ПОВИННА дозволяти користувачам обирати між світлою та темною темами.

#### Сценарій: Ручний перемикач
- ДАНО користувач на будь-якій сторінці
- КОЛИ користувач натискає перемикач теми
- ТОДІ тема змінюється негайно
- І уподобання зберігається між сесіями

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

tasks.md - Чек-лист реалізації:

# Завдання

## 1. Інфраструктура тем
- [ ] 1.1 Створити ThemeContext зі станом світлої/темної теми
- [ ] 1.2 Додати CSS-кастомні властивості для кольорів
- [ ] 1.3 Реалізувати збереження в localStorage

## 2. UI-компоненти
- [ ] 2.1 Створити компонент ThemeToggle
- [ ] 2.2 Додати перемикач на сторінку налаштувань
- [ ] 2.3 Оновити Header, додавши швидкий перемикач

## 3. Стилізація
- [ ] 3.1 Визначити палітру кольорів для темної теми
- [ ] 3.2 Оновити компоненти для використання CSS-змінних

3. Реалізація

Ви: /opsx:apply

AI:  Працюю над завданнями...
     ✓ 1.1 Створено ThemeContext зі станом світлої/темної теми
     ✓ 1.2 Додано CSS-кастомні властивості до globals.css
     ✓ 1.3 Реалізовано збереження в localStorage
     ✓ 2.1 Створено компонент ThemeToggle
     ...
     Усі завдання завершено!

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

4. Архівація

Ви: /opsx:archive

AI:  Архівую add-dark-mode...
     ✓ Злито специфікації в openspec/specs/ui/spec.md
     ✓ Переміщено до openspec/changes/archive/2025-01-24-add-dark-mode/
     Готово! Готовий до наступної функції.

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

Перевірка та огляд

Використовуйте CLI для перевірки ваших змін:

# Показати активні зміни
openspec list

# Переглянути деталі зміни
openspec show add-dark-mode

# Перевірити форматування специфікації
openspec validate add-dark-mode

# Інтерактивна панель
openspec view

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

• Робочі процеси - Поширені патерни та коли використовувати кожну команду
• Команди - Повна довідка для всіх слеш-команд
• Концепції - Глибше розуміння специфікацій, змін та схем
• Налаштування - Налаштуйте OpenSpec під свій спосіб роботи