Урок 15.3. Основные понятия: specs, changes и deltas

Зачем это нужно

В уроке 15.2 первое изменение прошло полный цикл /opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive, но мы сознательно не задерживались на внутренней механике: что именно создает openspec init, почему изменение - это папка, что такое дельта-спецификация и что происходит с ней при архивации.

Этот урок - опорная точка всего модуля. Здесь собрана ментальная модель OpenSpec: living specs, изменения, дельта-спецификации, артефакты, схемы и архивация. Остальные уроки - от справочников команд (15.5-15.6) до качества спецификаций (15.10) и архитектуры OPSX (15.14) - предполагают, что эта модель уже освоена. Если вы пришли из обзорного урока 2.10, здесь та же система разобрана изнутри.

В конце урока - консолидированный глоссарий модуля: таблица соответствий английских терминов русским эквивалентам и определения ключевых понятий. Единая терминология вводится здесь и соблюдается во всех последующих уроках. Материал объединяет три документа оригинала (overview.md, concepts.md, glossary.md); повторы устранены.

Основная идея

OpenSpec - легкий слой договоренностей между вами и вашим AI-агентом: вы записываете, что изменение должно делать, агент готовит детали, вы оба смотрите на один и тот же план - и только после этого пишется код. Вся идея умещается в пять слов: сначала договориться, потом уверенно строить (agree first, then build confidently).

В репозитории для этого появляются два каталога. openspec/specs/ хранит то, что истинно прямо сейчас, - living spec (актуальную спецификацию) системы. openspec/changes/ содержит то, что предлагается, - по одной папке на каждое изменение. Архивация переводит предложение в истину.

Пять идей OpenSpec

Все в OpenSpec построено из пяти понятий. Освойте их - остальное детали.

1. Спецификации - это истина. Спецификация описывает, как система ведет себя прямо сейчас. Она живет в openspec/specs/, организована по доменам (auth/, payments/, ui/) и состоит из требований («the system SHALL expire sessions after 30 minutes») и сценариев - конкретных примеров формата given/when/then. Спецификация - это единый согласованный ответ на вопрос «что эта программа делает?».

2. Изменение - одна единица работы. Когда нужно добавить, изменить или убрать поведение, создается изменение: папка в openspec/changes/, содержащая все об этой работе в одном месте. Proposal, design, список задач и правки спецификаций. Одно изменение, одна папка, одна функциональность.

3. Дельты описывают изменение, а не весь мир. Внутри изменения вы не переписываете спецификацию целиком. Пишется маленькая дельта: ADDED - это требование добавлено, MODIFIED - это изменено, REMOVED - вот это удалено. Именно этот прием позволяет OpenSpec хорошо редактировать существующие системы, а не только проектировать новые с чистого листа. Описывается diff, а не конечное состояние.

4. Артефакты строятся друг на друге. Изменение содержит несколько документов, создаваемых в естественном порядке - proposal → specs → design → tasks → implement, - и каждый дает контекст следующему. К любому артефакту можно вернуться в любой момент: это «включатели», а не ворота.

5. Архивация сворачивает изменение обратно в истину. Когда работа завершена, изменение архивируется. Его дельты сливаются в основные спецификации, а папка изменения переезжает в changes/archive/ с датой в имени. Теперь спецификации описывают новую реальность, и вы готовы к следующему изменению. Цикл замыкается.

Разделение «спецификации - изменения» - ключ ко всей механике: над несколькими изменениями можно работать параллельно, изменение можно проревьюить до того, как оно повлияет на основные спецификации, а при архивации дельты сливаются в источник истины чисто и предсказуемо.

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

Спецификации описывают поведение системы через структурированные требования и сценарии. Такой массив называют living spec - актуальной спецификацией: она фиксирует не то, что когда-то планировалось, а то, как система работает прямо сейчас.

Структура каталога

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

Спецификации организуются по возможностям (capabilities) - логическим группировкам, имеющим смысл для вашей системы. Типовые паттерны:

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

«Возможность (capability)» и «домен (domain)» употребляются как синонимы. Когда в возможности не остается ни одного требования, она «отправляется на пенсию» (раздел про дельты).

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

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

# 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

### 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

Ключевые элементы формата:

Требования - это «что», сценарии - это «когда»

Требования формулируют «что» - что система должна делать, без привязки к реализации. Сценарии дают «когда» - конкретные проверяемые примеры. Хороший сценарий:

• тестируем: по нему можно написать автоматический тест;
• покрывает и happy path, и граничные случаи;
• использует структурированный формат Given/When/Then или похожий.

Ключевые слова RFC 2119

Слова MUST, SHALL, SHOULD и MAY несут стандартизированное значение о строгости требования (название - от документа интернет-стандартов RFC 2119):

• MUST/SHALL - абсолютное требование;
• SHOULD - рекомендация, допускающая исключения;
• MAY - необязательное поведение.

Чем спецификация является - и чем не является

Спецификация - это поведенческий контракт, а не план реализации. Хорошее содержимое:

• наблюдаемое поведение, на которое полагаются пользователи или смежные системы;
• входы, выходы и условия ошибок;
• внешние ограничения (безопасность, приватность, надежность, совместимость) и сценарии, которые можно явно проверить.

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

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

Прогрессивная строгость

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

Lite-спецификация (по умолчанию): короткие требования, сформулированные через поведение; ясные рамки и не-цели; несколько конкретных проверок приемки.

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

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

Человек и агент

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

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

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

Изменения

Изменение - предлагаемая модификация системы, упакованная в папку со всем, что нужно для ее понимания и реализации.

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

openspec/changes/add-dark-mode/
├── proposal.md           # зачем и что
├── design.md             # как (технический подход)
├── tasks.md              # чек-лист реализации
├── .openspec.yaml        # метаданные изменения (необязательно): schema, created,
│                         # skip_specs, retire_capabilities
└── specs/                # дельта-спецификации
    └── ui/
        └── spec.md       # что меняется в ui/spec.md

Каждое изменение самодостаточно. В нем есть:

• артефакты - документы, фиксирующие намерение, проект и задачи;
• дельта-спецификации - описания того, что добавляется, меняется или удаляется;
• метаданные - необязательная конфигурация конкретного изменения.

Почему изменение - это папка

Упаковка изменения в папку дает четыре выгоды:

1. Все вместе. Proposal, design, tasks и спецификации живут в одном месте.
2. Параллельная работа. Несколько изменений существуют одновременно, не мешая друг другу: можно работать над add-dark-mode, пока в прогрессе fix-auth-bug.
3. Чистая история. При архивации изменения переезжают в changes/archive/ с полным контекстом. Позже можно понять не только что изменилось, но и почему.
4. Удобное ревью. Папку изменения легко открыть: прочитать proposal, проверить design, посмотреть дельты спецификаций.

Артефакты

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

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

Proposal - proposal.md

Proposal (предложение об изменении) фиксирует намерение, рамки и подход на верхнем уровне. Это первый создаваемый артефакт.

# 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.

Когда обновлять proposal: изменились рамки (сузились или расширились), прояснилось намерение, подход принципиально сместился.

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

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

Design - design.md

Design фиксирует технический подход и архитектурные решения. Для простых изменений его можно пропустить.

# 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

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

Когда обновлять design: реализация показала, что подход не работает; найдено лучшее решение; изменились зависимости или ограничения.

Tasks - tasks.md

Tasks - чек-лист реализации: конкретные шаги с чекбоксами.

# 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

Практики ведения задач:

• группируйте связанные задачи под заголовками;
• используйте иерархическую нумерацию (1.1, 1.2 и так далее);
• держите задачи достаточно мелкими, чтобы выполнять за одну сессию;
• указывайте, как проверяется каждая задача (тест, команда или наблюдаемый результат);
• размещайте тесты и документацию, которых требует группа задач, внутри этой же группы;
• отмечайте задачи выполненными по мере продвижения.

Во время /opsx:apply агент работает по этому списку и отмечает пункты по мере выполнения.

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

Дельта-спецификация (delta spec) - ключевое понятие, благодаря которому OpenSpec работает для brownfield-разработки. Дельта описывает, что меняется, а не пересказывает всю спецификацию целиком.

Формат дельты

# 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

## 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.)

Секции дельты и эффект при архивации

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

• Ясность. Дельта показывает точно, что меняется; полную спецификацию пришлось бы мысленно сравнивать с текущей версией.
• Без конфликтов. Два изменения могут трогать один файл спецификации, не конфликтуя, пока они меняют разные требования.
• Эффективное ревью. Ревьюер видит изменение, а не неизменный контекст.
• Пригодность для brownfield. Большая часть работы - модификация существующего поведения. Дельты делают модификацию полноценной частью процесса, а не запоздалой мыслью.

