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

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

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

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

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

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

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

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

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

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

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

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

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

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

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

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

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

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

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

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

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

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

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

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

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

Рецепт 4: Параллельная работа над несколькими изменениями

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

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

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

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

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

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

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

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

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      # выбрать расширенные рабочие процессы
$ openspec update              # применить их к текущему проекту

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

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

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

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

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

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

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

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

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

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

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

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

Дальнейшие шаги

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