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

Это руководство объясняет, как работает OpenSpec после того, как вы его установили и инициализировали. Инструкции по установке см. в основном README или в руководстве по установке. Вы новичок в этом наборе документации? Домашняя страница документации обо всем расскажет.

Где я вводю эти команды? В двух местах, и смешивание их — самая частая ошибка новичков.

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

Отдельного "интерактивного режима" для старта нет. Вы просто вводите слэш-команду в чат, и ваш ассистент продолжает работу. Полное объяснение: Как работают команды.

Ваши первые пять минут

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

TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (опционально: подумайте сначала)
AI CHAT      /opsx:propose add-dark-mode      (AI составляет план; вы его просматриваете)
AI CHAT      /opsx:apply                      (AI строит это)
AI CHAT      /opsx:archive                    (спецификации обновлены, изменения заархивированы)

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

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

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

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/	Дельта-спецификации, показывающие требования, которые были ДОБАВЛЕНЫ/ИЗМЕНЕНЫ/УДАЛЕНЫ
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

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 — Дельта, показывающая новые требования:

# Дельта для UI

## Требования, которые были ДОБАВЛЕНЫ

### Требование: Выбор темы
Система ДОЛЖНА позволять пользователям выбирать между светлой и темной темами.

#### Сценарий: Ручной переключатель
- ПРИМЕСКИ пользователь на любой странице
- КОГДА пользователь нажимает переключатель темы
- ТОгда тема немедленно меняется
- И предпочтение сохраняется в сессиях

#### Сценарий: Системные предпочтения
- ПРИМЕСКИ пользователь без сохраненного предпочтения
- КОГДА приложение загружается
- ТОгда используется предпочтительная цветовая схема системы

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

# Задачи

## 1. Инфраструктура темы
- [ ] 1.1 Создать ThemeContext с состоянием light/dark
- [ ] 1.2 Добавить пользовательские свойства CSS для цветов
- [ ] 1.3 Реализовать сохранение в localStorage

## 2. Компоненты UI
- [ ] 2.1 Создать компонент ThemeToggle
- [ ] 2.2 Добавить переключатель на страницу настроек
- [ ] 2.3 Обновить заголовок, чтобы включить быстрый переключатель

## 3. Стилизация
- [ ] 3.1 Определить цветовую палитру темной темы
- [ ] 3.2 Обновить компоненты для использования CSS переменных

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

Вы: /opsx:apply

AI:  Работаем над задачами...
     ✓ 1.1 Создан ThemeContext с состоянием light/dark
     ✓ 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

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

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