Основные понятия

В этом руководстве объясняются основные идеи OpenSpec и их взаимосвязь. Практические сведения см. в разделах Начало работы и Рабочие процессы.

Философия

В основе OpenSpec лежат четыре принципа:

гибкость, а не жёсткость       — нет обязательных этапов, работайте над тем, что нужно
итерации, а не каскадная модель — узнавайте новое в ходе работы и уточняйте решения
простота, а не сложность       — лёгкая настройка, минимум формальностей
приоритет существующим системам — работает с готовыми кодовыми базами, а не только с новыми

Почему эти принципы важны

Гибкость, а не жёсткость. Традиционные системы спецификаций привязывают вас к этапам: сначала планирование, затем реализация, после чего работа считается завершённой. OpenSpec гибче — артефакты можно создавать в любом порядке, подходящем для вашей задачи.

Итерации, а не каскадная модель. Требования меняются, понимание задачи углубляется. Подход, казавшийся удачным вначале, может не подойти после изучения кодовой базы. OpenSpec учитывает эту реальность.

Простота, а не сложность. Некоторые платформы для спецификаций требуют длительной настройки, жёстких форматов и тяжеловесных процессов. OpenSpec не мешает работе: инициализация занимает секунды, после неё можно сразу начинать, а настройка нужна только при необходимости.

Приоритет существующим системам. Большинство задач разработки — это не создание с нуля, а изменение работающих систем. Дельта-подход OpenSpec упрощает описание изменений существующего поведения, а не только новых систем.

Общая картина

OpenSpec разделяет работу на две основные области:

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │ Источник истины     │◄─────│ Предлагаемые изменения        │   │
│   │ Текущее поведение   │ слияние│ Одно изменение = одна папка  │   │
│   │ вашей системы       │      │ Артефакты и дельты            │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Спецификации — источник истины; они описывают текущее поведение системы.

Изменения — предлагаемые модификации; они хранятся в отдельных папках до момента слияния.

Такое разделение принципиально важно. Можно параллельно работать над несколькими изменениями, не создавая конфликтов, и проверить изменение до того, как оно затронет основные спецификации. При архивации его дельты аккуратно объединяются с источником истины.

Спецификации

Спецификации описывают поведение системы с помощью структурированных требований и сценариев.

Структура

openspec/specs/
├── auth/
│   └── spec.md           # Поведение аутентификации
├── payments/
│   └── spec.md           # Обработка платежей
├── notifications/
│   └── spec.md           # Система уведомлений
└── ui/
    └── spec.md           # Поведение интерфейса и темы

Группируйте спецификации по областям — логическим частям системы. Распространённые варианты:

• По функциональной области: auth/, payments/, search/
• По компоненту: api/, frontend/, workers/
• По ограниченному контексту: ordering/, fulfillment/, inventory/

Формат спецификации

Спецификация содержит требования, а каждое требование — сценарии:

# Спецификация аутентификации

## Purpose
Аутентификация и управление сеансами приложения.

## Requirements

### Требование: аутентификация пользователя
После успешного входа система SHALL выдавать токен JWT.

#### Сценарий: действительные учётные данные
- GIVEN: пользователь вводит действительные учётные данные
- WHEN: пользователь отправляет форму входа
- THEN: возвращается токен JWT
- AND: пользователь перенаправляется на панель управления

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

### Требование: завершение сеанса
Система MUST завершать сеансы после 30 минут бездействия.

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

Основные элементы:

Элемент	Назначение
## Purpose	Краткое описание области этой спецификации
### Requirement:	Конкретное поведение, обязательное для системы
#### Scenario:	Конкретный пример выполнения требования
SHALL/MUST/SHOULD	Ключевые слова RFC 2119, задающие обязательность требования

Почему спецификации устроены именно так

Требования описывают «что» — что должна делать система, без указания реализации.

Сценарии описывают «когда» — это конкретные, проверяемые примеры. Хорошие сценарии:

• можно проверить (для них можно написать автоматизированный тест);
• охватывают успешное выполнение и граничные случаи;
• используют формат Given/When/Then или похожую структуру.

Ключевые слова RFC 2119 (SHALL, MUST, SHOULD, MAY) передают степень обязательности:

• MUST/SHALL — безусловное требование;
• SHOULD — рекомендация, допускающая исключения;
• MAY — необязательное условие.

