Концепции

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

Философия

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

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

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

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

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

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

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

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

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

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

Спецификации — это источник истины — они описывают, как ваша система ведёт себя в данный момент.

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

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

Рабочие пространства координации

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

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

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

Ментальная модель рабочего пространства:

text

workspace = где живут связанные межрепозиторные изменения
link      = стабильное имя для репозитория или папки, с которыми рабочее пространство может работать
change    = одна функция, исправление, проект или другая запланированная работа

Рабочее пространство имеет другую структуру, чем проект, локальный для репозитория:

text

workspace-folder/
├── changes/                       # Планирование на уровне рабочего пространства
└── .openspec-workspace/
    ├── workspace.yaml             # Общая идентификация рабочего пространства и имена ссылок
    └── local.yaml                 # Локальные пути этой машины

Состояние OpenSpec, локальное для репозитория, сохраняет существующую структуру:

text

repo-root/
└── openspec/
    ├── specs/
    └── changes/

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

Стабильные имена ссылок — это способ, которым планирование рабочего пространства ссылается на репозитории и папки. Общее состояние рабочего пространства хранит имена вроде api, web или checkout; каждая машина сопоставляет эти имена со своими локальными путями в .openspec-workspace/local.yaml.

yaml

# .openspec-workspace/workspace.yaml
version: 1
name: platform
links:
  api: {}
  web: {}

yaml

# .openspec-workspace/local.yaml
version: 1
paths:
  api: /repos/api
  web: /repos/web

Рабочие пространства, созданные OpenSpec, по умолчанию исключают .openspec-workspace/local.yaml из переносимого состояния совместной работы. .openspec-workspace/workspace.yaml остаётся переносимым, поскольку хранит имя рабочего пространства и стабильные имена ссылок, а не абсолютные пути к рабочим копиям конкретного пользователя.

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

text

multi-repo:
  api      -> /repos/api
  web      -> /repos/web

large monorepo:
  billing  -> /repos/platform/services/billing
  checkout -> /repos/platform/apps/checkout

Управляемые рабочие пространства находятся в стандартном каталоге данных OpenSpec:

text

getGlobalDataDir()/workspaces

Это означает $XDG_DATA_HOME/openspec/workspaces, когда XDG_DATA_HOME установлен, ~/.local/share/openspec/workspaces в качестве запасного варианта в стиле Unix и %LOCALAPPDATA%\openspec\workspaces в качестве запасного варианта для нативной Windows. Нативные оболочки Windows, PowerShell и WSL2 каждая хранят строки пути для среды выполнения, запускающей OpenSpec. Эта основа не транслирует пути между D:\repo, /mnt/d/repo и UNC-путями WSL.

OpenSpec также ведёт реестр, локальный для машины, по адресу:

text

getGlobalDataDir()/workspaces/registry.yaml

Реестр сопоставляет имена рабочих пространств с их расположениями, чтобы последующие глобальные команды могли перечислять или выбирать известные рабочие пространства откуда угодно. Это только индекс. Каждая папка рабочего пространства остаётся авторитетной для своего собственного .openspec-workspace/workspace.yaml и .openspec-workspace/local.yaml, поэтому устаревшие записи реестра могут быть обнаружены и исправлены без переопределения самого рабочего пространства.

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

Полезные команды:

bash

# Настройка с помощью мастера
openspec workspace setup

# Настройка, удобная для автоматизации
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex

# Просмотр известных рабочих пространств из локального реестра
openspec workspace list
openspec workspace ls

# Добавление или исправление ссылок для выбранного рабочего пространства
openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace relink api-service /new/path/to/api

# Проверка того, что может разрешить эта машина
openspec workspace doctor
openspec workspace doctor --workspace platform

# Открытие связанного набора рабочих файлов
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

workspace setup всегда создаёт рабочее пространство в стандартном расположении, записывает его в локальный реестр, показывает расположение рабочего пространства и требует хотя бы одну связанную папку или репозиторий. Интерактивная настройка запрашивает предпочтительный инструмент открытия. Неинтерактивная настройка сохраняет его только тогда, когда предоставлен --opener codex, --opener claude, --opener github-copilot или --opener editor.

OpenSpec также поддерживает корневые файлы открытия рабочего пространства: управляемый OpenSpec блок рекомендаций в AGENTS.md, файл <workspace-name>.code-workspace, локальный для машины, для открытия в VS Code и GitHub Copilot-in-VS-Code, а также специальное правило игнорирования для этого поддерживаемого файла .code-workspace. Созданные пользователем файлы *.code-workspace остаются отслеживаемыми, поскольку правило игнорирования нацелено только на поддерживаемый файл.

