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

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

Прежде чем начать, напомним: slash-команды вроде /opsx:propose вводятся в чате с ИИ-ассистентом, а команды openspec — в терминале. Если это для вас ново, сначала прочитайте Как работают команды. В примерах ниже Вы: и ИИ: обозначают чат, а строки, начинающиеся с $, — терминал.

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

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

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

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

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

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

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

Вы: /opsx:apply

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

Вы: /opsx:archive

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

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

Рецепт 2: исправление ошибки

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

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

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

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

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

Совет: для исправления хорошим сценарием будет регрессионный тест, записанный словами. «GIVEN: пользователь не вошёл в систему; WHEN: он отправляет правильные учётные данные; THEN: он попадает на панель управления, и повторного перенаправления не происходит». Запишите это — и у реализации появится чёткая цель.

Рецепт 3: исследование до начала работы

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

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

Вы: /opsx:explore

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

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

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

Вы: С получения данных.

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

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

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

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

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

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

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

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

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

Вы: /opsx:apply

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

Вы: /opsx:archive

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

Вы: Вернёмся к тёмной теме.

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

ИИ:  Возобновляю add-dark-mode с задачи 2.3: обновить Header...

Если активно несколько изменений, укажите имя в /opsx:apply add-dark-mode, чтобы направить ИИ к конкретному изменению. Выполненные задачи отмечаются в tasks.md, поэтому ИИ точно знает, на чём вы остановились.

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

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

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

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

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

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

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

schema: spec-driven
skip_specs: true

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

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

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

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

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

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

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

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

Теперь можно создавать каркас и заполнять его постепенно:

Вы: /opsx:new add-2fa

ИИ:  Создана папка openspec/changes/add-2fa/. Готово к созданию: proposal.

Вы: /opsx:continue

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

Вы: /opsx:continue

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

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

Рецепт 7: практическое освоение всего цикла

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

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

Вы: /opsx:onboard

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

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

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

Состояние проекта можно проверить в терминале в любое время:

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

Эти команды предназначены для чтения и проверки. Предложения и реализация изменений по-прежнему выполняются с помощью slash-команд в чате. Подробности см. в справочнике CLI.

Что дальше

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