Чем является спецификация (и чем не является)

Спецификация — это контракт поведения, а не план реализации.

Что следует включать в спецификацию:

• наблюдаемое поведение, от которого зависят пользователи и последующие системы;
• входные и выходные данные, а также условия ошибок;
• внешние ограничения (безопасность, конфиденциальность, надёжность, совместимость);
• сценарии, которые можно протестировать или явно проверить.

Чего следует избегать в спецификациях:

• названий внутренних классов и функций;
• выбора библиотек и фреймворков;
• пошаговых деталей реализации;
• подробных планов выполнения (они относятся к design.md или tasks.md).

Быстрая проверка:

• если реализацию можно изменить, не меняя внешне наблюдаемого поведения, скорее всего, ей не место в спецификации.

Лёгкий подход: постепенное повышение строгости

OpenSpec помогает избежать бюрократии. Используйте минимальный уровень строгости, который всё ещё позволяет проверить изменение.

Облегчённая спецификация (по умолчанию):

• краткие требования, ориентированные на поведение;
• ясная область работ и явно исключённые задачи;
• несколько конкретных критериев приёмки.

Полная спецификация (для более рискованных изменений):

• изменения между командами или репозиториями;
• изменения API/контрактов, миграции, вопросы безопасности и конфиденциальности;
• изменения, в которых неоднозначность может привести к дорогостоящей переработке.

Большинство изменений должны оставаться в облегчённом режиме.

Совместная работа человека и агента

Во многих командах люди исследуют задачу, а агенты составляют черновики артефактов. Рекомендуемый цикл:

1. Человек задаёт цель, контекст и ограничения.
2. Агент преобразует их в требования и сценарии, ориентированные на поведение.
3. Агент описывает детали реализации в design.md и tasks.md, а не в spec.md.
4. Перед реализацией проверка подтверждает корректность структуры и ясность.

Так спецификации остаются понятными людям и последовательными для агентов.

Изменения

Изменение — это предлагаемая модификация системы, оформленная в отдельную папку со всем необходимым для понимания и реализации.

Структура изменения

openspec/changes/add-dark-mode/
├── proposal.md           # Зачем и что
├── design.md             # Как (технический подход)
├── tasks.md              # Контрольный список реализации
├── .openspec.yaml        # Метаданные изменения (необязательно): schema, created, skip_specs, retire_capabilities
└── specs/                # Дельта-спецификации
    └── ui/
        └── spec.md       # Что меняется в ui/spec.md

Каждое изменение самодостаточно. Оно включает:

• Артефакты — документы, описывающие цель, проектное решение и задачи;
• Дельта-спецификации — спецификации того, что добавляется, меняется или удаляется;
• Метаданные — необязательная конфигурация конкретного изменения.

Почему изменения оформляются в папки

Оформление изменения в виде папки имеет несколько преимуществ:

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

2. Параллельная работа. Несколько изменений могут существовать одновременно и не конфликтовать. Работайте над add-dark-mode, пока выполняется fix-auth-bug.

3. Понятная история. При архивации изменения перемещаются в changes/archive/ со всем контекстом. Позже можно выяснить не только, что изменилось, но и почему.

4. Удобство проверки. Папку изменения легко проверить: откройте её, прочитайте предложение, изучите проектное решение и дельты спецификаций.

Артефакты

Артефакты — документы внутри изменения, направляющие работу.

Последовательность артефактов

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   зачем         что            как          шаги
 + область     меняется       подход       работы

Артефакты создаются один на основе другого. Каждый предоставляет контекст для следующего.

Artifact Types

Предложение (proposal.md)

В предложении в общих чертах описываются цель, область работ и подход.

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

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

## Область работ
Входит в область:
- переключатель темы в настройках;
- определение системных предпочтений;
- сохранение предпочтения в localStorage.

Не входит в область:
- пользовательские цветовые темы (будущая работа);
- переопределение темы для отдельных страниц.

## Подход
Использовать пользовательские свойства CSS для тем и контекст React
для управления состоянием. При первой загрузке определять системные
предпочтения и разрешать ручное переопределение.

Когда следует обновить предложение:

• меняется область работ (сужается или расширяется);
• уточняется цель (проблема стала понятнее);
• существенно меняется подход.

