Концепции

В этом руководстве описаны основные идеи OpenSpec и то, как они взаимодействуют между собой. Для получения информации о практическом использовании см. Начало работы и Рабочие процессы.

Философия

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

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

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

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

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

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

Ориентированный на существующие проекты в первую очередь. Большая часть работы над программным обеспечением не связана с созданием систем с нуля — она заключается в модификации уже существующих. Подход 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) — это предлагаемые модификации, они хранятся в отдельных папках, пока вы не будете готовы объединить их с основной версией.

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

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

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

Структура

openspec/specs/
├── auth/
│   └── spec.md           # Authentication behavior
├── payments/
│   └── spec.md           # Payment processing
├── notifications/
│   └── spec.md           # Notification system
└── ui/
    └── spec.md           # UI behavior and themes

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

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

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

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

markdown

# Auth Specification

## Purpose
Authentication and session management for the application.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- 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
The system MUST expire sessions after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate

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

Элемент	Назначение
`## 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/контрактов, миграции, проблемы безопасности и конфиденциальности
Изменения, в которых неоднозначность может привести к дорогостоящей доработке

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

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

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

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

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

Изменения

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

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

openspec/changes/add-dark-mode/
├── proposal.md           # Why and what
├── design.md             # How (technical approach)
├── tasks.md              # Implementation checklist
├── .openspec.yaml        # Change metadata (optional): schema, created, skip_specs
└── specs/                # Delta specs
    └── ui/
        └── spec.md       # What's changing in 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

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.

## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage

Out of scope:
- Custom color themes (future work)
- Per-page theme overrides

## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.

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

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

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

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

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

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

markdown

# Design: Add Dark Mode

## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.

## Architecture Decisions

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution

## Data Flow
```
ThemeProvider (context)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS Variables (applied to :root)
```

## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)

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

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

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

Задачи — это чек-лист реализации, состоящий из конкретных шагов с чекбоксами.

markdown

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibility

Рекомендации по работе с задачами:

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

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

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

Формат

markdown

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation

#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)

Разделы дельта-спецификации

Раздел	Значение	Что происходит при архивации
`## ADDED Requirements`	Новое поведение	Добавляется в основную спецификацию
`## MODIFIED Requirements`	Измененное поведение	Заменяет существующее требование
`## REMOVED Requirements`	Устаревшее поведение	Удаляется из основной спецификации

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

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

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

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

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

Схемы

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

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

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
   (requires:                  (requires:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (requires:
                specs, design)

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

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

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

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

proposal → specs → design → tasks → implement

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

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

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

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, переходите сразу к tasks

Подробную информацию о создании и использовании пользовательских схем см. в разделе Настройка.

Архив

Архивация завершает изменение путём слияния его дельта-спецификаций в основные specs и сохраняет изменение для истории.

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

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

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/) отображают только работу в процессе. Завершенная работа перемещается за пределы активной области.

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

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

Как это всё работает вместе

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

Положительный цикл:

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

Глоссарий

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

Дальнейшие шаги

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

Концепции ​

Философия ​

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

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

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

Структура ​

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

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

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

Держите облегченным: постепенное повышение строгости ​

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

Изменения ​

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

Почему изменения упакованы в папки ​

Артефакты ​

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

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

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

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

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

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

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

Формат ​

Разделы дельта-спецификации ​

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

Схемы ​

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

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

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

Архив ​

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

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

Зачем нужна архивация ​

Как это всё работает вместе ​

Глоссарий ​

Дальнейшие шаги ​

Концепции

Философия

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

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

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

Структура

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

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

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

Держите облегченным: постепенное повышение строгости

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

Изменения

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

Почему изменения упакованы в папки

Артефакты

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

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

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

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

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

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

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

Формат

Разделы дельта-спецификации

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

Схемы

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

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

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

Архив

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

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

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

Как это всё работает вместе

Глоссарий

Дальнейшие шаги