Концепции

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

Философия

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

fluid not rigid         — нет фазовых ворот, работайте над тем, что имеет смысл
iterative not waterfall — учитесь по мере создания, уточняйте на ходу
easy not complex        — лёгкая настройка, минимальная бюрократия
brownfield-first        — работает с существующей кодовой базой, а не только с нуля

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

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

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

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

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

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

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

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

Specs — это единственный источник истины — они описывают, как ваша система работает в данный момент.

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

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

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

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

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

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

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

workspace     = private local view over context stores, initiatives, repos, and folders
context store = durable shared context container
initiative    = durable coordination context inside a context store
link          = a stable name for a repo or folder the workspace can resolve locally
change        = one planned piece of work; implementation belongs in the owning repo

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

getGlobalDataDir()/workspaces/<workspace-name>/
├── workspace.yaml                 # Запись приватного локального представления
├── AGENTS.md                      # Сгенерированное руководство для выполнения
└── <workspace-name>.code-workspace # Сгенерированный файл рабочего пространства редактора

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

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

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

Стабильные имена ссылок — это способ, которым рабочее пространство ссылается на репозитории и папки. Приватная запись рабочего пространства хранит имена вроде api, web или checkout и сопоставляет их с локальными путями текущего выполнения.

# workspace.yaml
version: 1
name: platform
context: null
links:
  api: /repos/api
  web: /repos/web

Когда рабочее пространство открывает инициативу, context записывает выбранную привязку к хранилищу контекста и идентификатор инициативы. Хранилища, выбранные через реестр, остаются переносимыми по id; хранилища, выбранные по пути, намеренно сохраняют путь, локальный для выполнения, поскольку workspace.yaml является приватным локальным состоянием.

context:
  kind: initiative
  store:
    id: platform
    selector:
      kind: registry
      id: platform
  initiative:
    id: billing-launch

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

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

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

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

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 по-прежнему может читать старые корневые каталоги рабочих пространств бета-версии в качестве входных данных совместимости, но управляемые рабочие пространства теперь используют корневую запись workspace.yaml, описанную выше. Папка рабочего пространства остаётся авторитетной для своего собственного приватного локального представления.

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

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

# Интерактивная настройка
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-cli

# Просмотр известных рабочих пространств из локального реестра
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 update
openspec workspace update --workspace platform --tools codex,claude

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

# Открытие инициативы как локального представления рабочего пространства
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative billing-launch --store-path /repos/platform-context

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

Навыки рабочего пространства устанавливаются только в корне рабочего пространства. Активный глобальный профиль определяет, какие навыки рабочих процессов генерируются; --tools выбирает, какие агенты их получат. Настройка и обновление рабочего пространства не создают файлы слеш-команд, даже когда глобальная доставка включает команды. Запустите openspec workspace update для обновления локального руководства рабочего пространства и добавления, обновления или удаления управляемых локальных каталогов навыков рабочего пространства без редактирования связанных репозиториев или папок.

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

Поддерживаемое рабочее пространство VS Code сначала перечисляет допустимые связанные репозитории или папки, затем контекст инициативы при подключении, затем файлы рабочего пространства OpenSpec. 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           # Поведение UI и темы

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

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

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

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

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

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

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

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

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)

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

# Proposal: Add Dark Mode

Назначение

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

Объём

Включено в работу:

• Переключатель темы в настройках
• Определение системных предпочтений
• Сохранение предпочтений в localStorage

Не включено в работу:

• Пользовательские цветовые темы (будущая работа)
• Переопределение темы для отдельных страниц

Подход

Использовать CSS-переменные для темы с React-контекстом для управления состоянием. Определить системные предпочтения при первой загрузке, разрешить ручное изменение.

**Когда обновлять предложение:**
- Изменяется объём (сужение или расширение)
- Уточняется назначение (лучшее понимание проблемы)
- Подход кардинально меняется

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

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

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

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

````markdown
# Дизайн: Добавление тёмного режима

## Технический подход
Состояние темы управляется через React Context для избежания передачи свойств через вложенность.
CSS-переменные позволяют переключение во время выполнения без переключения классов.

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

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

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

## Поток данных

ThemeProvider (контекст) │ ▼ ThemeToggle ◄──► localStorage │ ▼ CSS-переменные (применяются к :root)

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

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

• Реализация показывает, что подход не работает
• Обнаружено лучшее решение
• Зависимости или ограничения изменились

Задачи (tasks.md)

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

# Задачи

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

Формат

# Дельта для Аутентификации

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

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

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

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

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

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

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

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

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

Секции дельта-спецификаций

Секция	Значение	Что происходит при архивировании
## ДОБАВЛЕННЫЕ Требования	Новое поведение	Добавляется к основной спецификации
## ИЗМЕНЁННЫЕ Требования	Изменённое поведение	Заменяет существующее требование
## УДАЛЁННЫЕ Требования	Упразднённое поведение	Удаляется из основной спецификации

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

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

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

Эффективность рецензирования. Рецензенты видят изменения, а не неизменённый контекст. Сосредоточьтесь на главном.

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

Схемы

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

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

# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # Нет зависимостей, можно создать первым

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # Нужен предложение перед созданием

  - id: design
    generates: design.md
    requires: [proposal]      # Можно создать параллельно со спецификациями

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # Нужны обе спецификации и дизайн

Артефакты образуют граф зависимостей:

                    proposal
                 (корневой узел)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (требует:                    (требует:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (требует:
                specs, design)

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

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

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

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

proposal → specs → design → tasks → implement

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

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

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

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

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

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

# 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]   # Пропустить спецификации/дизайн, перейти сразу к задачам

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

Архив

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

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

До архивирования:

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

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

1. Слияние дельта-спецификаций. Каждая секция дельта-спецификации (ДОБАВЛЕННЫЕ/ИЗМЕНЁННЫЕ/УДАЛЁННЫЕ) применяется к соответствующей основной спецификации.

2. Перемещение в архив. Папка с изменениями перемещается в changes/archive/ с датой в качестве префикса для хронологического упорядочивания.

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

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

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

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

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

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

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

Благотворный цикл:

1. Спецификации описывают текущее поведение
2. Изменения предлагают модификации (в виде дельта-спецификаций)
3. Реализация воплощает изменения в жизнь
4. Архивирование сливает дельта-спецификации в спецификации
5. Спецификации теперь описывают новое поведение
6. Следующее изменение строится на обновлённых спецификациях

Глоссарий

Термин	Определение
Артефакт	Документ внутри изменения (предложение, дизайн, задачи или дельта-спецификации)
Архивация	Процесс завершения изменения и объединения его дельт в основные спецификации
Изменение	Предлагаемая модификация системы, упакованная в папку с артефактами
Дельта-спецификация	Спецификация, описывающая изменения (ДОБАВЛЕНО/ИЗМЕНЕНО/УДАЛЕНО) относительно текущих спецификаций
Домен	Логическая группировка спецификаций (например, auth/, payments/)
Требование	Конкретное поведение, которое система должна демонстрировать
Сценарий	Конкретный пример требования, обычно в формате Допустим/Когда/Тогда
Схема	Определение типов артефактов и их зависимостей
Спецификация	Описание поведения системы, содержащее требования и сценарии
Единый источник истины	Каталог openspec/specs/, содержащий текущее согласованное поведение

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

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