Урок 15.9. Примеры и рецепты: реальные изменения от начала до конца

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

К этому моменту все компоненты OpenSpec разобраны по отдельности: урок 15.2 провел первое изменение от идеи до архивации, урок 15.7 показал /opsx:explore как партнера по размышлению, урок 15.8 свел команды в workflow-паттерны. Между «понимать карту команд» и «уверенно провести изменение» остается дистанция, и преодолевается она только на разобранных примерах - с командами, которые вы вводите, и ответами, которые приходят обратно.

Этот урок - коллекция таких примеров: реальные изменения от начала до конца, записанные как стенограммы сессий. Каждый рецепт привязан к конкретной ситуации (маленькая фича, багфикс, исследование, параллельная работа, рефакторинг, пошаговое планирование, обучение на своем коде) и показывает полную последовательность действий. Формат выбран под копирование: сопоставьте свою ситуацию с паттерном и повторите его команд за командой.

Урок завершает «повседневный» блок модуля (15.7-15.10). Если вы пришли сюда из обзорного урока 2.10, этот материал - самый быстрый способ увидеть рабочий цикл OpenSpec целиком, без углубления в концепции.

Рецепты используют стандартный набор core-команд (propose, explore, apply, update, sync, archive). Там, где помогает расширенный набор, это явно отмечено - рецепты 6 и 7.

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

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

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

Прежде чем читать стенограммы, зафиксируем обозначения:

Вы:  сообщение в чате AI-ассистента (слэш-команды /opsx:* - тоже сюда)
AI:  ответ агента в чате
$    команда в терминале

Слэш-команды вроде /opsx:propose вводятся в чате coding-агента, команды openspec - в терминале. Если это различие еще не закрепилось, вернитесь к уроку 15.4.

Еще не решили, что именно будете строить? Большинство рецептов получается точнее, если сначала прогнать идею через /opsx:explore. Рецепт 3 показывает это в действии; полное обоснование подхода Explore First - в уроке 15.7.

Карта рецептов:

#	Ситуация	Путь
1	Знаете, что хотите; работа небольшая и самодостаточная	`/opsx:propose` → `/opsx:apply` → `/opsx:archive`
2	Что-то сломано; фикс нужно записать как изменение поведения	тот же путь + требование `MODIFIED`
3	Есть проблема, но нет плана	`/opsx:explore` → `/opsx:propose`
4	Посреди фичи вклинивается срочный фикс	два независимых изменения, `/opsx:apply <change>`
5	Правите код, поведение снаружи не меняется	`skip_specs: true` / `--skip-specs`
6	Сложное или рискованное изменение, нужно ревью по шагам	`/opsx:new` → `/opsx:continue` → `/opsx:ff` → `/opsx:verify`
7	Только установили OpenSpec, хотите почувствовать цикл	`/opsx:onboard`

Если сомневаетесь между точками входа, критерий один: можете ли вы уже сформулировать, что должно получиться. Можете - начинайте с /opsx:propose (рецепты 1, 2, 5). Не можете - сначала /opsx:explore (рецепт 3). Это то же различие, которое подробно разобрано в уроке 15.7.

Рецепт 1. Маленькая фича: быстрый путь

Когда применять: вы знаете, что хотите, и это самодостаточный кусок работы. Самый распространенный рецепт.

Весь цикл - три команды: предложить, реализовать, заархивировать.

Вы:  /opsx:propose add-logout-button

AI:  Создан openspec/changes/add-logout-button/
     ✓ proposal.md — зачем и что делаем
     ✓ specs/      — новое требование и его сценарии
     ✓ design.md   — технический подход
     ✓ tasks.md    — чек-лист реализации
     Готово к реализации. Запустите /opsx:apply.

Теперь прочитайте план: откройте proposal и дельта-спецификацию (delta spec). Это тот момент, ради которого построен OpenSpec: поймать неверное допущение, пока оно занимает один абзац, а не 400 строк кода. Если что-то не так, отредактируйте любой артефакт напрямую и продолжайте.

