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

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

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

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

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

Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

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

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

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

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

Два Режима

Быстрый Стандартный Путь (core profile)

Новые установки по умолчанию используют 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

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

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

AI:  Позвольте мне посмотреть... [анализирует поисковую службу и уровень кэширования]
     Проблема в индексе: он перестраивается только ночью, поэтому изменения отображаются не раньше следующего дня. Есть два варианта: перестройка при записи (просто, но больше нагрузки) или инвалидация кеша с коротким 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

AI:  Создана openspec/changes/add-logout-button/
     Готов создать: proposal

Вы: /opsx:ff

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

Вы: /opsx:apply

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

Вы: /opsx:archive

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

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

Исследовательский Режим (Exploratory)

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

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

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

Вы: /opsx:explore

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

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

AI:  Позвольте мне помочь с расследованием...
     [Анализирует размеры бандлов, определяет медленные запросы, просматривает паттерны рендеринга компонентов]

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

     Какую проблему вы хотели бы решить в первую очередь?

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

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

AI:  Создано изменение. Готов создать: proposal

Вы: /opsx:continue

AI:  Создаю предложение на основе нашего исследования...
     [Пишет предложение, включающее результаты расследования]

     Готов создать: specs, design
     Что вы хотите сделать дальше?

Вы: /opsx:continue

AI:  Создаю спецификации...

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

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

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

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

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

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

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

AI:  Создана openspec/changes/fix-login-redirect/

Вы: /opsx:ff

AI:  ✓ Созданы планировочные артефакты

Вы: /opsx:apply

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

Вы: /opsx:archive

AI:  ✓ Изменение fix-login-redirect заархивировано

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

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

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

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

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

Вы: /opsx:bulk-archive

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

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

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

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

Вы: Да

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

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

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

Рекомендуемый рабочий процесс завершения:

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

Проверка (Verify): Проверьте свою работу

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

Вы: /opsx:verify

AI:  Проверяю add-auth...

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

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

     СОГЛАСОВАНИЕ (COHERENCE)
     ✓ Решения по дизайну отражены в структуре кода
     ✓ Согласованность названий с design.md
     ⚠ Дизайн упоминает "event-driven", но реализация использует опросы (polling)

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

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

Что проверяет Verify:

Измерение	Что проверяется
Полнота (Completeness)	Все задачи выполнены, все требования реализованы, сценарии покрыты
Корректность (Correctness)	Реализация соответствует замыслу спецификации, обработаны крайние случаи
Согласование (Coherence)	Решения по дизайну отражены в коде, паттерны согласованы

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

Архивирование (Archive): Финализация Изменения

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

Вы: /opsx:archive

AI:  Архивирую add-auth...

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

     Delta specs: Еще не синхронизированы с основной веткой
     → Хотите ли вы синхронизировать сейчас?

Вы: Да

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

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

Archive предложит синхронизацию, если спецификации не синхронизированы. Оно не будет блокировать из-за незавершенных задач, но предупредит об этом.

Когда Что Использовать

/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

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

Вы: Как нам следует обрабатывать ограничение скорости (rate limiting) для нашего API?

AI:  Позвольте мне изучить вашу текущую настройку и варианты...
     [Исследует кодовую базу, рассматривает паттерны]

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

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

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

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

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

Вы: /opsx:verify

AI:  Проверяю add-dark-mode...

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

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

Это ловит несоответствия до того, как вы закрываете изменение.

Четко Называйте Изменения

Хорошие названия делают openspec list полезным:

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

Краткий справочник команд

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

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

Следующие шаги

• Команды - Полная справочная информация по командам и опциям
• Концепции - Глубокое изучение спецификаций, артефактов и схем
• Кастомизация - Создание пользовательских рабочих процессов