Урок 15.2. Быстрый старт: первое изменение от идеи до архива

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

В уроке 15.1 вы установили OpenSpec и выполнили openspec init в тестовом проекте. Этот урок проводит первый полный цикл: от идеи изменения до его архивации, на минимальном примере - темная тема для приложения. Материал взят из официального гайда Getting Started и разобран шаг за шагом.

Знать список команд недостаточно. У нового пользователя OpenSpec обычно спотыкается о три вещи:

где выполняется каждая команда: openspec ... - в терминале, /opsx:... - в чате coding-агента, и это самая частая ошибка первых дней;
какие именно файлы появляются в репозитории после openspec init и зачем нужен каждый из них;
как из короткого proposal (предложения об изменении) получается актуальная спецификация системы - что именно происходит при архивации.

Этот урок отвечает на все три вопроса на одном сквозном примере. В обзоре 2.10 OpenSpec уже появлялся как один из SDD-инструментов; здесь его цикл проходится руками, а не по карточке инструмента.

Оригинальный Getting Started описывает работу с уже установленным и инициализированным OpenSpec: инструкции по установке и карту всей документации мы разобрали в уроке 15.1.

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

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

flowchart LR subgraph Terminal["Терминал: подготовка"] A1["npm install -g @fission-ai/openspec@latest"] --> A2["cd your-project && openspec init"] end subgraph Chat["Чат агента: работа над изменением"] B1["/opsx:explore (необязательно)"] --> B2["/opsx:propose add-dark-mode"] B2 --> B3["/opsx:apply"] B3 --> B4["/opsx:archive"] end A2 --> B1

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

Версия на тридцать секунд

«Версия на тридцать секунд» уже давалась в уроке 15.1; здесь она же - с явной меткой, где выполняется каждый шаг:

ТЕРМИНАЛ    $ npm install -g @fission-ai/openspec@latest
ТЕРМИНАЛ    $ cd your-project && openspec init
ЧАТ АГЕНТА    /opsx:explore                    (необязательно: продумать заранее)
ЧАТ АГЕНТА    /opsx:propose add-dark-mode      (агент готовит план; вы его проверяете)
ЧАТ АГЕНТА    /opsx:apply                      (агент реализует)
ЧАТ АГЕНТА    /opsx:archive                    (спецификации обновлены, изменение убрано в архив)

Два шага в терминале - и дальше вы живете в чате. Остальная часть урока расшифровывает, что делает каждый шаг и что вы увидите.

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

Пока не ясно, что именно строить? Начните с /opsx:explore. Это партнер по размышлению без обязательств: команда читает кодовую базу, взвешивает варианты и превращает расплывчатую идею в конкретный план - все еще до написания кода. Когда картина проясняется, эстафета передается /opsx:propose. Авторы документации называют это лучшей привычкой при работе с AI, который иначе уверенно построит не то, что нужно. Подробный разбор explore - в уроке 15.7.

Где выполнять команды

Самый частый ранний конфуз - перепутать два места, в которых живут команды OpenSpec:

openspec ... (например, openspec init) выполняется в терминале;
/opsx:... (например, /opsx:propose) выполняется в чате AI-ассистента - в том же окне, куда вы обычно пишете «добавь фичу».

Отдельного «интерактивного режима» запускать не нужно: вы просто вводите слэш-команду в чате, и ассистент разбирается дальше сам. Полное объяснение - в уроке 15.4.

Как устроен цикл команд

Быстрый путь по умолчанию (профиль core)

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (необязательно)

Начните с /opsx:explore, если еще разбираетесь, что делать; переходите сразу к /opsx:propose, если уже знаете. Explore входит в профиль по умолчанию, так что он всегда под рукой, когда понадобится.

Заметьте: в «версии на тридцать секунд» выше шаг /opsx:sync не показан, а в полном быстром пути профиля core он есть - документация приводит оба варианта списка. Справочник всех команд, включая sync, - урок 15.5.

Расширенный путь (выбор кастомного workflow)

/opsx:new ──► /opsx:ff или /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Глобальный профиль по умолчанию - core; в него входят propose, explore, apply, update, sync и archive. Расширенные команды workflow включаются через openspec config profile, после чего нужно выполнить openspec update.

Оба пути описывают один и тот же жизненный цикл изменения; расширенный путь - альтернативный набор команд с другими именами (new, ff, continue, verify). Для первого изменения достаточно профиля core - пример ниже использует именно его.

Что появляется в репозитории после init

После openspec init проект получает такую структуру:

openspec/
├── specs/              # Источник истины (текущее поведение системы)
│   └── <domain>/
│       └── spec.md
├── changes/            # Предлагаемые обновления (одна папка на изменение)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Дельта-спецификации (что меняется)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Конфигурация проекта (необязательно)