Спецификации (дельта-спецификации в specs/)

Дельта-спецификации описывают, что меняется по сравнению с текущими спецификациями. См. раздел Дельта-спецификации ниже.

Проектное решение (design.md)

Проектное решение описывает технический подход и архитектурные решения.

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

## Технический подход
Состояние темы управляется через React Context, чтобы избежать передачи
свойств через промежуточные компоненты. Пользовательские свойства CSS
позволяют переключать тему во время выполнения без переключения классов.

## Архитектурные решения

### Решение: Context вместо Redux
Для состояния темы используется React Context, поскольку:
- состояние простое и двоичное (светлая/тёмная тема);
- сложных переходов между состояниями нет;
- не нужно добавлять зависимость Redux.

### Решение: пользовательские свойства CSS
Используются переменные CSS вместо CSS-in-JS, потому что:
- они работают с существующими таблицами стилей;
- не добавляют накладных расходов во время выполнения;
- это встроенный в браузер механизм.

## Поток данных
```
ThemeProvider (контекст)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
Переменные CSS (применяются к :root)
```

## Изменения файлов
- `src/contexts/ThemeContext.tsx` (новый файл)
- `src/components/ThemeToggle.tsx` (новый файл)
- `src/styles/globals.css` (изменён)

Когда следует обновить проектное решение:

• при реализации выяснилось, что подход не сработает;
• найдено более удачное решение;
• изменились зависимости или ограничения.

Задачи (tasks.md)

Задачи — это контрольный список реализации с конкретными шагами и флажками.

# Задачи

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

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

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

Рекомендации по задачам:

• объединяйте связанные задачи в группы под заголовками;
• используйте иерархическую нумерацию (1.1, 1.2 и т. д.);
• делайте задачи достаточно небольшими, чтобы выполнить их за один сеанс;
• указывайте способ проверки каждой задачи (тест, команда или наблюдаемый результат);
• добавляйте тесты и документацию для каждой группы задач в саму эту группу, а не в заключительную группу «наверстать упущенное»;
• отмечайте задачи по мере выполнения.

Дельта-спецификации

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

Формат

# Дельта для аутентификации

## ADDED Requirements

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

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

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

## MODIFIED Requirements

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

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

## REMOVED Requirements

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

Разделы дельты

Раздел	Значение	Действие при архивации
## ADDED Requirements	Новое поведение	Добавляется в основную спецификацию
## MODIFIED Requirements	Изменённое поведение	Заменяет существующее требование
## REMOVED Requirements	Устаревшее поведение	Удаляется из основной спецификации; удаление последнего требования выводит возможность из эксплуатации и удаляет её файл спецификации, если изменение объявляет retire_capabilities: true
## Purpose	Назначение новой возможности	Используется как Purpose создаваемой основной спецификации; игнорируется, если спецификация уже существует

Почему используются дельты, а не полные спецификации

Ясность. Дельта точно показывает, что меняется. Читая полную спецификацию, вам пришлось бы самостоятельно сравнивать её с текущей версией.

Предотвращение конфликтов. Два изменения могут затрагивать один файл спецификации, не конфликтуя, если меняют разные требования.

Эффективность проверки. Проверяющие видят изменение, а не неизменившийся контекст, и могут сосредоточиться на важном.

Подходит для существующих систем. Большинство задач меняют уже существующее поведение. Дельты позволяют считать такие изменения основным сценарием, а не исключением.

Схемы

Схемы определяют типы артефактов и их зависимости в рабочем процессе.

Как работают схемы

openspec/schemas/spec-driven/schema.yaml

name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # Нет зависимостей, создаётся первым

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # Перед созданием требуется proposal

  - id: design
    generates: design.md
    requires: [proposal]      # Можно создать параллельно со specs

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # Сначала нужны и specs, и design

