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

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

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

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

Рецепт 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:  Создано изменение. Предложение формулирует цель (разделить платёжный
     модуль, без изменения поведения), а дизайн описывает новую структуру.
     Изменений спецификаций нет, так как поведение идентично.
     Готово к реализации.

Явно объявите пустую дельту, установив skip_specs: true в .openspec.yaml изменения:

schema: spec-driven
skip_specs: true

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

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

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

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

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

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

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

$ openspec config profile      # выберите расширенный рабочий процесс (expanded workflows)
$ 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.

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

• Сначала исследуй: рекомендуемый способ начать, когда вы не уверены
• Рабочие процессы: приведённые выше шаблоны с рекомендациями, когда какой использовать
• Команды: все слэш-команды подробно
• Начало работы: каноническое пошаговое руководство по первому изменению
• Концепции: почему части складываются именно так