Вы:  /opsx:apply

AI:  Прохожу по задачам...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     Все задачи выполнены!

Вы:  /opsx:archive

AI:  Архивирую add-logout-button...
     ✓ Спецификации слиты в openspec/specs/auth/spec.md
     ✓ Перемещено в openspec/changes/archive/2026-06-22-add-logout-button/
     Готово. Можно браться за следующее изменение.

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

Путь изменения внутри репозитория:

flowchart LR P["/opsx:propose"] --> R["Ревью плана (proposal + delta spec)"] R --> A["/opsx:apply"] A --> AR["/opsx:archive"] AR --> S["openspec/specs/ living spec"] AR --> H["openspec/changes/archive/ изменение с контекстом"]

Что показывает рецепт 1

Полный цикл умещается в три слэш-команды; промежуточных ритуалов нет.
Пауза между /opsx:propose и /opsx:apply - главная точка контроля: план читают и правят до кода, а не после.
Архивация делает двойную работу: сливает дельту в living spec и сохраняет изменение с полным контекстом в openspec/changes/archive/.

Шпаргалка

/opsx:propose add-logout-button
# прочитать и при необходимости поправить proposal.md и дельта-спецификацию
/opsx:apply
/opsx:archive

Инженерный вывод курса: в коротком ревью плана смотрите в первую очередь на proposal.md (зачем делаем) и дельта-спецификацию (что считается правильным поведением) - именно там живут дорогие ошибки допущений; design.md и tasks.md важны, но проверяются быстрее.

Рецепт 2. Багфикс

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

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

Вы:  /opsx:propose fix-login-redirect-loop

AI:  Создан openspec/changes/fix-login-redirect-loop/
     Proposal отражает текущее сломанное поведение и целевое
     поведение. Дельта-спецификация модифицирует требование
     о редиректе (MODIFIED), так что оно становится точным
     и проверяемым.
     Готово к реализации.

Поскольку фикс попадает в спецификацию как требование с маркером MODIFIED и свежим сценарием, следующий человек (или следующая сессия AI) видит не только то, что вы это починили, но и что означает «правильно». Затем - обычные /opsx:apply и /opsx:archive.

Подсказка из документации: для фикса хороший сценарий - это регрессионный тест, записанный прозой:

GIVEN a logged-out user, WHEN they submit valid credentials,
THEN they land on the dashboard and are not redirected again.

Напишите такой сценарий - и у реализации появится ясная цель.

Что показывает рецепт 2

Механика та же, что у фичи; меняется содержание артефактов.
Формулировка корректного поведения превращает фикс в спецификацию: сценарий фиксирует, что считается исправленным.
Дельта-спецификация работает поверх существующего требования (операция MODIFIED), а не создает новую возможность.

Шпаргалка

/opsx:propose fix-login-redirect-loop
# в дельте: MODIFIED-требование + сценарий-регрессионный тест
/opsx:apply
/opsx:archive

Рецепт 3. Исследование до обязательств

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

Начните с /opsx:explore. Это партнер по размышлениям без жесткой структуры: команда никогда не пишет код и ничего не создает, пока вы сами не попросите зафиксировать результат или не согласитесь, когда агент предложит. Она читает вашу кодовую базу и помогает принять решение.

Вы:  /opsx:explore

AI:  Что хотите исследовать?

Вы:  Страницы грузятся медленно, но непонятно, куда уходит время.

AI:  Посмотрю... Нашел три вероятных виновника:
     1. Большие неоптимизированные изображения в списке товаров
     2. Синхронная загрузка данных, блокирующая отрисовку
     3. Перерисовки из-за изменений контекста
     За что возьмемся первым?

Вы:  Давайте сначала загрузка данных.

Вы:  /opsx:propose optimize-product-list-fetching

AI:  Изменение создано; proposal опирается на то, что мы
     только что нашли. Готово к реализации.

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

Что показывает рецепт 3

