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

Цей гайд пояснює, як працює OpenSpec після того, як ви його встановили та ініціалізували. Для інструкцій з встановлення дивіться main README або Installation guide. Новачок у цій документації? documentation home відображає все.

Де я вводжу ці команди? У двох місцях, і змішування їх — це найпоширеніша початкова помилка.

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

Немає окремого "інтерактивного режиму" для старту. Ви просто вводите команду зі слешем у чат, і ваш асистент продовжує роботу. Повна пояснення: How Commands Work.

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

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

TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (optional: think it through first)
AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
AI CHAT      /opsx:apply                      (AI builds it)
AI CHAT      /opsx:archive                    (specs updated, change filed away)

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

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

Як це працює

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

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

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (optional)

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

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

/opsx:new ──► /opsx:ff or /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
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            оновлюйте, вивчаючи

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

Як працюють Дельта-специфікації (Delta Specs)

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

Формат

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

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
Система ПОВИННА вимагати другий фактор під час входу.

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

## MODIFIED Requirements

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

#### Scenario: Idle timeout
- GIVEN автентифікована сесія
- WHEN минуло 30 хвилин без активності
- THEN сесія анулюється

## REMOVED Requirements

### Requirement: Remember Me
(Застаріло на користь 2FA)

Що відбувається при архівуванні (Archive)

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

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

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

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

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

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

You: /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 — Фіксує намір:

# Proposal: Add Dark Mode

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

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

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

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

# Delta for UI

## ADDED Requirements

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

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

#### Scenario: System preference
- GIVEN користувач без збереженої переваги
- WHEN застосунок завантажується
- THEN використовується системна схема кольорів

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

# Tasks

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

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

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

3. Реалізація (Implement)

You: /opsx:apply

AI:  Виконую завдання...
     ✓ 1.1 Створено ThemeContext зі станом light/dark
     ✓ 1.2 Додано CSS custom properties до globals.css
     ✓ 1.3 Реалізовано збереження у localStorage
     ✓ 2.1 Створено компонент ThemeToggle
     ...
     Усі завдання виконані!

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

4. Архівування (Archive)

You: /opsx:archive

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

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

Перевірка та огляд (Verifying and Reviewing)

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

# Список активних змін
openspec list

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

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

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

Наступні кроки (Next Steps)

• Explore First - Використовуйте /opsx:explore, щоб продумати ідею перед комітом
• Using OpenSpec in an Existing Project - Почніть з великої кодової бази brownfield
• Editing & Iterating on a Change - Оновлення артефактів, повернення назад, узгодження ручних правок
• Core Concepts at a Glance - Вся ментальна модель на одній сторінці
• Examples & Recipes - Реальні зміни від початку до кінця
• Workflows - Поширені патерни та коли використовувати кожну команду
• Commands - Повний посібник з усіх слеш-команд
• Concepts - Глибше розуміння специфікацій, змін і схем
• Customization - Зробіть OpenSpec під себе
• Stores - Планування, що охоплює репозиторії або команди? Залиште це у власному репо (бета)
• FAQ та Troubleshooting - Коли ви застрягли