Артефакты образуют граф зависимостей:

                    proposal
                   (корневой узел)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (требуется:                  (требуется:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (требуется:
                specs, design)

Зависимости — опоры, а не обязательные этапы. Они показывают, что можно создать, а не что обязательно создавать следующим. Если проектное решение не требуется, этап design можно пропустить. Спецификации можно создать до или после design — и те и другие зависят только от proposal.

Встроенные схемы

spec-driven (по умолчанию)

Стандартный рабочий процесс разработки на основе спецификаций:

proposal → specs → design → tasks → implement

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

Пользовательские схемы

Создавайте пользовательские схемы для рабочего процесса своей команды:

# Создать с нуля
openspec schema init research-first

# Или скопировать существующую
openspec schema fork spec-driven research-first

Пример пользовательской схемы:

openspec/schemas/research-first/schema.yaml

name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # Сначала исследование

  - id: proposal
    generates: proposal.md
    requires: [research]   # Предложение учитывает результаты исследования

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # Пропустить specs/design и сразу перейти к задачам

Подробные сведения о создании и использовании пользовательских схем см. в разделе Настройка.

Архивация

Архивация завершает изменение: его дельта-спецификации объединяются с основными, а само изменение сохраняется в истории.

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

До архивации:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ объединение
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


После архивации:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # Теперь включает требования для двухфакторной аутентификации
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # Сохранено в истории
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

Процесс архивации

1. Объединение дельт. Каждый раздел дельта-спецификации (ADDED/MODIFIED/REMOVED) применяется к соответствующей основной спецификации.

2. Перемещение в архив. Папка изменения переносится в changes/archive/ с префиксом даты для хронологической сортировки.

3. Сохранение контекста. Все артефакты сохраняются в архиве без изменений. В любой момент можно узнать, почему было сделано изменение.

Почему архивация важна

Чистое состояние. В списке активных изменений (changes/) отображается только незавершённая работа. Завершённые изменения перемещаются в архив.

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

Развитие спецификаций. Спецификации естественным образом расширяются по мере архивации изменений. Каждая архивация объединяет дельты, постепенно создавая полную спецификацию.

Как всё взаимосвязано

┌──────────────────────────────────────────────────────────────────────────────┐
│                         РАБОЧИЙ ПРОЦЕСС OPENSPEC                              │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. НАЧНИТЕ    │  /opsx:propose (core) или /opsx:new (expanded)          │
│   │     ИЗМЕНЕНИЕ  │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. СОЗДАЙТЕ   │  /opsx:ff или /opsx:continue (расширенный процесс)      │
│   │     АРТЕФАКТЫ  │  Создаёт proposal → specs → design → tasks              │
│   │                │  (с учётом зависимостей схемы)                          │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. ВЫПОЛНИТЕ  │  /opsx:apply                                            │
│   │     ЗАДАЧИ     │  Выполняйте задачи и отмечайте их                       │
│   │                │◄──── Уточняйте артефакты по мере работы                 │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. ПРОВЕРЬТЕ  │  /opsx:verify (необязательно)                           │
│   │     РЕЗУЛЬТАТ  │  Проверьте соответствие реализации спецификациям        │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. АРХИВИРУЙТЕ│────►│  Дельты объединяются с основными спецификациями│  │
│   │     ИЗМЕНЕНИЕ  │     │  Папка изменения перемещается в archive/      │    │
│   └────────────────┘     │  Спецификации обновляются                    │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Полезный цикл:

1. Спецификации описывают текущее поведение.
2. Изменения предлагают модификации в виде дельт.
3. Реализация воплощает изменения.
4. Архивация объединяет дельты со спецификациями.
5. Спецификации теперь описывают новое поведение.
6. Следующее изменение опирается на обновлённые спецификации.

Глоссарий

Термин	Определение
Артефакт	Документ внутри изменения (предложение, проектное решение, задачи или дельта-спецификации)
Архивация	Завершение изменения и объединение его дельт с основными спецификациями
Изменение	Предлагаемая модификация системы, оформленная в папку с артефактами
Дельта-спецификация	Спецификация изменений (ADDED/MODIFIED/REMOVED) относительно текущих спецификаций
Область	Логическая группа спецификаций (например, auth/, payments/)
Требование	Конкретное поведение, которое должна обеспечивать система
Сценарий	Конкретный пример выполнения требования, обычно в формате Given/When/Then
Схема	Определение типов артефактов и их зависимостей
Спецификация	Описание поведения системы, содержащее требования и сценарии
Источник истины	Каталог openspec/specs/, содержащий актуальное согласованное описание поведения

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

• Начало работы — первые практические шаги
• Рабочие процессы — распространённые шаблоны и их применение
• Команды — полный справочник команд
• Настройка — создание пользовательских схем и конфигурация проекта