В дереве <domain> - домен спецификации, например auth или payments; <change-name> - имя конкретного изменения, например add-dark-mode. Полные имена файлов и каталогов всегда остаются на английском.

Два ключевых каталога:

openspec/specs/ - источник истины. Эти спецификации описывают, как система ведет себя сейчас. Организованы по доменам: например, specs/auth/, specs/payments/.
openspec/changes/ - предлагаемые модификации. Каждое изменение получает собственную папку со всеми связанными артефактами. Когда изменение завершено, его спецификации сливаются в главный каталог specs/.

Файл config.yaml необязателен и хранит конфигурацию проекта; настройке посвящен урок 15.13.

Артефакты изменения

Каждая папка изменения содержит артефакты, которые направляют работу:

Артефакт	Назначение
`proposal.md`	«зачем» и «что» - фиксирует цель, объем и подход
`specs/`	дельта-спецификации (delta specs): требования ADDED/MODIFIED/REMOVED
`design.md`	«как» - технический подход и архитектурные решения
`tasks.md`	чек-лист реализации с чекбоксами

Артефакты строятся друг на друге: proposal → specs → design → tasks → реализация. По мере того как в ходе реализации вы узнаете новое, ранние артефакты можно возвращать и уточнять.

flowchart LR P["proposal.md: зачем и что"] --> S["specs/: дельта-требования"] S --> D["design.md: как"] D --> T["tasks.md: чек-лист"] T --> IMPL["реализация"] IMPL -.->|"уточнения по мере узнаемого"| P IMPL -.-> S IMPL -.-> D

Как работают дельта-спецификации

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

Инженерный вывод курса: дельта-спецификация читается как diff. Ревью изменения сводится к просмотру короткого списка операций ADDED/MODIFIED/REMOVED, а не к перечитыванию всей спецификации домена.

Формат

Дельта-спецификация использует секции, каждая из которых указывает тип изменения:

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

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

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

Три секции - три типа операций: ADDED добавляет требования, MODIFIED заменяет существующие, REMOVED удаляет. Требования и сценарии остаются на английском - SHALL/WHEN/THEN это часть формата, а не prose. Как писать сильные требования, разобрано в уроке 15.10.

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

Когда изменение архивируется:

требования ADDED дописываются в главную спецификацию;
требования MODIFIED заменяют существующую версию;
требования REMOVED удаляются из главной спецификации.

Папка изменения переезжает в openspec/changes/archive/ - она остается там как история для аудита.

Пример: первое изменение

Пройдем канонический пример документации - добавление темной темы (dark mode) в приложение. Все команды ниже можно выполнить в любом тестовом проекте с инициализированным OpenSpec.

Шаг 1. Создание изменения

Вы:  /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — зачем делаем и что меняется
     ✓ specs/       — требования и сценарии
     ✓ design.md    — технический подход
     ✓ tasks.md     — чек-лист реализации

Аргумент add-dark-mode становится именем папки изменения: openspec/changes/add-dark-mode/. Агент готовит черновик плана, а вы его проверяете - именно на этом шаге дешевле всего исправить неверное понимание задачи.

Если включен расширенный профиль workflow, то же самое делается в два шага: /opsx:new, затем /opsx:ff (или /opsx:continue для инкрементальной работы).

Шаг 2. Что создается

Разберем каждый артефакт из ответа агента.

proposal.md - фиксирует цель изменения:

markdown
# Proposal: Add Dark Mode

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

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

Три секции отвечают на три вопроса: Intent - зачем изменение (пользователи просят темную тему), Scope - что входит (переключатель в настройках, следование системной теме, хранение выбора в localStorage), Approach - выбранный технический путь (CSS custom properties плюс React context).

specs/ui/spec.md - дельта с новыми требованиями:

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

Одно требование - два сценария: ручное переключение и следование системной теме. Обратите внимание: дельта не описывает темную тему целиком - только новые требования относительно текущих спецификаций UI. Формулировки требований пока можно просто читать; правила их написания - урок 15.10.

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

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

Чек-лист сгруппирован по темам: инфраструктура темы, UI-компоненты, стилизация. Нумерация пунктов 1.1-3.2 совпадает с отметками в выводе /opsx:apply ниже - по ней удобно следить за прогрессом.

Шаг 3. Реализация

Вы:  /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

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

Шаг 4. Архивация

Вы:  /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Дельта-спецификации теперь часть главных спецификаций: они документируют, как работает система. Изменение закрыто, история осталась в openspec/changes/archive/.

Убедиться, что изменение действительно закрыто, можно командой openspec list: в списке активных изменений его больше нет.

Проверка и ревью

Для проверки изменений используется CLI - эти команды выполняются в терминале:

bash
# Список активных изменений
openspec list

# Детали конкретного изменения
openspec show add-dark-mode

