Рабочие процессы

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

Философия: Действия, а не фазы

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

OPSX использует другой подход:

Традиционные (с фиксированными фазами):

  ПЛАНИРОВАНИЕ ────────► РЕАЛИЗАЦИЯ ────────► ЗАВЕРШЕНО
      │                    │
      │   «Нельзя вернуться назад»  │
      └────────────────────┘

OPSX (гибкие действия):

  proposal ──► specs ──► design ──► tasks ──► implement

Ключевые принципы:

• Действия, а не фазы — команды — это то, что вы можете делать, а не стадии, в которых вы застряли
• Зависимости расширяют возможности, а не задают порядок действий — они показывают, что вы можете сделать, а не что нужно делать следующим

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

Два режима работы

Стандартный быстрый путь (профиль core)

При новой установке по умолчанию используется профиль core, который включает следующие команды:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:sync
• /opsx:archive

Типичный поток работы:

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (опционально)

Начните с исследования (привычка, которая стоит выработать)

/opsx:explore входит в стандартный профиль, а не является дополнительным расширенным компонентом. Эту команду стоит использовать, когда у вас есть проблема, но еще нет готового плана — а с ИИ-ассистентом это происходит в большинстве случаев.

Вы: /opsx:explore

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

Вы: Результаты поиска у нас устарели. Не уверен, в чем причина: в кэшировании,
     индексации или в самом запросе.

ИИ:  Давайте посмотрю... [читает код сервиса поиска и слоя кэширования]
     Проблема в индексе: он перестраивается только раз в сутки, поэтому правки
     появляются только на следующий день. Два варианта решения: перестраивать
     при записи (просто, но больше нагрузки) или инвалидация кэша с коротким
     TTL (больше движущихся частей, меньше нагрузки). Учитывая ваш низкий
     объем записей, перестройка при записи — более чистое решение. Хотите
     ограничить область изменений?

Вы: Да.

Вы: /opsx:propose rebuild-search-index-on-write

Исследование не создает артефактов и не генерирует код. Это бесплатная беседа без рисков, которая превращает неясное опасение в точное изменение, поэтому последующее предложение будет четким. Уже точно знаете, что хотите сделать? Пропустите этот шаг и переходите сразу к /opsx:propose. Полное руководство: Explore First.

Расширенный/полный рабочий процесс (выборочная настройка)

Если вам нужны явные команды для создания каркаса и сборки (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), включите их с помощью:

openspec config profile
openspec update

Шаблоны рабочего процесса (расширенный режим)

Быстрое добавление функции

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

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Пример диалога:

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

ИИ:  Создана папка openspec/changes/add-logout-button/
     Готово к созданию: предложение

Вы: /opsx:ff

ИИ:  Создание всех артефактов планирования...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Готово к реализации!

Вы: /opsx:apply

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

Вы: /opsx:archive

ИИ:  ✓ Объединены спецификации
     ✓ Изменение перемещено в архив

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

Исследовательский режим

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

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Пример диалога:

Вы: /opsx:explore

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

Вы: Я хочу улучшить скорость загрузки страниц, но не знаю,
     где находятся узкие места.

ИИ:  Давайте я помогу разобраться...
     [Анализирует размеры бандлов, находит медленные запросы, проверяет
     паттерны рендеринга компонентов]

     Я нашел три основных узких места:
     1. Большие неоптимизированные изображения
     2. Синхронная загрузка данных в ProductList
     3. Повторные рендеры из-за изменений контекста

     С каким из них вы хотите разобраться в первую очередь?

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

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

ИИ:  Изменение создано. Готово к созданию: предложение

Вы: /opsx:continue

ИИ:  Создание предложения на основе нашего исследования...
     [Формирует предложение с учетом результатов исследования]

     Готово к созданию: спецификации, дизайн
     Что дальше?

Вы: /opsx:continue

ИИ:  Создание спецификаций...

Подходит для: Оптимизации производительности, отладки, принятия архитектурных решений, неясных требований.

Параллельные изменения

Работайте над несколькими изменениями одновременно:

Изменение A: /opsx:new ──► /opsx:ff ──► /opsx:apply (в процессе)
                                         │
                                    переключение контекста
                                         │
Изменение B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Пример диалога:

Вы: Я работаю над add-dark-mode, но меня отвлекли на исправление ошибки

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

ИИ:  Создана папка openspec/changes/fix-login-redirect/

Вы: /opsx:ff

