Концепции
Это руководство объясняет основные идеи, лежащие в основе OpenSpec, и то, как они связаны между собой. Для практических инструкций обратитесь к разделам Начало работы и Рабочие процессы.
Философия
OpenSpec построен вокруг четырех принципов:
fluid not rigid — нет фазовых ворот, работайте над тем, что имеет смысл
iterative not waterfall — учитесь в процессе создания, уточняйте по ходу дела
easy not complex — простая настройка, минимальная бюрократия
brownfield-first — работает с существующими кодовыми базами, а не только с новыми проектамиПочему эти принципы важны
Гибкость, а не жесткость. Традиционные системы спецификаций привязывают вас к фазам: сначала вы планируете, затем реализуете, и на этом все заканчивается. OpenSpec более гибкий — вы можете создавать артефакты в любом порядке, который имеет смысл для вашей работы.
Итеративность, а не каскадность. Требования меняются. Понимание углубляется. То, что казалось хорошим подходом в начале, может не выдержать проверки после того, как вы увидите кодовую базу. OpenSpec принимает эту реальность.
Простота, а не сложность. Некоторые фреймворки для спецификаций требуют обширной настройки, жестких форматов или громоздких процессов. OpenSpec не мешает вам работать. Инициализация занимает секунды, начинайте работать сразу, настраивайте только при необходимости.
Приоритет существующих проектов. Большинство работы с ПО — это не создание с нуля, а модификация существующих систем. Подход OpenSpec, основанный на дельтах, упрощает описание изменений в существующем поведении, а не только описание новых систем.
Общая картина
OpenSpec организует вашу работу в две основные области:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Источник истины │◄─────│ Предлагаемые модификации │ │
│ │ Как ваша система │ merge│ Каждое изменение = одна папка │ │
│ │ работает сейчас │ │ Содержит артефакты + дельты │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Спецификации (Specs) — это источник истины — они описывают, как ваша система работает в данный момент.
Изменения (Changes) — это предлагаемые модификации — они хранятся в отдельных папках, пока вы не будете готовы их объединить.
Такое разделение является ключевым. Вы можете работать над несколькими изменениями параллельно без конфликтов. Вы можете проверить изменение до того, как оно повлияет на основные спецификации. А когда вы архивируете изменение, его дельты бесшовно объединяются с источником истины.
Спецификации
Спецификации описывают поведение вашей системы с помощью структурированных требований и сценариев.
Структура
openspec/specs/
├── auth/
│ └── spec.md # Поведение аутентификации
├── payments/
│ └── spec.md # Обработка платежей
├── notifications/
│ └── spec.md # Система уведомлений
└── ui/
└── spec.md # Поведение UI и темыОрганизуйте спецификации по доменам — логическим группам, которые имеют смысл для вашей системы. Типичные паттерны:
- По области функциональности:
auth/,payments/,search/ - По компоненту:
api/,frontend/,workers/ - По ограниченному контексту:
ordering/,fulfillment/,inventory/
Формат спецификации
Спецификация содержит требования, и каждое требование имеет сценарии:
markdown
# Спецификация аутентификации
## Назначение
Аутентификация и управление сессиями для приложения.
## Требования
### Требование: Аутентификация пользователя
Система ДОЛЖНА выдавать JWT-токен после успешного входа.
#### Сценарий: Корректные учетные данные
- ДАН пользователь с корректными учетными данными
- КОГДА пользователь отправляет форму входа
- ТОГДА возвращается JWT-токен
- И пользователь перенаправляется на панель управления
#### Сценарий: Некорректные учетные данные
- ДАНЫ некорректные учетные данные
- КОГДА пользователь отправляет форму входа
- ТОГДА отображается сообщение об ошибке
- И токен не выдается
### Требование: Истечение сессии
Система ОБЯЗАНА завершать сессии после 30 минут бездействия.
#### Сценарий: Тайм-аут простоя
- ДАНА аутентифицированная сессия
- КОГДА проходит 30 минут без активности
- ТОГДА сессия аннулируется
- И пользователь должен пройти аутентификацию зановоКлючевые элементы:
| Элемент | Назначение |
|---|---|
## Назначение | Высокоуровневое описание домена этой спецификации |
### Требование: | Конкретное поведение, которое должна иметь система |
#### Сценарий: | Конкретный пример реализации требования |
| SHALL/MUST/SHOULD | Ключевые слова RFC 2119, указывающие силу требования |
Почему спецификации структурированы именно так
Требования — это "что" — они указывают, что должна делать система, не уточняя реализацию.
Сценарии — это "когда" — они предоставляют конкретные примеры, которые можно проверить. Хорошие сценарии:
- Тестируемы (для них можно написать автоматизированный тест)
- Охватывают как основной сценарий, так и крайние случаи
- Используют формат Given/When/Then или аналогичную структурированную форму
Ключевые слова RFC 2119 (SHALL, MUST, SHOULD, MAY) передают намерение:
- MUST/SHALL — абсолютное требование
- SHOULD — рекомендуется, но существуют исключения
- MAY — опционально
Что такое спецификация (и что это не такое)
Спецификация — это контракт поведения, а не план реализации.
Хорошее содержание спецификации:
- Наблюдаемое поведение, на которое полагаются пользователи или внешние системы
- Входы, выходы и условия ошибок
- Внешние ограничения (безопасность, конфиденциальность, надежность, совместимость)
- Сценарии, которые можно протестировать или явно проверить
Чего следует избегать в спецификациях:
- Внутренних имен классов/функций
- Выбора библиотек или фреймворков
- Пошаговых деталей реализации
- Подробных планов выполнения (они должны находиться в
design.mdилиtasks.md)
Быстрая проверка:
- Если реализация может измениться без изменения внешнего видимого поведения, вероятно, она не должна находиться в спецификации.
Сохраняйте легкость: Прогрессивная строгость
OpenSpec стремится избежать бюрократии. Используйте самый легкий уровень, который все еще делает изменение проверяемым.
Легкая спецификация (по умолчанию):
- Краткие требования с фокусом на поведение
- Ясная область и исключения
- Несколько конкретных проверок приемлемости
Полная спецификация (для более рискованных изменений):
- Изменения, затрагивающие несколько команд или репозиториев
- Изменения API/контрактов, миграции, вопросы безопасности/конфиденциальности
- Изменения, где неоднозначность, вероятно, приведет к дорогостоящей переделке
Большинство изменений должны оставаться в легком режиме.
Сотрудничество человека и агента
Во многих командах люди исследуют, а агенты создают артефакты. Предполагаемый цикл:
- Человек предоставляет намерение, контекст и ограничения.
- Агент преобразует это в требования с фокусом на поведение и сценарии.
- Агент хранит детали реализации в
design.mdиtasks.md, а не вspec.md. - Валидация подтверждает структуру и ясность перед реализацией.
Это делает спецификации читаемыми для людей и согласованными для агентов.
Изменения
Изменение — это предлагаемая модификация вашей системы, упакованная в папку со всем необходимым для понимания и реализации.
Структура изменения
openspec/changes/add-dark-mode/
├── proposal.md # Почему и что
├── design.md # Как (технический подход)
├── tasks.md # Чеклист реализации
├── .openspec.yaml # Метаданные изменения (опционально)
└── specs/ # Дельта-спецификации
└── ui/
└── spec.md # Что изменяется в ui/spec.mdКаждое изменение самодостаточно. Оно включает:
- Артефакты — документы, фиксирующие намерение, дизайн и задачи
- Дельта-спецификации — спецификации для того, что добавляется, изменяется или удаляется
- Метаданные — опциональная конфигурация для этого конкретного изменения
Почему изменения — это папки
Упаковка изменения в папку имеет несколько преимуществ:
Все вместе. Предложение, дизайн, задачи и спецификации находятся в одном месте. Не нужно искать в разных местах.
Параллельная работа. Несколько изменений могут существовать одновременно без конфликтов. Работайте над
add-dark-mode, пока также ведется работа надfix-auth-bug.Чистая история. При архивации изменения перемещаются в
changes/archive/с сохранением полного контекста. Вы можете вернуться и понять не только что изменилось, но и почему.Удобство проверки. Папку изменения легко проверить — откройте ее, прочитайте предложение, проверьте дизайн, посмотрите на дельты спецификаций.
Артефакты
Артефакты — это документы внутри изменения, направляющие работу.
Поток артефактов
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
почему что как шаги
+ область изменения подход для выполненияАртефакты строятся друг на друге. Каждый артефакт предоставляет контекст для следующего.
Типы артефактов
Предложение (proposal.md)
Предложение фиксирует намерение, область и подход на высоком уровне.
markdown
# Предложение: Добавить темный режим
## Назначение
Пользователи запрашивали опцию темного режима для уменьшения нагрузки на глаза
при использовании в ночное время и соответствия системным настройкам.
## Область
В область входит:
- Переключатель темы в настройках
- Определение системных предпочтений
- Сохранение предпочтения в localStorage
Вне области:
- Пользовательские цветовые темы (будущая работа)
- Переопределение темы для отдельных страниц
## Подход
Использовать пользовательские свойства CSS для темизации с контекстом React
для управления состоянием. Определять системные предпочтения при первой загрузке,
позволять ручное переопределение.Когда обновлять предложение:
- Изменяется область (сужение или расширение)
- Уточняется намерение (лучшее понимание проблемы)
- Подход принципиально меняется
Спецификации (дельта-спецификации в specs/)
Дельта-спецификации описывают что изменяется по отношению к текущим спецификациям. См. Дельта-спецификации ниже.
Дизайн (design.md)
Дизайн фиксирует технический подход и архитектурные решения.
markdown
# Дизайн: Добавить темный режим
## Технический подход
Состояние темы управляется через React Context для избежания прокидывания пропсов.
Пользовательские свойства CSS позволяют переключать тему в рантайме без переключения классов.
## Архитектурные решения
### Решение: Контекст вместо Redux
Используем React Context для управления состоянием темы, потому что:
- Простое бинарное состояние (светлая/тёмная тема)
- Отсутствие сложных переходов состояний
- Избегаем добавления зависимости от Redux
### Решение: CSS Custom Properties
Используем CSS-переменные вместо CSS-in-JS, потому что:
- Работает с существующими таблицами стилей
- Нет накладных расходов во время выполнения
- Нативное решение браузера
## Поток данных
```
ThemeProvider (контекст)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS-переменные (применяются к :root)
```
## Изменения файлов
- `src/contexts/ThemeContext.tsx` (новый)
- `src/components/ThemeToggle.tsx` (новый)
- `src/styles/globals.css` (изменён)Когда обновлять дизайн:
- Реализация показывает, что подход не работает
- Обнаружено лучшее решение
- Изменяются зависимости или ограничения
Задачи (tasks.md)
Задачи — это чек-лист реализации — конкретные шаги с флажками.
markdown
# Задачи
## 1. Инфраструктура темы
- [ ] 1.1 Создать ThemeContext с состоянием светлой/тёмной темы
- [ ] 1.2 Добавить пользовательские CSS-свойства для цветов
- [ ] 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. Пользователи должны повторно аутентифицироваться в каждой сессии.)Секции дельты
| Секция | Значение | Что происходит при архивации |
|---|---|---|
## ДОБАВЛЕННЫЕ требования | Новое поведение | Добавляется в основную спецификацию |
## ИЗМЕНЁННЫЕ требования | Изменённое поведение | Заменяет существующее требование |
## УДАЛЁННЫЕ требования | Устаревшее поведение | Удаляется из основной спецификации |
Почему дельты, а не полные спецификации
Ясность. Дельта показывает именно то, что меняется. Читая полную спецификацию, вам пришлось бы мысленно сравнивать её с текущей версией.
Избежание конфликтов. Два изменения могут затрагивать один и тот же файл спецификации без конфликтов, если они модифицируют разные требования.
Эффективность проверки. Проверяющие видят изменение, а не неизменный контекст. Фокус на том, что важно.
Соответствие 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
(корневой узел)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(требует: (требует:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(требует:
specs, design)Зависимости — это ускорители, а не шлагбаумы. Они показывают, что можно создавать, а не то, что вы должны создавать следующим. Вы можете пропустить design, если он вам не нужен. Вы можете создавать specs до или после design — оба зависят только от proposal.
Встроенные схемы
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Процесс архивации
Слияние дельт. Каждая секция дельта-спецификации (ДОБАВЛЕННЫЕ/ИЗМЕНЁННЫЕ/УДАЛЁННЫЕ) применяется к соответствующей основной спецификации.
Перемещение в архив. Папка изменения перемещается в
changes/archive/с датовым префиксом для хронологического порядка.Сохранение контекста. Все артефакты остаются нетронутыми в архиве. Вы всегда можете вернуться, чтобы понять, почему было сделано изменение.
Почему архивация важна
Чистое состояние. Активные изменения (changes/) показывают только текущую работу. Завершённая работа убирается с дороги.
Аудиторский след. Архив сохраняет полный контекст каждого изменения — не только то, что изменилось, но и proposal, объясняющий почему, design, объясняющий как, и задачи, показывающие проделанную работу.
Эволюция спецификаций. Спецификации растут органически по мере архивации изменений. Каждая архивация сливает свои дельты, со временем формируя комплексную спецификацию.
Как всё это работает вместе
┌──────────────────────────────────────────────────────────────────────────────┐
│ ПРОЦЕСС OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. НАЧАЛО │ /opsx:propose (core) или /opsx:new (expanded) │
│ │ ИЗМЕНЕНИЯ │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. СОЗДАНИЕ │ /opsx:ff или /opsx:continue (expanded workflow) │
│ │ АРТЕФАКТОВ │ Создаёт proposal → specs → design → tasks │
│ │ │ (на основе зависимостей схемы) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. РЕАЛИЗАЦИЯ │ /opsx:apply │
│ │ ЗАДАЧ │ Работа над задачами, отмечая их выполнение │
│ │ │◄──── Обновление артефактов по мере обучения │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. ПРОВЕРКА │ /opsx:verify (опционально) │
│ │ РАБОТЫ │ Проверка соответствия реализации спецификациям │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. АРХИВАЦИЯ │────►│ Дельта-спецификации сливаются с основными │ │
│ │ ИЗМЕНЕНИЯ │ │ Папка изменения перемещается в archive/ │ │
│ └────────────────┘ │ Спецификации теперь являются обновлённым │ │
│ │ источником истины │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Добродетельный цикл:
- Спецификации описывают текущее поведение
- Изменения предлагают модификации (в виде дельт)
- Реализация делает изменения реальными
- Архивация сливает дельты со спецификациями
- Спецификации теперь описывают новое поведение
- Следующее изменение строится на обновлённых спецификациях
Глоссарий
| Термин | Определение |
|---|---|
| Артефакт | Документ в рамках изменения (предложение, дизайн, задачи или дельта-спецификации) |
| Архивация | Процесс завершения изменения и слияния его дельт в основные спецификации |
| Изменение | Предлагаемая модификация системы, оформленная в виде папки с артефактами |
| Дельта-спецификация | Спецификация, описывающая изменения (ДОБАВЛЕНО/ИЗМЕНЕНО/УДАЛЕНО) относительно текущих спецификаций |
| Домен | Логическая группировка спецификаций (например, auth/, payments/) |
| Требование | Конкретное поведение, которое должна иметь система |
| Сценарий | Конкретный пример требования, обычно в формате Given/When/Then |
| Схема | Определение типов артефактов и их зависимостей |
| Спецификация | Документ, описывающий поведение системы, содержащий требования и сценарии |
| Единый источник истины | Директория openspec/specs/, содержащая текущее согласованное поведение |
Следующие шаги
- Начало работы - Практические первые шаги
- Рабочие процессы - Типовые паттерны и когда использовать каждый
- Команды - Полный справочник по командам
- Настройка - Создание пользовательских схем и настройка вашего проекта