# Проверка форматирования спецификаций
openspec validate add-dark-mode

# Интерактивный дашборд
openspec view

Каждая команда отвечает на свой вопрос: list - какие изменения активны, show - что внутри конкретного изменения, validate - корректно ли отформатированы его спецификации, view - интерактивный обзор всего.

openspec validate стоит запускать до архивации: она проверяет форматирование спецификаций изменения. Полный справочник CLI - урок 15.6; что проверять в плане, который подготовил агент, до написания кода - урок 15.10.

Куда двигаться дальше

Getting Started сознательно остается поверхностным: это самый короткий путь до первого архивированного изменения. Оригинал завершается списком «Next Steps» - вот как он ложится на документацию и на этот модуль. Ссылки в таблице ведут на английские оригиналы документов; перевод и разбор - в уроках модуля:

Тема оригинала	О чем	Урок модуля
Core Concepts at a Glance	ментальная модель на одной странице	15.3
Concepts	глубже о specs, changes и схемах	15.3
Commands	полный справочник слэш-команд	15.5
Explore First	продумать идею до proposal	15.7
Workflows	типовые паттерны команд и когда какую применять	15.8
Examples & Recipes	реальные изменения от начала до конца	15.9
Reviewing a Change	что проверить в плане до кода	15.10
Writing Good Specs	сильные requirement и scenario	15.10
Editing & Iterating on a Change	правка артефактов, откат, reconciliation	15.10
Existing Projects	большой brownfield-codebase	15.11
Stores	планирование в отдельном репозитории (beta)	15.12
Customization	настройка под себя	15.13
FAQ и Troubleshooting	когда застряли	15.15

Уроки в таблице - план модуля; читайте их по порядку или прыгайте к нужной теме.

Практика

Если еще не делали практику урока 15.1 - выполните openspec init в тестовом проекте и найдите в созданном каталоге openspec/ три объекта: specs/, changes/ и config.yaml.
Придумайте минимальное изменение, например add-page-footer - ссылка в подвале страницы. Что-то простое, о чем вы можете судить сами.
Если не сразу ясно, что именно менять, начните с /opsx:explore и опишите идею своими словами; когда она оформится в план - переходите дальше.
Выполните /opsx:propose add-page-footer, затем откройте openspec/changes/add-page-footer/ в редакторе и прочитайте proposal.md, дельту в specs/ и tasks.md до того, как разрешать агенту писать код.
В терминале выполните openspec validate add-page-footer и посмотрите, что проверка форматирования проходит.
В чате выполните /opsx:apply, затем /opsx:archive.
Проверьте результат: openspec list больше не показывает изменение, в openspec/specs/ появились его требования, а папка изменения переехала в openspec/changes/archive/.

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

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

Полный цикл OpenSpec - это две терминальные команды подготовки и четыре слэш-команды в чате агента; все остальное - артефакты на диске, которые можно читать, проверять и уточнять.

openspec init создает openspec/specs/ (источник истины, по доменам), openspec/changes/ (папки изменений) и необязательный config.yaml.
Быстрый путь профиля core: /opsx:explore (необязательно) → /opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive; расширенный workflow (/opsx:new, /opsx:ff, /opsx:continue, /opsx:verify) включается через openspec config profile и openspec update.
Изменение описывают четыре артефакта: proposal.md, дельта specs/, design.md, tasks.md; их можно уточнять по мере узнаемого в ходе реализации.
Дельта-спецификация показывает изменения относительно текущих спецификаций через секции ADDED/MODIFIED/REMOVED; при архивации они применяются к главной спецификации, а папка изменения уходит в openspec/changes/archive/.
Состояние изменений проверяется CLI-командами openspec list, show, validate, view.

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

Какие команды OpenSpec выполняются в терминале, а какие - в чате AI-ассистента? Почему смешение этих двух мест - самая частая ошибка первых дней?
Перечислите быстрый путь профиля core. Какие команды входят в профиль core и как включить расширенный workflow?
Для чего нужны каталоги openspec/specs/ и openspec/changes/? Что происходит с папкой изменения при архивации?
Какие артефакты создает /opsx:propose и как они строятся друг на друге? Можно ли возвращаться к ранним артефактам во время реализации?
Что означают секции ADDED, MODIFIED и REMOVED в дельта-спецификации и как каждая из них применяется к главной спецификации при архивации?
Какими командами CLI можно проверить состояние изменения до архивации и что именно проверяет openspec validate?

Что дальше

Цикл пройден руками, но за кадром остались вопросы «почему так устроено»: чем живая спецификация отличается от изменения, как структурно устроены specs и changes, что такое возможность (capability) и зачем нужна схема. Урок 15.3 собирает всю ментальную модель на одной странице - и вводит полный глоссарий модуля.

Источники

https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md