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

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

Де вводити ці команди? Є два місця, і їх плутання є найпоширенішою помилкою на початку роботи.

• Команди openspec ... (наприклад, openspec init) запускаються у вашому терміналі.
• Команди /opsx:... (наприклад, /opsx:propose) запускаються у чаті вашого AI-асистента, в тому самому полі, де ви просите його написати код.

Окремої «інтерактивного режиму» для запуску не потрібно. Просто введіть слеш-команду в чаті, і ваш асистент продовжить роботу за вас. Повне пояснення: Як працюють команди.

Ваші перші п'ять хвилин

Весь цикл роботи, кожен крок позначено місцем його виконання:

ТЕРМІНАЛ   $ npm install -g @fission-ai/openspec@latest
ТЕРМІНАЛ   $ cd your-project && openspec init
AI ЧАТ      /opsx:explore                    (необов'язково: спочатку обдумайте ідею)
AI ЧАТ      /opsx:propose add-dark-mode      (AI складає план; ви його перевіряєте)
AI ЧАТ      /opsx:apply                      (AI реалізує його)
AI ЧАТ      /opsx:archive                    (специфікації оновлено, зміну заархівовано)

Два кроки в терміналі для налаштування, після чого ви працюєте переважно в чаті. Решта цього посібника розбирає, що робить кожен крок і що ви побачите.

Ще не визначилися, що саме будувати? Почніть з /opsx:explore. Це безризиковий помічник для міркувань, який аналізує вашу кодову базу, оцінює варіанти та перетворює нечітку ідею на конкретний план, ще до появи будь-яких артефактів або коду. Коли картина стане зрозумілою, він передає роботу /opsx:propose. Це найкраща звичка при роботі з AI, який інакше впевнено збудує не те, що потрібно. Дивіться посібник з Explore.

Як це працює

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

Шлях за замовчуванням (профіль core):

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (необов'язково)

Почніть з /opsx:explore, якщо ви ще визначаєтеся, що робити, або перейдіть безпосередньо до /opsx:propose, якщо ви вже маєте чітке уявлення. Команда Explore входить до профілю за замовчуванням, тому вона завжди доступна, коли ви її потребуєте.

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

/opsx:new ──► /opsx:ff або /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Глобальний профіль за замовчуванням — core, він включає команди propose, explore, apply, sync та 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/	Дельта-специфікації, що показують ADDED/MODIFIED/REMOVED вимоги
design.md	«Як» — технічний підхід та рішення з архітектури
tasks.md	Чекліст реалізації з прапорцями для відмітки виконання

Артефакти побудовані один на одному:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            оновлюйте по мірі отримання нових знань

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

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

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

Формат

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

# Delta for Auth

## ADDED Вимоги

### Вимога: Two-Factor Authentication
Система MUST вимагає другий фактор під час входу.

#### Сценарій: Потрібен OTP
- GIVEN користувач із увімкненою 2FA
- WHEN користувач надсилає дійсні облікові дані
- THEN подається запит на OTP

## MODIFIED Вимоги

### Вимога: Session Timeout
Система SHALL завершує сесії після 30 хвилин бездіяльності.
(Раніше: 60 хвилин)

#### Сценарій: Таймаут бездіяльності
- GIVEN автентифікована сесія
- WHEN минає 30 хвилин без активності
- THEN сесія скасовується

## REMOVED Вимоги

### Вимога: Remember Me
(Застарів на користь 2FA)

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

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

1. Вимоги ADDED додаються до основної специфікації
2. Вимоги MODIFIED замінюють існуючу версію
3. Вимоги REMOVED видаляються з основної специфікації

Папка зміною переміщується до 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 — Дельта, що показує нові вимоги:

# Delta for UI

## ADDED Вимоги

### Вимога: Theme Selection
Система SHALL дозволяє користувачам вибирати між світлою та темною темами.

#### Сценарій: Ручне перемикання
- GIVEN користувач на будь-якій сторінці
- WHEN користувач натискає перемикач теми
- THEN тема змінюється миттєво
- AND уподобання зберігаються між сесіями

#### Сценарій: Системні уподобання
- GIVEN користувач без збережених уподобань
- WHEN завантажується додаток
- THEN використовується бажана кольорова схема системи

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

# Завдання

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

## 2. Компоненти інтерфейсу
- [ ] 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

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

• Спочатку Explore — Використовуйте /opsx:explore, щоб обдумати ідею, перш ніж її реалізовувати
• Огляд зміни — Що перевіряти в плані, складеному AI, до написання будь-якого коду
• Написання якісних специфікацій — Як виглядають якісні вимоги та сценарії
• Використання OpenSpec у існуючому проекті — Робота з великою brownfield кодовою базою
• Редагування та ітерації зміною — Оновлення артефактів, повернення до попередніх кроків, узгодження ручних редагувань
• Ключові концепції за одним переглядом — Уся ментальна модель на одній сторінці
• Приклади та рецепти — Реальні зміни від початку до кінця
• Робочі процеси — Типові патерни та випадки використання кожної команди
• Команди — Повний довідник з усіх слеш-команд
• Концепції — Глибоке розуміння специфікацій, змін та схем
• Налаштування — Налаштуйте OpenSpec під себе
• Сховища — Планування, що охоплює кілька репозиторіїв або команд? Зберігайте його в окремому репозиторії (бета)
• Часті запитання та Усунення несправностей — Коли ви застрягли