Концепции
Этот гайд объясняет основные идеи OpenSpec и то, как они взаимодействуют. Для практического использования см. Getting Started и Workflows.
Философия
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". Большая часть работы с программным обеспечением заключается не в создании с нуля, а в модификации существующих систем. Дельта-ориентированный подход OpenSpec позволяет легко указывать изменения существующего поведения, а не просто описывать новые системы.
Общая картина
OpenSpec организует вашу работу в две основные области:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs — это источник истины, они описывают текущее поведение вашей системы.
Changes — это предлагаемые модификации, которые находятся в отдельных папках до тех пор, пока вы не будете готовы их слить (merge).
Это разделение имеет ключевое значение. Вы можете работать над несколькими изменениями параллельно без конфликтов. Вы можете просмотреть изменение до того, как оно повлияет на основные specs. А когда вы архивируете изменение, его дельты чисто сливаются в источник истины.
Specs
Specs описывают поведение вашей системы с использованием структурированных требований и сценариев.
Структура
openspec/specs/
├── auth/
│ └── spec.md # Authentication behavior (Поведение аутентификации)
├── payments/
│ └── spec.md # Payment processing (Обработка платежей)
├── notifications/
│ └── spec.md # Notification system (Система уведомлений)
└── ui/
└── spec.md # UI behavior and themes (Поведение пользовательского интерфейса и темы)Организуйте specs по домену — логические группы, которые имеют смысл для вашей системы. Общие паттерны:
- По области функциональности:
auth/,payments/,search/ - По компоненту:
api/,frontend/,workers/ - По ограниченному контексту (bounded context):
ordering/,fulfillment/,inventory/
Формат Spec
Spec содержит требования, и каждое требование имеет сценарии:
markdown
# Auth Specification (Спецификация аутентификации)
## Purpose (Цель)
Управление аутентификацией и сессиями для приложения.
## Requirements (Требования)
### Requirement: User Authentication (Требование: Аутентификация пользователя)
Система ДОЛЖНА выдать JWT токен после успешного входа в систему.
#### Scenario: Valid credentials (Сценарий: Корректные учетные данные)
- GIVEN a user with valid credentials (ДАНО: пользователь с корректными учетными данными)
- WHEN the user submits login form (КОГДА: пользователь отправляет форму входа)
- THEN a JWT token is returned (ТОГДА: возвращается JWT токен)
- AND the user is redirected to dashboard (И: пользователь перенаправляется на панель управления)
#### Scenario: Invalid credentials (Сценарий: Некорректные учетные данные)
- GIVEN invalid credentials (ДАНО: некорректные учетные данные)
- WHEN the user submits login form (КОГДА: пользователь отправляет форму входа)
- THEN an error message is displayed (ТОГДА: отображается сообщение об ошибке)
- AND no token is issued (И: токен не выдается)
### Requirement: Session Expiration (Требование: Истечение срока действия сессии)
Система ДОЛЖНА истекать сессии после 30 минут бездействия.
#### Scenario: Idle timeout (Сценарий: Тайм-аут бездействия)
- GIVEN an authenticated session (ДАНО: аутентифицированная сессия)
- WHEN 30 minutes pass without activity (КОГДА: проходит 30 минут без активности)
- THEN the session is invalidated (ТОГДА: сессия аннулируется)
- AND the user must re-authenticate (И: пользователь должен повторно пройти аутентификацию)Ключевые элементы:
| Элемент | Назначение |
|---|---|
## Purpose | Высокоуровневое описание домена данной спецификации |
### Requirement: | Конкретное поведение, которое должна обеспечить система |
#### Scenario: | Конкретный пример требования в действии |
| SHALL/MUST/SHOULD | Ключевые слова RFC 2119, указывающие на силу требования |
Почему такая структура Specs (Спецификаций)
Требования — это «ЧТО» — они описывают, что должна делать система, без указания реализации.
Сценарии — это «КОГДА» — они предоставляют конкретные примеры, которые можно проверить. Хорошие сценарии:
- Поддаются тестированию (можно написать автоматический тест)
- Охватывают как основной путь (happy path), так и крайние случаи (edge cases)
- Используют структуру Given/When/Then или аналогичный формат
Ключевые слова RFC 2119 (SHALL, MUST, SHOULD, MAY) передают намерение:
- MUST/SHALL — абсолютное требование
- SHOULD — рекомендуется, но существуют исключения
- MAY — опционально
Что такое Spec (Спецификация), а что нет
Spec — это контракт поведения, а не план реализации.
Хороший контент спецификации:
- Наблюдаемое поведение, на которое полагаются пользователи или нижестоящие системы
- Входы, выходы и условия ошибок
- Внешние ограничения (безопасность, конфиденциальность, надежность, совместимость)
- Сценарии, которые можно протестировать или явно проверить
Чего избегать в спецификациях:
- Внутренние имена классов/функций
- Выборки библиотек или фреймворков
- Пошаговые детали реализации
- Подробные планы выполнения (они относятся к
design.mdилиtasks.md)
Быстрая проверка:
- Если реализация может измениться без изменения внешне видимого поведения, то она, вероятно, не должна быть в спецификации.
Держите это легким: Прогрессивная строгость
OpenSpec стремится избегать бюрократии. Используйте самый легкий уровень, который все еще позволяет проверить изменение.
Легкая spec (по умолчанию):
- Краткие требования, ориентированные на поведение
- Четкий объем и нецели (non-goals)
- Несколько конкретных проверок приемки (acceptance checks)
Полная spec (для высокого риска):
- Изменения, затрагивающие несколько команд или репозиториев
- Изменения API/контрактов, миграции, вопросы безопасности/конфиденциальности
- Изменения, где неоднозначность, вероятно приведет к дорогостоящей переработке
Большинство изменений должны оставаться в Легком режиме.
Сотрудничество Человека и Агента (Agent)
Во многих командах люди исследуют, а агенты составляют артефакты. Предполагаемый цикл таков:
- Человек предоставляет намерение, контекст и ограничения.
- Агент преобразует это в требования и сценарии, ориентированные на поведение.
- Агент сохраняет детали реализации в
design.mdиtasks.md, а не вspec.md. - Валидация подтверждает структуру и ясность перед реализацией.
Это делает спецификации читаемыми для людей и согласованными для агентов.
Changes (Изменения)
Change — это предлагаемая модификация вашей системы, упакованная как папка со всем необходимым для понимания и реализации.
Структура Change
openspec/changes/add-dark-mode/
├── proposal.md # Why and what (Почему и что)
├── design.md # How (technical approach) (Как, технический подход)
├── tasks.md # Implementation checklist (Контрольный список реализации)
├── .openspec.yaml # Change metadata (optional) (Метаданные изменения, опционально)
└── specs/ # Delta specs (Дельты спецификаций)
└── ui/
└── spec.md # What's changing in ui/spec.md (Что меняется в ui/spec.md)Каждое изменение самодостаточно. Оно содержит:
- Artifacts — документы, фиксирующие намерение, дизайн и задачи
- Delta specs — спецификации того, что добавляется, изменяется или удаляется
- Metadata — опциональная конфигурация для этого конкретного изменения
Почему Changes — это папки
Упаковка изменения в виде папки имеет несколько преимуществ:
Все вместе. Предложение, дизайн, задачи и спецификации находятся в одном месте. Не нужно искать их в разных местах.
Параллельная работа. Несколько изменений могут существовать одновременно без конфликтов. Работайте над
add-dark-mode, пока идет процессfix-auth-bug.Чистая история. При архивировании изменения перемещаются в
changes/archive/с сохранением полного контекста. Вы можете заглянуть назад и понять не только то, что изменилось, но и почему.Удобно для обзора (Review). Папка изменения легко просматривается — откройте ее, прочитайте предложение, проверьте дизайн, просмотрите дельты спецификаций.
Artifacts (Артефакты)
Artifacts — это документы внутри Change, которые направляют работу.
Поток Артефактов
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeАртефакты строятся друг на друге. Каждый артефакт предоставляет контекст для следующего.
Типы Артефактов
Proposal (proposal.md)
Proposal фиксирует намерение (intent), объем (scope) и подход (approach) на высоком уровне.
markdown
# Proposal: Add Dark Mode (Предложение: Добавление темной темы)
## Intent (Намерение)
Пользователи запросили опцию темной темы для снижения нагрузки на глаза во время ночного использования и соответствия системным предпочтениям.
## Scope (Объем)
Входит в объем:
- Переключатель темы в настройках
- Обнаружение системных предпочтений
- Сохранение предпочтений в localStorage
Не входит в объем:
- Пользовательские цветовые темы (будущая работа)
- Переопределение тем на уровне страницы
## Approach (Подход)
Использовать CSS custom properties для тематизации с React context для управления состоянием. Обнаруживать системные предпочтения при первой загрузке, разрешить ручное переопределение.Когда обновлять Proposal:
- Изменение объема (сужение или расширение)
- Уточнение намерения (лучшее понимание проблемы)
- Фундаментальный сдвиг подхода
Specs (Дельты спецификаций в specs/)
Delta specs описывают что меняется по сравнению с текущими спецификациями. Смотрите Delta Specs ниже.
Design (design.md)
Design фиксирует технический подход и архитектурные решения.
markdown
# Design: Add Dark Mode (Дизайн: Добавление темной темы)
## Technical Approach (Технический подход)
Состояние темы управляется через React Context, чтобы избежать "prop drilling" (передачи свойств). CSS custom properties позволяют переключать тему во время выполнения без переключения классов.
## Architecture Decisions (Архитектурные решения)
### Decision: Context over Redux (Решение: Context вместо Redux)
Использование React Context для состояния темы, потому что:
- Простое бинарное состояние (светлый/темный)
- Нет сложных переходов состояний
- Избегает добавления зависимости Redux
### Decision: CSS Custom Properties (Решение: CSS Custom Properties)
Использование переменных CSS вместо CSS-in-JS, потому что:
- Работает с существующим файлом стилей
- Не имеет накладных расходов во время выполнения
- Решение, нативное для браузера
## Data Flow (Поток данных)
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes (Изменения файлов)
- `src/contexts/ThemeContext.tsx` (новый)
- `src/components/ThemeToggle.tsx` (новый)
- `src/styles/globals.css` (измененный)Когда обновлять Design:
- Реализация показывает, что подход не сработает
- Обнаружено лучшее решение
- Изменились зависимости или ограничения
Tasks (tasks.md)
Tasks — это контрольный список реализации — конкретные шаги с чекбоксами.
markdown
# Tasks (Задачи)
## 1. Theme Infrastructure (Инфраструктура темы)
- [ ] 1.1 Create ThemeContext with light/dark state (Создать ThemeContext со состоянием светлый/темный)
- [ ] 1.2 Add CSS custom properties for colors (Добавить CSS custom properties для цветов)
- [ ] 1.3 Implement localStorage persistence (Реализовать сохранение в localStorage)
- [ ] 1.4 Add system preference detection (Добавить обнаружение системных предпочтений)
## 2. UI Components (Компоненты пользовательского интерфейса)
- [ ] 2.1 Create ThemeToggle component (Создать компонент ThemeToggle)
- [ ] 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 (Обновить компоненты, чтобы они использовали переменные CSS)
- [ ] 3.3 Test contrast ratios for accessibility (Проверить коэффициенты контрастности для доступности)Лучшие практики для задач:
- Группируйте связанные задачи под заголовками
- Используйте иерархическое нумерование (1.1, 1.2 и т.д.)
- Держите задачи достаточно маленькими, чтобы завершить их за одну сессию
- Проставляйте галочки при выполнении
Delta Specs (Дельты спецификаций)
Delta specs — это ключевая концепция, которая позволяет OpenSpec работать для проектов с "brownfield" (уже существующей кодовой базой). Они описывают что меняется, а не повторяют всю спецификацию.
Формат
markdown
# Delta for Auth (Дельта для Аутентификации)
## ADDED Requirements (ДОБАВЛЕННЫЕ Требования)
### Requirement: Two-Factor Authentication (Требование: Двухфакторная аутентификация)
Система ДОЛЖНА поддерживать двухфакторную аутентификацию на основе TOTP.
#### Scenario: 2FA enrollment (Сценарий: Регистрация 2FA)
- GIVEN a user without 2FA enabled (ДАНО: пользователь без включенной 2FA)
- WHEN the user enables 2FA in settings (КОГДА: пользователь включает 2FA в настройках)
- THEN a QR code is displayed for authenticator app setup (ТОГДА: отображается QR-код для настройки приложения аутентификатора)
- AND the user must verify with a code before activation (И: пользователь должен проверить с помощью кода перед активацией)
#### Scenario: 2FA login (Сценарий: Вход с 2FA)
- GIVEN a user with 2FA enabled (ДАНО: пользователь с включенной 2FA)
- WHEN the user submits valid credentials (КОГДА: пользователь отправляет корректные учетные данные)
- THEN an OTP challenge is presented (ТОГДА: представляется вызов OTP)
- AND login completes only after valid OTP (И: вход завершается только после корректного OTP)
## MODIFIED Requirements (ИЗМЕНЕННЫЕ Требования)
### Requirement: Session Expiration (Требование: Истечение срока действия сессии)
Система ДОЛЖНА истекать сессии после 15 минут бездействия.
(Ранее: 30 минут)
#### Scenario: Idle timeout (Сценарий: Тайм-аут бездействия)
- GIVEN an authenticated session (ДАНО: аутентифицированная сессия)
- WHEN 15 minutes pass without activity (КОГДА: проходит 15 минут без активности)
- THEN the session is invalidated (ТОГДА: сессия аннулируется)
## REMOVED Requirements (УДАЛЕННЫЕ Требования)
### Requirement: Remember Me (Требование: Запомнить меня)
(Устарело в пользу 2FA. Пользователи должны повторно проходить аутентификацию при каждой сессии.)Секции Delta (Дельты)
| Секция | Значение | Что происходит при архивировании |
|---|---|---|
## ADDED Requirements | Новое поведение | Добавляется к основной спецификации |
## MODIFIED Requirements | Измененное поведение | Заменяет существующее требование |
## REMOVED Requirements | Устаревшее поведение | Удаляется из основной спецификации |
Почему Дельты, а не Полные Спецификации
Ясность. Дельта показывает именно то, что меняется. Читая полную спецификацию, вам пришлось бы мысленно сравнивать ее с текущей версией.
Предотвращение конфликтов. Два изменения могут затрагивать один и тот же файл спецификации без конфликта, при условии, что они изменяют разные требования.
Эффективность обзора. Рецензенты видят изменение, а не неизменённый контекст. Сосредоточьтесь на том, что важно.
Соответствие 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)Зависимости — это активаторы, а не блокирующие ворота. Они показывают, что возможно создать, а не то, что вы должны создавать следующим. Вы можете пропустить дизайн, если он вам не нужен. Вы можете создать specs до или после дизайна — оба зависят только от 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, переходим сразу к задачамСм. Customization для получения полной информации о создании и использовании пользовательских схем.
Архив
Архивирование завершает изменение путем слияния его дельта-спецификаций в основные спецификации и сохранения изменения для истории.
Что происходит при архивировании
До архивирования:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ слияние (merge)
├── 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/) показывают только незавершенную работу. Завершенная работа перемещается в архив.
Аудиторский след. Архив сохраняет полный контекст каждого изменения — не просто то, что изменилось, а proposal, объясняющий почему, design, объясняющий как, и задачи, показывающие выполненную работу.
Эволюция спецификаций. Спецификации развиваются органически по мере архивирования изменений. Каждый архив сливает свои дельты, постепенно формируя всеобъемлющую спецификацию.
Как это всё работает вместе
┌──────────────────────────────────────────────────────────────────────────────┐
│ ПОТОК 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/ │ │
│ └────────────────┘ │ Спецификации теперь являются обновленным источником истины │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Благородный цикл:
- Specs описывают текущее поведение.
- Изменения предлагают модификации (в виде дельт).
- Реализация делает изменения реальными.
- Архив сливает дельты в specs.
- Specs теперь описывают новое поведение.
- Следующее изменение строится на основе обновленных спецификаций.
Глоссарий
| Термин | Определение |
|---|---|
| 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/, содержащая текущее согласованное поведение |
Следующие шаги
- Getting Started - Практические первые шаги
- Workflows - Общие шаблоны и когда их использовать
- Commands - Полная справочная информация по командам
- Customization - Создание пользовательских схем и настройка вашего проекта