ИИ:  ✓ Артефакты планирования созданы

Вы: /opsx:apply

ИИ:  Работа над fix-login-redirect...
     [Реализует исправление]
     Все задачи выполнены!

Вы: /opsx:archive

ИИ:  ✓ fix-login-redirect перемещен в архив

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

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

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

Подходит для: Параллельных рабочих потоков, срочных отвлекающих задач, совместной работы в команде.

Когда у вас есть несколько завершенных изменений, используйте /opsx:bulk-archive:

Вы: /opsx:bulk-archive

ИИ:  Найдено 3 завершенных изменения:
     - add-dark-mode (все задачи выполнены)
     - fix-login-redirect (все задачи выполнены)
     - update-footer (все задачи выполнены)

     Проверка на конфликты спецификаций...
     ⚠ add-dark-mode и update-footer затрагивают specs/ui/

     Анализ кодовой базы для разрешения конфликта...
     Оба изменения реализованы. Они будут применены в хронологическом порядке.

     Переместить все 3 изменения в архив?

Вы: Да

ИИ:  ✓ add-dark-mode перемещен в архив
     ✓ fix-login-redirect перемещен в архив
     ✓ update-footer перемещен в архив
     Спецификации объединены в порядке: add-dark-mode → update-footer

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

Завершение изменения

Рекомендуемый поток завершения:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              проверяет          запрашивает синхронизацию
              реализацию         при необходимости

Проверка: Контроль вашей работы

/opsx:verify проверяет реализацию на соответствие артефактам по трем направлениям:

Вы: /opsx:verify

ИИ:  Проверка add-auth...

     ПОЛНОТА
     ✓ Все 12 задач из tasks.md выполнены
     ✓ Все требования из спецификаций имеют соответствующий код
     ⚠ Сценарий "Завершение сессии после периода неактивности" не протестирован

     КОРРЕКТНОСТЬ
     ✓ Реализация соответствует замыслу спецификации
     ✓ Крайние случаи из сценариев обработаны
     ✓ Состояния ошибок соответствуют определениям в спецификации

     СОГЛАСОВАННОСТЬ
     ✓ Архитектурные решения отражены в структуре кода
     ✓ Соглашения об именовании соответствуют design.md
     ⚠ В дизайне указан событийный подход, но в реализации используется опрос

     ИТОГИ
     ─────────────────────────────
     Критические проблемы: 0
     Предупреждения: 2
     Готово к архивированию: Да (с предупреждениями)

     Рекомендации:
     1. Добавить тест для сценария завершения сессии
     2. Рассмотреть рефакторинг под событийный подход, как указано в дизайне, или обновить design.md

Что проверяет команда verify:

Направление	Что проверяется
Полнота	Все задачи выполнены, все требования реализованы, все сценарии покрыты
Корректность	Реализация соответствует замыслу спецификации, обработаны крайние случаи
Согласованность	Архитектурные решения отражены в коде, паттерны использования согласованы

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

Архивирование: Завершение изменения

/opsx:archive завершает изменение и перемещает его в архив:

Вы: /opsx:archive

ИИ:  Архивирование add-auth...

     Статус артефактов:
     ✓ proposal.md существует
     ✓ specs/ существует
     ✓ design.md существует
     ✓ tasks.md существует (12/12 задач выполнены)

     Дельта спецификаций: еще не синхронизирована с основной веткой
     → Хотите синхронизировать сейчас?

Вы: Да

ИИ:  ✓ Спецификации синхронизированы с openspec/specs/auth/spec.md
     ✓ Перемещено в openspec/changes/archive/2025-01-24-add-auth/

     Изменение успешно архивировано.

При отсутствии синхронизации спецификаций архивирование запросит подтверждение. Оно не блокируется из-за невыполненных задач, но вы получите предупреждение.

Когда что использовать

/opsx:ff против /opsx:continue

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

Правило большого пальца: Если вы можете описать полный объем работ заранее, используйте /opsx:ff. Если вы определяете его по ходу дела, используйте /opsx:continue.

Когда обновлять существующее изменение, а когда создавать новое

Частый вопрос: в каких случаях можно обновлять существующее изменение, а в каких стоит создавать новое?

Обновляйте существующее изменение, если:

• Одинаковая цель, уточненная реализация
• Объем работ сужается (сначала MVP, остальное позже)
• Исправления на основе новых знаний (кодовая база оказалась не такой, как ожидалось)
• Корректировки дизайна на основе открытий в процессе реализации