/opsx:explore ничего не пишет на диск без явного запроса: исследование не оставляет следов и не налагает обязательств.
Диалог с агентом идет по вашей реальной кодовой базе, а не по абстрактному примеру.
Переход /opsx:explore → /opsx:propose переносит выводы исследования прямо в proposal нового изменения.

Шпаргалка

/opsx:explore
# свободный диалог по кодовой базе; артефакты не создаются
/opsx:propose optimize-product-list-fetching
# дальше - обычный путь: /opsx:apply, /opsx:archive

Рецепт 4. Два изменения параллельно

Когда применять: вы посреди фичи, и срочный фикс перебивает очередь.

Изменения - независимые каталоги, поэтому параллельная работа не конфликтует. Начните фикс, завершите его и вернитесь к фиче ровно там, где остановились.

Вы:  Я на середине add-dark-mode, но сейчас нужно срочно
     починить баг логина.

Вы:  /opsx:propose fix-login-redirect

AI:  Создан openspec/changes/fix-login-redirect/. Готово к реализации.

Вы:  /opsx:apply

AI:  Фикс реализован. Все задачи выполнены.

Вы:  /opsx:archive

AI:  ✓ Заархивировано: fix-login-redirect.

Вы:  Возвращаемся к темной теме.

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

AI:  Возобновляю add-dark-mode. Продолжаю с задачи 2.3: Update Header...

Указание имени изменения в /opsx:apply add-dark-mode - способ направить агента на конкретное изменение, когда активны несколько. Благодаря тому, что выполнение отмечается в tasks.md, агент точно знает, где вы остановились.

Схема переключения между двумя изменениями:

flowchart TD F["add-dark-mode (в работе, задача 2.3)"] -->|"срочный фикс"| P["/opsx:propose fix-login-redirect"] P --> A1["/opsx:apply"] --> AR1["/opsx:archive"] AR1 -->|"возврат к фиче"| A2["/opsx:apply add-dark-mode продолжение с задачи 2.3"]

Когда завершены сразу несколько изменений, расширенная команда /opsx:bulk-archive разбирает их вместе и разрешает конфликты спецификаций, проверяя, что реально реализовано. Подробнее о параллельных изменениях - в уроке 15.8.

Что показывает рецепт 4

Каждое изменение - отдельный каталог в openspec/changes/; переключение между ними не требует веток или стэшинга.
tasks.md хранит прогресс, поэтому возобновление - это продолжение с конкретной задачи, а не пересказ контекста.
Имя изменения в /opsx:apply выбирает активное изменение, когда их несколько.

Шпаргалка

/opsx:propose fix-login-redirect
/opsx:apply
/opsx:archive
/opsx:apply add-dark-mode
# несколько завершенных изменений разбирает: /opsx:bulk-archive

Рецепт 5. Рефакторинг без изменения поведения

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

Это самый интересный случай: у чистого рефакторинга нечего добавлять в спецификации. Контракт поведения не меняется - меняется только реализация. Поэтому работа живет в design и tasks, а дельта-спецификация пуста или отсутствует.

Вы:  /opsx:propose refactor-payment-module

AI:  Изменение создано. Proposal формулирует цель (разделить
     платежный модуль, поведение не меняется), design описывает
     новую структуру. Спецификации не меняются, так как поведение
     идентично. Готово к реализации.

Пустую дельту нужно объявить явно - флагом skip_specs: true в файле .openspec.yaml изменения:

yaml
schema: spec-driven
skip_specs: true

Без маркера openspec validate отклоняет изменение без единой дельты (так что забытый этап specs все равно будет замечен); с маркером валидация проходит, а openspec status показывает этап specs как явно пропущенный, а не ожидающий. Если рефакторинг все же меняет поведение, удалите skip_specs из .openspec.yaml и напишите дельта-спецификации: валидация считает маркер вместе с файлами спецификаций конфликтом, поэтому устаревший маркер не сможет тихо остаться.

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

