Концепции

Это руководство объясняет основные идеи, лежащие в основе OpenSpec, и то, как они сочетаются друг с другом. Для практического использования см. Начало работы и Рабочие процессы.

Философия

OpenSpec построен на четырех принципах:

fluid not rigid         — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex        — lightweight setup, minimal ceremony
brownfield-first        — works with existing codebases, not just greenfield

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

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

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

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

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

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

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

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  Источник истины    │◄─────│  Предлагаемые изменения       │   │
│   │  Как ваша система   │ merge│  Каждое изменение = одна папка│   │
│   │  работает сейчас    │      │  Содержит артефакты и дельты  │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Спецификации (Specs) — это источник истины, описывающий текущее поведение вашей системы.

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

Это разделение является ключевым. Вы можете параллельно работать над несколькими изменениями без конфликтов. Вы можете проверить изменение перед тем, как оно повлияет на основные спецификации. А при архивировании изменения его дельты чистым образом сливаются с источником истины.

Спецификации (Specs)

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

Структура

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

Организуйте спецификации по доменам — логическим группировкам, имеющим смысл для вашей системы. Распространенные шаблоны:

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

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

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

markdown

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

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

## Требования

### Требование: Аутентификация пользователя
Система ДОЛЖНА выдавать JWT-токен после успешного входа.

#### Сценарий: Действительные учетные данные
- Дано пользователь с действительными учетными данными
- Когда пользователь отправляет форму входа
- Тогда возвращается JWT-токен
- И пользователь перенаправляется на панель управления

#### Сценарий: Недействительные учетные данные
- Дано недействительные учетные данные
- Когда пользователь отправляет форму входа
- Тогда отображается сообщение об ошибке
- И токен не выдается

### Требование: Истечение срока сеанса
Система ОБЯЗАНА истекать сеансы после 30 минут бездействия.

#### Сценарий: Тайм-аут простоя
- Дано аутентифицированный сеанс
- Когда проходит 30 минут без активности
- Тогда сеанс становится недействительным
- И пользователь должен пройти повторную аутентификацию

Ключевые элементы:

Элемент	Назначение
`## Цель`	Описание высокого уровня домена этой спецификации
`### Требование:`	Конкретное поведение, которым должна обладать система
`#### Сценарий:`	Конкретный пример работы требования
SHALL/MUST/SHOULD	Ключевые слова RFC 2119, указывающие силу требования

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

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

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

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

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

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

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

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

Хорошее содержание спецификации:

Наблюдаемое поведение, на которое полагаются пользователи или downstream-системы
Входы, выходы и условия ошибок
Внешние ограничения (безопасность, конфиденциальность, надежность, совместимость)
Сценарии, которые можно протестировать или явно проверить

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

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

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

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

Сохраняйте легкость: прогрессивная строгость

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

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

Короткие требования, ориентированные на поведение
Четкий объем работ и цели, которых нет (non-goals)
Несколько конкретных критериев приемки

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

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

Большинство изменений должно оставаться в режиме Lite.

Сотрудничество человека и агента

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

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

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

Изменения (Changes)

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

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

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

Каждое изменение самодостаточно. Оно содержит:

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

Почему изменения — это папки

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

Все вместе. Предложение, дизайн, задачи и спецификации находятся в одном месте. Не нужно искать информацию в разных местах.
Параллельная работа. Несколько изменений могут существовать одновременно без конфликтов. Работайте над add-dark-mode, пока fix-auth-bug также находится в процессе.
Чистая история. При архивировании изменения перемещаются в changes/archive/ с сохранением полного контекста. Вы можете вернуться назад и понять не только то, что изменилось, но и почему.
Удобство для ревью. Папку с изменением легко проверять — откройте ее, прочитайте предложение, проверьте дизайн, посмотрите дельты спецификаций.

Артефакты

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

Поток артефактов

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   why            what           how          steps
 + scope        changes       approach      to take

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

Типы артефактов

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

Предложение фиксирует намерение, объем работ и подход на высоком уровне.

markdown

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

## Намерение
Пользователи запросили опцию темной темы для снижения нагрузки на глаза
во время использования ночью и соответствия системным настройкам.

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

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

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

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

Изменяется объем работ (сужение или расширение)
Уточняется намерение (лучшее понимание проблемы)
Подход фундаментально меняется

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

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

Дизайн (`design.md`)

Дизайн фиксирует технический подход и архитектурные решения.

markdown

# Дизайн: Добавить темную тему

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

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

### Решение: Context вместо Redux
Используем React Context для состояния темы, потому что:
- Простое бинарное состояние (светлая/темная)
- Нет сложных переходов состояния
- Избегаем добавления зависимости Redux

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

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

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

Когда обновлять дизайн:

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

Задачи (`tasks.md`)

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

markdown

# Задачи

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

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

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

Лучшие практики для задач:

Группируйте связанные задачи под заголовками
Используйте иерархическую нумерацию (1.1, 1.2 и т.д.)
Делайте задачи достаточно маленькими, чтобы завершить их за одну сессию
Отмечайте задачи как выполненные по мере завершения

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

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

Формат

markdown

# Дельта для Auth

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

### Требование: Двухфакторная аутентификация
Система ОБЯЗАНА поддерживать двухфакторную аутентификацию на основе TOTP.

#### Сценарий: Регистрация 2FA
- Дано пользователь без включенной 2FA
- Когда пользователь включает 2FA в настройках
- Тогда отображается QR-код для настройки приложения-аутентификатора
- И пользователь должен подтвердить код перед активацией

