OpenSpec

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

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

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

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

Отдельного «интерактивного режима» для запуска не существует. Вы просто вводите команду с косой чертой в чате, и ассистент берёт процесс на себя. Полное объяснение: Как работают команды.

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

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

text
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 CHAT      /opsx:apply                      (ИИ реализует)
AI CHAT      /opsx:archive                    (спецификации обновлены, изменения заархивированы)

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

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

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

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

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

Основной быстрый путь (профиль core):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (необязательно)

Начните с /opsx:explore, когда определяетесь с тем, что делать, или сразу переходите к /opsx:propose, если вы уже знаете. Explore входит в профиль по умолчанию, поэтому он всегда доступен, когда вам нужен.

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

text
/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/Дельта-спецификации, показывающие ДОБАВЛЁННЫЕ/ИЗМЕНЁННЫЕ/УДАЛЁННЫЕ требования
design.md«Как» — технический подход и архитектурные решения
tasks.mdЧек-лист реализации с галочками

Артефакты строятся друг на друге:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            обновляйте по мере обучения

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

Как работают дельта-спецификации ​

Дельта-спецификации — ключевое понятие в OpenSpec. Они показывают, что меняется относительно ваших текущих спецификаций.

Формат ​

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

markdown
# 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. Запуск изменения (по умолчанию) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Если вы включили профиль расширенного рабочего процесса, вы также можете сделать это в два шага: /opsx:new, затем /opsx:ff (или /opsx:continue по частям).

2. Что создаётся ​

proposal.md — фиксирует намерение:

markdown
# 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 — дельта с новыми требованиями:

markdown
# 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 — чек-лист реализации:

markdown
# 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. Реализация ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

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

4. Архивация ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

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

Проверка и ревью ​

Используйте CLI для отслеживания изменений:

bash
# Список активных изменений
openspec list

# Просмотр деталей изменения
openspec show add-dark-mode

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

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

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