bash
$ openspec archive refactor-payment-module --skip-specs

Тот же флаг удобен для тулинга, CI и docs-only изменений. Принцип простой: спецификации описывают поведение, поэтому если поведение не изменилось, спецификация тоже не должна меняться. Подробнее о том, чем спецификация является и чем не является, - в уроке 15.3.

Что показывает рецепт 5

Не всякое изменение порождает дельту: рефакторинг остается в design.md и tasks.md.
Пропуск спецификаций - осознанное решение, зафиксированное в .openspec.yaml, а не умолчание.
Валидация защищает с обеих сторон: пустая дельта без маркера - ошибка, но и маркер вместе с файлами спецификаций - конфликт.

Шпаргалка

/opsx:propose refactor-payment-module
# в .openspec.yaml изменения: skip_specs: true
/opsx:apply
/opsx:archive
# эквивалент в терминале: openspec archive <change> --skip-specs

Рецепт 6. Пошаговый контроль (расширенные команды)

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

Core-команда /opsx:propose готовит все артефакты разом. Если удобнее двигаться по шагам, включите расширенные команды:

bash
$ openspec config profile      # выбрать расширенные workflow
$ openspec update              # применить их к этому проекту

Теперь план можно собирать постепенно:

Вы:  /opsx:new add-2fa

AI:  Создан openspec/changes/add-2fa/. Следующий шаг: proposal.

Вы:  /opsx:continue

AI:  Создан proposal.md. Теперь доступны: specs, design.

Вы:  /opsx:continue

AI:  Создан specs/auth/spec.md. Теперь доступен: design.

Ревьюьте каждый артефакт по мере появления, правьте свободно и продолжайте, когда довольны результатом. Когда захотите достроить план одним заходом, /opsx:ff промотает оставшиеся планировочные артефакты. Перед архивацией /opsx:verify проверит, что реализация действительно соответствует спецификациям. Подробнее о соотношении /opsx:ff и /opsx:continue - в уроке 15.8.

Что показывает рецепт 6

Расширенный профиль переключается на уровне проекта: openspec config profile плюс openspec update.
/opsx:new создает каркас изменения, /opsx:continue добавляет артефакты по одному.
/opsx:ff и /opsx:verify закрывают цикл: быстро достроить план и сверить код со спецификацией перед архивацией.

Шпаргалка

bash
openspec config profile
openspec update

/opsx:new add-2fa
/opsx:continue        # повторять по шагам: proposal → specs → design
/opsx:ff              # достроить оставшиеся артефакты одним заходом
/opsx:apply
/opsx:verify          # сверить реализацию со спецификациями
/opsx:archive

Рецепт 7. Изучение всего цикла на собственном коде

Когда применять: вы установили OpenSpec и хотите прочувствовать workflow на своем коде, а не на игрушечном примере.

Включите расширенные команды (рецепт 6), затем:

Вы:  /opsx:onboard

AI:  Добро пожаловать в OpenSpec! Проведу вас через полное
     изменение на вашей реальной кодовой базе. Поищу небольшое
     безопасное улучшение, которое можно сделать вместе...

/opsx:onboard находит настоящее (небольшое) улучшение, создает для него изменение, реализует и архивирует, комментируя каждый шаг. Это занимает 15-30 минут и оставляет вам реальное изменение, которое можно оставить или выбросить. Самый мягкий способ освоить цикл. Полное описание команды - в справочнике урока 15.5.

Что показывает рецепт 7

Полный цикл propose → apply → archive можно пройти без выдуманного учебного проекта - на вашей кодовой базе.
Результат onboard - настоящее изменение в репозитории; оставить его или выбросить, решаете вы.
Команда рассчитана на первое знакомство и не требует знания остальных рецептов.

Шпаргалка

# предварительно: расширенные команды из рецепта 6
/opsx:onboard

Проверка состояния из терминала

В любой момент состояние дел можно посмотреть из терминала:

bash
$ openspec list                      # активные изменения
$ openspec show add-dark-mode        # одно изменение подробно
$ openspec validate add-dark-mode    # проверка структуры
$ openspec view                      # интерактивный дашборд

Это инструменты чтения и инспекции: они не меняют состояние проекта, а только показывают его. Их можно запускать в любой момент - например, openspec list как быструю проверку того, что сейчас в работе, или openspec validate как контроль структуры перед архивацией. Предложение и реализация по-прежнему происходят через слэш-команды в чате агента. Полный справочник CLI - в уроке 15.6.

Практика

Пройдите рецепт 1 на настоящем (но небольшом) изменении в тестовом проекте:

Выберите маленькую фичу - например, кнопку, ссылку или фильтр, которых еще нет. Придумайте change-id вида add-<что-то>.
Выполните /opsx:propose <change-id> и прочитайте все созданные артефакты: proposal.md, дельта-спецификацию, design.md, tasks.md.
Найдите хотя бы одну формулировку, которую поправили бы, и отредактируйте артефакт напрямую.
В терминале выполните openspec list (изменение активно) и openspec validate <change-id>.
Вернитесь в чат: /opsx:apply, затем /opsx:archive.
Снова выполните openspec list - активных изменений нет; загляните в openspec/changes/archive/ и в living spec, куда слилась дельта.
Ответьте себе: какой из семи рецептов ближе к вашей текущей рабочей задаче? Начали бы вы с /opsx:explore или сразу с /opsx:propose - и почему?

Если хочется продолжить: включите расширенный профиль (рецепт 6) и запустите /opsx:onboard, чтобы пройти цикл на изменении, которое агент найдет сам.

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

Рецепты покрывают повседневный спектр работы с OpenSpec - от маленькой фичи до рефакторинга - и все опираются на один и тот же цикл propose → apply → archive; различаются содержание артефактов и несколько явных флагов.

Маленькая фича - три команды: /opsx:propose, /opsx:apply, /opsx:archive; план читают и правят между propose и apply.
Багфикс формулируется как корректное поведение: MODIFIED-требование со сценарием-регрессионным тестом.
/opsx:explore исследует кодовую базу без обязательств; выводы переносятся в последующий proposal.
Изменения независимы: /opsx:apply <change> возобновляет нужное, /opsx:bulk-archive разбирает несколько сразу.
Рефакторинг без изменения поведения - skip_specs: true в .openspec.yaml или флаг --skip-specs; пустая дельта без маркера не пройдет валидацию.
Расширенный профиль дает пошаговый контроль (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify) и команду /opsx:onboard для первого знакомства.
openspec list, show, validate, view - инспекция из терминала; сама работа идет в чате агента.

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

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

Почему для багфикса предлагается описывать корректное поведение, а не сам баг? Что это дает следующему человеку или следующей сессии агента?
Что /opsx:explore делает с кодовой базой и чего принципиально не делает без вашего запроса?
Как указать агенту, какое из нескольких активных изменений продолжать, и откуда агент узнает, где вы остановились?
Что произойдет при openspec validate для изменения без единой дельты: с флагом skip_specs: true и без него? А если у изменения есть и маркер, и файлы спецификаций?
Чем пара /opsx:new + /opsx:continue отличается от /opsx:propose, и когда расширенный набор команд оправдан?
Почему openspec list/show/validate/view не могут заменить работу в чате агента?

Что дальше

Рецепты показывают, где в цикле проверять план. Урок 15.10 «Написание, ревью и редактирование изменений» отвечает на вопрос, как делать это хорошо: формат сильных requirement и scenario (SHALL/WHEN/THEN), правильный размер изменения, двухминутное ревью свежего плана, правка артефактов и откат назад.

Материалы, на которые ссылаются рецепты, в пересчете на уроки модуля: Explore First - 15.7, workflow-паттерны - 15.8, справочник слэш-команд - 15.5, канонический walkthrough первого изменения - 15.2, устройство specs и deltas - 15.3.

Источники

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