Инженерный вывод курса: дельта-спецификация - это diff для поведенческого контракта, полный аналог git diff, но не для кода, а для требований. Как и в git, вы читаете diff, чтобы понять изменение, и применяете его, чтобы обновить «рабочую копию» - основные спецификации. Вся механика OpenSpec держится на этой аналогии.

«Включатели, а не ворота»

Эта фраза встречается в документации OpenSpec повсюду, поэтому зафиксируем, что она значит.

Классические процессы со спецификациями устроены как waterfall: закончить планирование, только потом разрешена реализация, вернуться назад больно. OpenSpec отказывается от этой модели. Порядок proposal → specs → design → tasks показывает, что становится возможным далее, а не что вы обязаны делать далее.

Обнаружили посреди реализации, что design ошибочен? Отредактируйте design.md и продолжайте. Поняли, что рамки стоит сузить? Обновите proposal. Ничего не блокируется: зависимости существуют только чтобы у агента был нужный контекст, а не чтобы запереть вас в фазах.

Сильная сторона - честность: реальная работа грязная и итеративная, и OpenSpec позволяет ей быть такой. Плата - самодисциплина: вы сами отвечаете за то, чтобы изменение оставалось сфокусированным. Рабочие привычки для этого разобраны в уроке 15.8.

Схемы

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

Как устроена схема

# 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

Граф зависимостей

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

Это DAG (directed acyclic graph): стрелки указывают только вперед, циклов нет. OpenSpec использует граф, чтобы определять, что можно создавать следующим.

Зависимости - «включатели», а не ворота: они показывают, что возможно создать. Design можно пропустить, если он не нужен; specs можно создавать до или после design - оба зависят только от proposal.

Встроенная схема spec-driven

Схема по умолчанию - spec-driven: стандартный workflow спецификация-ориентированной разработки.

proposal → specs → design → tasks → implement

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

Кастомные схемы

Под workflow команды можно создать собственную схему:

# создать с нуля
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]   # proposal на основе исследования

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # без specs/design, сразу к задачам

Полный разбор кастомизации - в уроке 15.13.

Архивация

Архивация завершает изменение: дельты сливаются в основные спецификации, а само изменение сохраняется в историю.

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

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

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,
                                   # design, tasks, specs

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

1. Слить дельты. Каждая секция дельты (ADDED/MODIFIED/REMOVED) применяется к соответствующей основной спецификации.
2. Переместить в архив. Папка изменения переезжает в changes/archive/ с префиксом даты.
3. Сохранить контекст. Все артефакты остаются нетронутыми - к ним можно вернуться, чтобы понять, почему изменение было сделано.

Родственное действие - синхронизация (sync): слияние дельт изменения в основные спецификации без архивации. Обычно она происходит автоматически (архивация сама предлагает ее выполнить), но доступна и отдельно как /opsx:sync для долгоживущих изменений.

Зачем архивировать

• Чистое состояние. В активных изменениях (changes/) видно только то, что в работе. Завершенное уходит с дороги.
• Аудиторский след. Архив сохраняет полный контекст: proposal объясняет «почему», design - «как», tasks показывают проделанную работу.
• Эволюция спецификаций. Спецификации растут органически по мере архивации изменений: каждая архивация вливает свои дельты.

Как всё связано вместе

Полный цикл работы OpenSpec от начала изменения до архивации:

«Добродетельный цикл» выглядит так:

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

Повседневный цикл команд

В настройках по умолчанию рабочий день выглядит так: сначала (необязательно) обдумать задачу, затем одна команда готовит план, вы читаете его, следующая - реализует, последняя - убирает в архив.

/opsx:explore                   →  (необязательно) сначала обдумать с AI
/opsx:propose add-dark-mode     →  AI готовит proposal, specs, design, tasks
        (вы читаете и правите план)
/opsx:apply                     →  AI реализует, отмечая задачи
/opsx:archive                   →  спецификации обновлены, изменение заархивировано

Если сомневаетесь - начинайте с исследования. /opsx:explore - «партнер по размышлению» без ставок: агент читает код, раскладывает варианты и превращает расплывчатую идею в конкретный план до того, как написан хоть один файл кода, - противоядие от агента, который иначе построит что-то по смутному промпту. Точно знаете, что хотите? Переходите сразу к /opsx:propose. Explore входит в профиль по умолчанию, так что команда всегда под рукой; подробный разбор - в уроке 15.7.