Поддерживаемое рабочее пространство VS Code включает корень координации как . плюс допустимые связанные репозитории или папки в качестве дополнительных корней. VS Code отображает эти записи как мультикорневое рабочее пространство.

workspace open открывает связанный набор рабочих файлов с помощью сохранённого предпочтительного инструмента, если только не передан --agent <tool> или --editor для этой конкретной сессии. Передача обоих переопределений инструмента открытия является ошибкой. Открытие корневого рабочего пространства делает связанные репозитории и папки видимыми для исследования и планирования; реализация начинается после того, как пользователь явно запросит работу по реализации.

workspace link и workspace relink записывают только существующие папки; они не создают, копируют, перемещают, инициализируют и не редактируют связанный репозиторий или папку. После успешной привязки или перепривязки OpenSpec обновляет управляемые рекомендации, файл рабочего пространства VS Code и правило игнорирования.

Команды рабочего пространства, которым требуется одно рабочее пространство, могут запускаться откуда угодно с --workspace <name>. Если вы запускаете их внутри папки рабочего пространства или подкаталога, OpenSpec использует это текущее рабочее пространство. Если доступно несколько известных рабочих пространств и вы не передали --workspace <name>, команды для людей показывают средство выбора; --json и --no-interactive завершаются ошибкой со структурированным статусом вместо запроса.

Прямые команды рабочего пространства поддерживают вывод JSON для скриптов. JSON-ответы хранят основные данные в объектах workspace, workspaces или link и сообщают о предупреждениях или ошибках в массивах status. Исправные объекты используют status: [].

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

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

Структура

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

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

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

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

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

markdown

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

Назначение

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

Требования

Требование: Аутентификация пользователя

Система ДОЛЖНА выдавать JWT-токен при успешном входе.

Сценарий: Действительные учетные данные

ДАНО пользователь с действительными учетными данными
КОГДА пользователь отправляет форму входа
ТО возвращается JWT-токен
И пользователь перенаправляется на панель управления

Сценарий: Недействительные учетные данные

ДАНЫ недействительные учетные данные
КОГДА пользователь отправляет форму входа
ТО отображается сообщение об ошибке
И токен не выдается

Требование: Истечение сессии

Система ОБЯЗАНА завершать сессии после 30 минут бездействия.

Сценарий: Тайм-аут бездействия

ДАНА аутентифицированная сессия
КОГДА проходит 30 минут без активности
ТО сессия становится недействительной
И пользователь должен пройти аутентификацию повторно


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

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

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

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

**Сценарии — это "когда"** — они предоставляют конкретные примеры, которые можно проверить. Хорошие сценарии:
- Являются тестируемыми (для них можно написать автоматизированный тест)
- Охватывают как основной путь, так и граничные случаи
- Используют структурированный формат Given/When/Then или аналогичный

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

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

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

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

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

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

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

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

**Легкая спецификация (по умолчанию):**
- Короткие требования, основанные на поведении
- Четкая область действия и не-цели
- Несколько конкретных проверок приемки

**Полная спецификация (для более высокого риска):**
- Изменения, затрагивающие несколько команд или репозиториев
- Изменения API/контрактов, миграции, проблемы безопасности/конфиденциальности
- Изменения, где неоднозначность, вероятно, приведет к дорогостоящей переработке

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

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

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

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

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

## Изменения

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

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

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


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

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

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

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

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

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

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

## Артефакты

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

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

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

Формат

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`	Устаревшее поведение	Удаляется из основной спецификации

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

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

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

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

Соответствие условиям 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]   # Предложение на основе исследования

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

Порядок действий:

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

Глоссарий

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

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

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

Концепции ​

Философия ​

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

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

Рабочие пространства координации ​

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

Структура ​

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

Назначение ​

Требования ​

Требование: Аутентификация пользователя ​

Сценарий: Действительные учетные данные ​

Сценарий: Недействительные учетные данные ​

Требование: Истечение сессии ​

Сценарий: Тайм-аут бездействия ​

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

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

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

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

Формат ​

Секции дельт ​

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

Схемы ​

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

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

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

Архивирование ​

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

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

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

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

Глоссарий ​

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

Концепции

Философия

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

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

Рабочие пространства координации

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

Структура

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

Назначение

Требования

Требование: Аутентификация пользователя

Сценарий: Действительные учетные данные

Сценарий: Недействительные учетные данные

Требование: Истечение сессии

Сценарий: Тайм-аут бездействия

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

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

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

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

Формат

Секции дельт

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

Схемы

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

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

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

Архивирование

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

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

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

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

Глоссарий

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