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

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

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

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

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

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

  ПЛАНИРОВАНИЕ ────────► РЕАЛИЗАЦИЯ ────────► ГОТОВО
      │                    │
      │   «Назад дороги нет»  │
      └────────────────────┘

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

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

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

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

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

Обзор рабочего процесса

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

flowchart TD
    Idea["Идея или проблема"] --> Explore["/opsx:explore<br/>(необязательно)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Артефакты планирования<br/>готовы?"}
    Review -->|"Уточнить"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Реализовать"| Apply["/opsx:apply"]
    Apply -->|"План изменен"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(необязательно, выборочно)"]
    Apply --> Sync["/opsx:sync<br/>(необязательно перед архивированием)"]
    Verify --> Verified{"Готово к архивированию?"}
    Verified -->|"Исправить реализацию"| Apply
    Verified -->|"Пересмотреть план"| Update
    Verified -->|"Готово"| Sync
    Verified -->|"Готово"| Archive
    Sync --> Archive

ИИ-ассистент управляет рабочим процессом, тогда как CLI предоставляет детерминированную структуру, статус и инструкции по работе с артефактами:

sequenceDiagram
    actor Human
    participant Assistant as ИИ-ассистент
    participant CLI as OpenSpec CLI
    participant Files as Файлы планирования и реализации

    Human->>Assistant: /opsx:propose "изменение"
    Assistant->>CLI: openspec new change
    CLI->>Files: Создание метаданных изменения
    Assistant->>CLI: Запрос статуса и инструкций по артефактам
    CLI-->>Assistant: Порядок сборки, пути и шаблоны
    Assistant->>Files: Запись артефактов планирования согласно схеме
    Assistant-->>Human: Представление артефактов на проверку

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Запрос инструкций для применения
    CLI-->>Assistant: Контекстные файлы и состояние задач
    Assistant->>Files: Выполнение задач и обновление чекбоксов
    Assistant-->>Human: Отчет о состоянии реализации

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Запрос входных данных для архивирования и статуса артефактов
    CLI-->>Assistant: Пути планирования и завершенность артефактов
    Assistant->>Files: Чтение состояния задач и сравнение дельта-спецификаций
    opt Существуют дельта-спецификации
        Assistant-->>Human: Предложение выполнить синхронизацию перед архивированием
        alt Синхронизация принята
            Human->>Assistant: Подтверждение синхронизации
            Assistant->>Files: Слияние дельта-спецификаций с основными спецификациями
        else Синхронизация пропущена
            Human->>Assistant: Архивирование без синхронизации
        end
    end
    Assistant->>Files: Перемещение изменения в архив
    Assistant-->>Human: Отчет о местоположении архива и результате синхронизации

    Note over Human,CLI: Альтернативный вариант через CLI: `openspec archive change-name --yes` пропускает запросы подтверждения. Он все равно выполняет проверку, применяет любые дельта-спецификации и архивирует

Два режима

Быстрый путь по умолчанию (профиль core)

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

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /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. Полное руководство: Исследование прежде всего.

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

Если вам нужны явные команды создания структуры и построения (/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/
     Готово к созданию: proposal

Вы: /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

ИИ:  Изменение создано. Готово к созданию: proposal

Вы: /opsx:continue

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

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

Вы: /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 при неясных требованиях

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

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

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

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

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

You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

Выявляет несоответствия перед завершением изменения.

Называйте изменения ясно

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

Good:                          Avoid:
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 request'ы
• Команды - Полный справочник команд с параметрами
• Концепции - Глубокое погружение в спецификации, артефакты и схемы
• Настройка - Создание пользовательских рабочих процессов