Примеры и рецепты

Реальные изменения: от начала до конца. Каждый рецепт демонстрирует команды, которые вы вводите, и то, что вы видите в ответ, чтобы вы могли сопоставить свою ситуацию с шаблоном и скопировать его. Здесь используются стандартные команды core (propose, explore, apply, sync, archive); если расширенный набор команд полезен, это указано.

Напоминание перед началом: слеш-команды, такие как /opsx:propose, вводятся в чат AI-ассистента, а команды openspec — в терминале. Если вы к этому непривыкли, сначала прочитайте Как работают команды. В приведенных ниже транскриптах You: и AI: — это чат, а строки, начинающиеся с $, — терминал.

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

Рецепт 1: Небольшая фича, быстрый путь

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

Всё сводится к трём командам. Предложить, построить, заархивировать.

You: /opsx:propose add-logout-button

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

Теперь прочтите план. Откройте предложение и дельта-спецификацию. Это момент, для которого создан OpenSpec: поймать неверное предположение, пока оно всего лишь один абзац, а не 400 строк кода. Отредактируйте любой артефакт напрямую, если что-то не так, а затем продолжайте.

You: /opsx:apply

AI:  Выполняю задачи...
     ✓ 1.1 Добавить кнопку выхода в шапке
     ✓ 1.2 Очистить сессию при клике
     ✓ 1.3 Добавить диалоговое окно подтверждения
     Все задачи выполнены!

You: /opsx:archive

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

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

Рецепт 2: Исправление ошибки (багфикс)

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

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

You: /opsx:propose fix-login-redirect-loop

AI:  Создан openspec/changes/fix-login-redirect-loop/
     Предложение фиксирует текущее некорректное поведение и
     преднамеренное поведение. Дельта-спецификация ИЗМЕНЯЕТ требование
     редиректа, делая его точным и тестируемым.
     Готов к реализации.

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

Совет: для исправления ошибки хорошим сценарием является регрессионный тест в прозе. «ДАНО: пользователь вышел из системы, КОГДА: он отправляет действительные учетные данные, ТО: он попадает на дашборд и больше не перенаправляется». Напишите это, и у реализации будет четкая цель.

Рецепт 3: Исследование перед коммитом

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

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

You: /opsx:explore

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

You: Страницы загружаются медленно, но я не знаю, где теряется время.

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

You: То, что касается получения данных.

You: /opsx:propose optimize-product-list-fetching

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

Исследование проясняет ваше мышление до того, как вы потратите на это изменение. Когда инсайт кристаллизуется, предложите его, и AI продолжит контекст.

Рецепт 4: Управление двумя изменениями одновременно

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

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

You: Я на середине работы над add-dark-mode, но мне нужно срочно исправить баг входа.

You: /opsx:propose fix-login-redirect

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

You: /opsx:apply

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

You: /opsx:archive

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

You: Возвращаюсь к темной теме.

You: /opsx:apply add-dark-mode

AI:  Возобновление работы над add-dark-mode. Возобновляю с задачи 2.3: Обновить шапку...

Название изменения в /opsx:apply add-dark-mode — это способ указать AI на конкретное изменение, когда активно несколько. Поскольку задачи отслеживают завершение в tasks.md, AI точно знает, где вы остановились.

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

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

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

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

You: /opsx:propose refactor-payment-module

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

Когда вы архивируете изменение, которое не затрагивает спецификации, вы можете указать терминальной команде пропустить шаг спецификаций:

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

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

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

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

Основная /opsx:propose черновик всех сразу. Когда вы предпочитаете идти шаг за шагом, включите расширенные команды:

$ openspec config profile      # Выберите расширенные рабочие процессы
$ openspec update              # Примените их к этому проекту

Теперь вы можете постепенно создавать и строить:

You: /opsx:new add-2fa

AI:  Создан openspec/changes/add-2fa/. Готов создать: proposal.

You: /opsx:continue

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

You: /opsx:continue

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

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

Рецепт 7: Обучение на всем цикле вживую

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

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

You: /opsx:onboard

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

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

Проверка работы через терминал

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

$ openspec list                      # Активные изменения
$ openspec show add-dark-mode        # Одно изменение в деталях
$ openspec validate add-dark-mode    # Проверка структуры
$ openspec view                      # Интерактивная панель управления

Это инструменты для чтения и инспекции. Предложение и построение по-прежнему происходят через слеш-команды в чате. Полные детали см. в CLI справочнике.

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

• Explore First: Рекомендуемый способ начала, если вы не уверены
• Workflows: Шаблоны выше с руководством по принятию решений о том, когда какой использовать
• Commands: Каждая слеш-команда в деталях
• Getting Started: Основной пошаговый обзор первого изменения
• Concepts: Почему части складываются именно так