Создавайте новое изменение, если:

• Цель принципиально изменилась
• Объем работ разросся до совершенно другой задачи
• Исходное изменение может быть помечено как "завершенное" самостоятельно
• Правки будут больше запутывать, чем прояснять

                     ┌─────────────────────────────────────┐
                     │     Это та же работа?               │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Одинаковая цель?     >50% совпадения?    Исходное изменение
          Одинаковая проблема?  Одинаковый объем?  может быть завершено
                 │                  │          без этих правок?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      ДА                НЕТ ДА           НЕТ  НЕТ            ДА
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    ОБНОВИТЬ         НОВОЕ ОБНОВИТЬ     НОВОЕ ОБНОВИТЬ       НОВОЕ

Пример: "Добавление темной темы"

• "Нужно также добавить поддержку пользовательских тем" → Новое изменение (объем разросся)
• "Определение системных настроек оказалось сложнее, чем ожидалось" → Обновление (та же цель)
• "Сначала выпустим переключатель, поддержку настроек добавим позже" → Сначала обновить, архивировать, потом создать новое изменение

Рекомендации

Держите изменения сфокусированными

Одна логическая единица работы на изменение. Если вы делаете "добавление функции X и одновременно рефакторинг Y", подумайте о создании двух отдельных изменений.

Почему это важно:

• Проще проверять и понимать
• Более чистая история архива
• Можно выпускать независимо друг от друга
• Проще откатить при необходимости

Используйте /opsx:explore при неясных требованиях

Прежде чем приступать к изменению, исследуйте проблемную область:

Вы: /opsx:explore

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

Вы: Как нам реализовать ограничение запросов для нашего API?

ИИ:  Давайте я изучу вашу текущую конфигурацию и возможные варианты...
     [Изучает кодовую базу, анализирует паттерны]

     Я вижу три возможных подхода:
     1. На основе middleware (простой, для каждого эндпоинта отдельно)
     2. С использованием Redis (масштабируемый, общее состояние)
     3. Ведро токенов на пользователя (справедливый, сложный)

     Ваш текущий стек предполагает вариант 1 или 2. Какой у вас масштаб?

Исследование проясняет мысли перед созданием артефактов.

Проверяйте перед архивированием

Используйте /opsx:verify, чтобы проверить соответствие реализации артефактам:

Вы: /opsx:verify

ИИ:  Проверка add-dark-mode...

     ✓ Все задачи из tasks.md выполнены
     ✓ Все требования из спецификаций имеют соответствующий код
     ✓ Архитектурные решения отражены в реализации

     Готово к архивированию!

Обнаруживает несоответствия до завершения изменения.

Давайте изменениям понятные имена

Хорошие имена делают команду openspec list полезной:

Хорошо:	Избегайте:
add-dark-mode	feature-1
fix-login-redirect	update
optimize-product-query	changes
implement-2fa	wip

Быстрая справка по командам

Полное описание команд и их параметров смотрите в разделе Команды.

Команда	Назначение	Когда использовать
/opsx:propose	Создание изменений и артефактов планирования	Быстрый путь по умолчанию (профиль core)
/opsx:explore	Обсуждение идей с ИИ	Начните с этой команды, если не уверены: неясные требования, исследование, сравнение вариантов
/opsx:new	Создание каркаса изменения	Расширенный режим, явный контроль над артефактами
/opsx:continue	Создание следующего артефакта	Расширенный режим, пошаговое создание артефактов
/opsx:ff	Создание всех артефактов планирования	Расширенный режим, понятный объём работ
/opsx:apply	Выполнение задач	Готовность к написанию кода
/opsx:verify	Проверка реализации	Расширенный режим, перед архивацией
/opsx:sync	Синхронизация дельта-спецификаций	Расширенный режим, опционально
/opsx:archive	Архивирование изменения	Все работы завершены
/opsx:bulk-archive	Массовое архивирование изменений	Расширенный режим, параллельная работа

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

• Написание качественных спецификаций — как выглядят сильные требования и сценарии, и как правильно определить объём изменения
• Проверка изменения — быстрая двухминутная проверка готового плана перед началом написания кода
• Использование OpenSpec в команде — как изменения соотносятся с ветками и pull-запросами
• Команды — полная справка по командам с описанием параметров
• Концепции — подробное описание спецификаций, артефактов и схем
• Настройка — создание пользовательских рабочих процессов