Все это - слэш-команды в чате AI-ассистента; установка и инициализация происходят в терминале. Это разделение - самая частая точка путаницы, и урок 15.4 разбирает его отдельно.

Стоит ли это дополнительной работы

Честно: OpenSpec добавляет шаг. Перед реализацией пишется короткий план. Что взамен?

• Ошибочные повороты ловятся раньше, чем станут дорогими. Исправить недопонимание в proposal объемом в один абзац - бесплатно; после того, как агент написал 400 строк, - нет.
• План и код живут в одном репозитории. Полгода спустя спецификация расскажет вам (и следующей сессии AI), почему система работает именно так.
• Изменения можно ревьюить. Папка изменения - аккуратный пакет: прочитать proposal, просмотреть дельты, проверить задачи. Никакой археологии в истории чата.
• Подходит для существующих кодовых баз. Благодаря дельтам можно описать изменение в приложении на 50 000 строк, не документируя его целиком заранее.

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

Терминология модуля

Глоссарий ниже консолидирует терминологию всего модуля: он объединяет glossary.md оригинала с решениями плана модуля. Английский термин дается при первом упоминании вместе с русским эквивалентом, дальше - русский вариант.

Соответствие английских и русских терминов

Термины последней группы нужны, только когда планирование расползается на несколько репозиториев; функциональность в статусе beta, разбор - в уроке 15.12.

Русские определения ключевых терминов

Практика

1. Откройте проект из урока 15.2 (или выполните openspec init в свежем тестовом каталоге, как в уроке 15.1).
2. Постройте дерево openspec/: найдите specs/ и changes/, определите, какие возможности уже описаны.
3. Откройте папку созданного изменения и прочитайте артефакты в порядке потока: proposal.md → specs/ → design.md → tasks.md. Какие секции встречаются в дельте и что каждая означает?
4. Для одной возможности из specs/ выпишите название требования, использованное ключевое слово RFC 2119 и сценарии. Проверьте себя быстрым тестом: нет ли в спецификации внутренних имен классов или деталей реализации?
5. Нарисуйте граф зависимостей для гипотетической схемы research → proposal → specs → tasks (без design). Какие артефакты можно создавать параллельно?

Краткое резюме

Ментальная модель OpenSpec умещается в два каталога и пять идей: openspec/specs/ - living spec, источник истины о текущем поведении системы; openspec/changes/ - предлагаемые модификации, по одной папке на изменение.

• Спецификация состоит из требований (ключевые слова RFC 2119) и сценариев (Given/When/Then); это поведенческий контракт, а не план реализации.
• Изменение - самодостаточная папка с артефактами proposal.md, design.md, tasks.md и дельта-спецификациями в specs/.
• Дельта описывает только ADDED/MODIFIED/REMOVED относительно текущих спецификаций - поэтому OpenSpec удобен для brownfield.
• Артефакты строятся друг на друге (proposal → specs → design → tasks), но это «включатели», а не ворота: любой документ можно править в любой момент.
• Схема (по умолчанию spec-driven) задает типы артефактов и их граф зависимостей; схемы можно форкать и писать свои.
• Архивация сливает дельты в основные спецификации и убирает папку изменения в changes/archive/ с датой - спецификации описывают новую реальность; термины модуля сведены в глоссарий выше и действуют во всех уроках 15.1-15.15.

Вопросы для самопроверки

1. Какие два каталога образуют openspec/ и какую роль играет каждый? Что происходит с ними при архивации изменения?
2. Чем дельта-спецификация отличается от полной и какие секции в ней бывают? Что происходит с каждой секцией при архивации?
3. Что означает принцип «включатели, а не ворота»? Приведите пример ситуации, когда разрешено вернуться к уже созданному артефакту.
4. Чем MUST и SHALL отличаются от SHOULD и MAY в требованиях? Почему сценарий должен быть проверяемым?
5. Что, согласно быстрому тесту из урока, не должно попадать в спецификацию?
6. Что определяет схема и какие артефакты с какими зависимостями входят во встроенную схему spec-driven?

Что дальше

Урок 15.4 разбирает, где какая команда выполняется: CLI openspec в терминале и слэш-команды /opsx:* в чате агента, интерактивный режим, вариации написания команд в разных инструментах и типичную ошибку новичка.

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/docs/overview.md
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/glossary.md