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

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

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

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

OPSX предлагает иной подход:

Традиционный (привязанный к этапам):

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

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

  предложение ──► спецификации ──► дизайн ──► задачи ──► реализация

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

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

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

Два режима

Путь по умолчанию (профиль core)

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

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

Типичный процесс:

/opsx:propose ──► /opsx:apply ──► /opsx:archive

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

Если вам нужны явные команды для создания и сборки (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:sync, /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:  ✓ Спецификации объединены
     ✓ Изменение архивировано

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

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

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

/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:  Создание proposal на основе нашего исследования...
     [Пишет proposal, включая результаты исследования]

     Готово к созданию: specs, design
     Что бы вы хотели создать следующим?

Вы: /opsx:continue

AI:  Создание specs...

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

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

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

Изменение 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: Обновление Header...

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

Когда у вас есть несколько завершенных изменений, используйте /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

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

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

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

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

Verify: Проверка вашей работы

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

Вы: /opsx:verify

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

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

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

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

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

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

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

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

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

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

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

Вы: /opsx:archive

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

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

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

Вы: Да

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

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

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

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

/opsx:ff vs /opsx:continue

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

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

Когда обновлять, а когда начинать заново

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

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

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

Начинайте новое изменение, когда:

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

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

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

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

Лучшие практики

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

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

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

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

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

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

Вы: /opsx:explore

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

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

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

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

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

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

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

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

Вы: /opsx:verify

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

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

     Готово к архивации!

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

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

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

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

## Краткая справочная информация по командам

Полные сведения о командах и параметрах см. в разделе [Команды](commands.md).

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

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

- [Команды](commands.md) - Полная справочная информация по командам с параметрами
- [Концепции](concepts.md) - Подробное описание спецификаций, артефактов и схем
- [Настройка](customization.md) - Создание пользовательских рабочих процессов