Начало работы

Это руководство объясняет, как работает OpenSpec после его установки и инициализации. Инструкции по установке см. в основном README.

Как это работает

OpenSpec помогает вам и вашему ИИ-ассистенту для программирования договориться о том, что нужно создать, до написания какого-либо кода.

Путь по умолчанию (профиль core):

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

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

/opsx:new ──► /opsx:ff или /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

ИИ:  Создана 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

ИИ:  Работаю над задачами...
     ✓ 1.1 Создан ThemeContext со состоянием светлой/темной темы
     ✓ 1.2 Добавлены пользовательские свойства CSS в globals.css
     ✓ 1.3 Реализовано сохранение в localStorage
     ✓ 2.1 Создан компонент ThemeToggle
     ...
     Все задачи выполнены!

В процессе реализации, если вы обнаружите, что дизайн нуждается в корректировке, просто обновите артефакт и продолжайте.

4. Архивация

Вы: /opsx:archive

ИИ:  Архивирую 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 под себя