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

В этом руководстве объясняется, как работает OpenSpec после установки и инициализации. Инструкции по установке см. в основном README или в руководстве по установке. Впервые открыли эту документацию? На главной странице документации описаны все разделы.

Где вводить эти команды? Есть два места, и путаница между ними — самая частая ошибка новичков.

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

Не нужно запускать отдельный «интерактивный режим». Просто введите slash-команду в чате, а дальше ассистент сделает всё сам. Подробное объяснение: Как работают команды.

Первые пять минут

Весь цикл с указанием места выполнения каждого шага:

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

Для настройки нужны два шага в терминале, а затем вся работа ведётся в чате. Далее в руководстве объясняется, что делает каждый шаг и что вы увидите.

Не хотите самостоятельно выполнять команды в терминале? Вставьте инструкцию по настройке в чат ассистента. Он выполнит обе команды и сообщит, что было создано.

Ещё не решили, что разрабатывать? Начните с /opsx:explore. Это партнёр для обдумывания без обязательств: он изучает кодовую базу, сравнивает варианты и превращает расплывчатую идею в конкретный план ещё до написания кода. Когда всё прояснится, он передаст работу команде /opsx:propose. Это лучшая привычка при работе с ИИ, который иначе может уверенно построить не то, что нужно. См. руководство по исследованию.

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

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

Быстрый путь по умолчанию (профиль 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, 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. Они показывают, что меняется относительно текущих спецификаций.

Формат

В дельта-спецификациях тип изменения указывается в заголовке раздела:

# Дельта для авторизации

## ADDED Requirements

### Требование: двухфакторная аутентификация
Система MUST запрашивать второй фактор при входе.

#### Сценарий: запрос одноразового пароля
- GIVEN: у пользователя включена двухфакторная аутентификация
- WHEN: пользователь отправляет действительные учётные данные
- THEN: отображается запрос одноразового пароля

## MODIFIED Requirements

### Требование: время ожидания сеанса
Система SHALL завершать сеансы после 30 минут бездействия.
(Ранее: 60 минут)

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

## REMOVED Requirements

### Требование: запоминание входа
(Устарело и заменено двухфакторной аутентификацией.)

Что происходит при архивации

При архивации изменения:

1. требования ADDED добавляются в основную спецификацию;
2. требования MODIFIED заменяют существующую версию;
3. требования REMOVED удаляются из основной спецификации.

Папка изменения перемещается в 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 — фиксирует цель:

# Предложение: добавить тёмную тему

## Intent
Пользователи попросили добавить тёмную тему, чтобы уменьшить
нагрузку на глаза при использовании приложения ночью.

## Область работ
- Добавить переключатель темы в настройки
- Поддержать определение системных предпочтений
- Сохранять предпочтение в localStorage

## Approach
Использовать пользовательские свойства CSS для тем и контекст React
для управления состоянием.

specs/ui/spec.md — дельта с новыми требованиями:

# Дельта для интерфейса

## ADDED Requirements

### Требование: выбор темы
Система 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

ИИ:  Выполняю задачи...
     ✓ 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

Следующие шаги

• Сначала исследуйте — используйте /opsx:explore, чтобы обдумать идею до принятия обязательств
• Проверка изменения — что проверить в плане ИИ до написания кода
• Как писать хорошие спецификации — как выглядят хорошие требования и сценарии
• Использование OpenSpec в существующем проекте — начало работы с большой кодовой базой
• Редактирование и доработка изменения — обновление артефактов, возврат к предыдущим шагам и согласование ручных правок
• Основные понятия вкратце — вся концептуальная модель на одной странице
• Примеры и рецепты — реальные изменения от начала до конца
• Рабочие процессы — типичные схемы работы и применение команд
• Команды — полный справочник slash-команд
• Основные понятия — подробное описание спецификаций, изменений и схем
• Настройка — настройте OpenSpec под себя
• Хранилища — планируйте работу нескольких репозиториев и команд в отдельном репозитории (бета-версия)
• FAQ и Устранение неполадок — помощь, если возникли трудности