#### Сценарий: Вход с 2FA
- Дано пользователь с включенной 2FA
- Когда пользователь отправляет действительные учетные данные
- Тогда предъявляется OTP-запрос
- И вход завершается только после ввода действительного OTP

## ИЗМЕНЕННЫЕ Требования

### Требование: Истечение срока сеанса
Система ОБЯЗАНА истекать сеансы после 15 минут бездействия.
(Ранее: 30 минут)

#### Сценарий: Тайм-аут простоя
- Дано аутентифицированный сеанс
- Когда проходит 15 минут без активности
- Тогда сеанс становится недействительным

## УДАЛЕННЫЕ Требования

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

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

Раздел	Значение	Что происходит при архивировании
`## ДОБАВЛЕННЫЕ Требования`	Новое поведение	Добавляется к основной спецификации
`## ИЗМЕНЕННЫЕ Требования`	Измененное поведение	Заменяет существующее требование
`## УДАЛЕННЫЕ Требования`	Устаревшее поведение	Удаляется из основной спецификации; удаление последнего требования выводит возможность из эксплуатации и удаляет файл спецификации, если изменение объявляет `retire_capabilities: true`
`## Цель`	Для чего нужна новая возможность	Заполняет Цель создаваемой основной спецификации; игнорируется, если спецификация уже существует

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

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

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

Эффективность ревью. Ревьюеры видят изменение, а не неизменный контекст. Фокус на том, что важно.

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

Схемы

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

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

yaml

# 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
                   (root node)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (requires:                  (requires:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (requires:
                specs, design)

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

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

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

Стандартный рабочий процесс для spec-driven разработки:

proposal → specs → design → tasks → implement

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

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

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

bash

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

# Или создать на основе существующей
openspec schema fork spec-driven research-first

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

yaml

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # Сначала провести исследование

  - id: proposal
    generates: proposal.md
    requires: [research]   # Proposal основан на исследовании

  - 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        # Теперь включает требования 2FA
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # Сохранено для истории
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

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

Объедините дельты. Каждый раздел дельта-спецификации (ADDED/MODIFIED/REMOVED) применяется к соответствующей основной спецификации.
Переместите в архив. Папка изменения перемещается в changes/archive/ с префиксом даты для хронологического упорядочивания.
Сохраните контекст. Все артефакты остаются в архиве в неизменном виде. Вы всегда можете вернуться назад, чтобы понять, почему было внесено изменение.

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

Чистое состояние. Активные изменения (changes/) показывают только работу в процессе. Завершенная работа убирается с пути.

Аудит-след. Архив сохраняет полный контекст каждого изменения — не только то, что изменилось, но и предложение, объясняющее почему, дизайн, объясняющий как, и задачи, показывающие проделанную работу.

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

Как всё это сочетается

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC FLOW                                   │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
│   │     CHANGE     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
│   │                │  (based on schema dependencies)                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. IMPLEMENT  │  /opsx:apply                                            │
│   │     TASKS      │  Work through tasks, checking them off                  │
│   │                │◄──── Update artifacts as you learn                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. VERIFY     │  /opsx:verify (optional)                                │
│   │     WORK       │  Check implementation matches specs                     │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
│   │     CHANGE     │     │  Change folder moves to archive/             │    │
│   └────────────────┘     │  Specs are now the updated source of truth   │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Позитивный цикл:

Спецификации описывают текущее поведение
Изменения предлагают модификации (в виде дельт)
Реализация воплощает изменения в жизнь
Архив объединяет дельты со спецификациями
Спецификации теперь описывают новое поведение
Следующее изменение опирается на обновленные спецификации

Глоссарий

Термин	Определение
Artifact	Документ внутри изменения (proposal, design, tasks или delta specs)
Archive	Процесс завершения изменения и объединения его дельт с основными спецификациями
Change	Предлагаемая модификация системы, упакованная в папку с артефактами
Delta spec	Спецификация, описывающая изменения (ADDED/MODIFIED/REMOVED) относительно текущих спецификаций
Domain	Логическая группировка для спецификаций (например, `auth/`, `payments/`)
Requirement	Конкретное поведение, которым должна обладать система
Scenario	Конкретный пример требования, обычно в формате Given/When/Then
Schema	Определение типов артефактов и их зависимостей
Spec	Спецификация, описывающая поведение системы, содержащая требования и сценарии
Source of truth	Каталог `openspec/specs/`, содержащий текущее согласованное поведение

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

Начало работы - Практические первые шаги
Рабочие процессы - Общие шаблоны и когда их использовать
Команды - Полная справка по командам
Настройка - Создание пользовательских схем и настройка вашего проекта

Концепции ​

Философия ​

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

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

Спецификации (Specs) ​

Структура ​

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

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

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

Сохраняйте легкость: прогрессивная строгость ​

Сотрудничество человека и агента ​

Изменения (Changes) ​

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

Почему изменения — это папки ​

Артефакты ​

Поток артефактов ​

Типы артефактов ​

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

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

Дизайн (design.md) ​

Задачи (tasks.md) ​

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

Формат ​

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

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

Схемы ​

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

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

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

Архив ​

Что происходит при архивировании ​

Процесс архивирования ​

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

Как всё это сочетается ​

Глоссарий ​

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

Концепции

Философия

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

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

Спецификации (Specs)

Структура

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

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

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

Сохраняйте легкость: прогрессивная строгость

Сотрудничество человека и агента

Изменения (Changes)

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

Почему изменения — это папки

Артефакты

Поток артефактов

Типы артефактов

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

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

Дизайн (`design.md`)

Задачи (`tasks.md`)

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

Формат

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

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

Схемы

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

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

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

Архив

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

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

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

Как всё это сочетается

Глоссарий

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