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

Цей посібник пояснює, як працює 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 or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Стандартний глобальний профіль — core, який містить propose, explore, apply, update, 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 Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 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 — фіксує намір:

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md — дельта з новими вимогами:

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md — контрольний список реалізації:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

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

Ви: /opsx:apply

AI:  Виконую завдання...
     ✓ 1.1 Створено ThemeContext зі станом світло/темно
     ✓ 1.2 Додано CSS custom properties до 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

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

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