Урок 15.8. Workflow-паттерны: когда какую команду применять

Зачем это нужно

Уроки 15.4–15.6 разобрали, где выполняются команды OpenSpec и что делает каждая из них по отдельности, а урок 15.7 подробно остановился на /opsx:explore. Но знать команды по одной - еще не уметь их сочетать. В реальной работе вопрос формулируется иначе: «у меня небольшая фича с понятным объемом», «есть баг непонятной природы», «меня дергают между тремя задачами сразу». Какая комбинация команд подходит каждой из этих ситуаций - тема данного урока.

Документ Workflows - центральный в «повседневной» части документации OpenSpec: он собирает разрозненные команды из справочников в целостные паттерны. После него вы перестаете думать отдельными командами и начинаете думать ситуациями: понятные требования - быстрый путь, неясные требования - исследование, несколько незавершенных задач - параллельные изменения и пакетная архивация.

Урок расширяет цикл из урока 15.2 (/opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive) и продолжает линию обзора 2.10: OpenSpec - это легкий слой спецификаций без фазовых ворот, и данный урок показывает, как это устроено на практике.

Основная идея

Традиционные workflow загоняют работу в фазы: сначала планирование, потом реализация, потом «готово». Реальная работа в такие коробки не укладывается: в середине реализации выясняются новые факты, и план приходится править - а фазовая модель это запрещает.

Workflow OPSX предлагает противоположный подход - действия вместо фаз:

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

Два ключевых принципа:

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

Кастомизация. Workflow OPSX управляется схемами (schemas), которые задают последовательности артефактов. Создание собственных схем разобрано в документе Customization (в курсе - урок 15.13).

Workflow целиком на одной схеме

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

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

Разделение ролей здесь то же, что в уроке 15.4: ассистент читает и пишет Markdown-артефакты, CLI отвечает за детерминированные операции - каркас, статус, валидацию, перемещение файлов.

Два режима команд

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

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

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

Типичный поток:

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (необязательно)

Начинайте с explore - привычка, которую стоит завести

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

Вы:  /opsx:explore

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

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

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

Вы:  Да.

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

Explore никогда не пишет код - и не пишет ничего вообще, пока вы не попросите или не согласитесь на предложение ассистента. Это «бесплатный» разговор без обязательств и последствий, который превращает расплывчатое беспокойство в точное изменение, и следующим за ним proposal получается острым.

Точно знаете, что хотите? Пропустите explore и идите сразу в /opsx:propose. Полный разбор команды - в уроке 15.7.

Расширенный режим (custom selection)

Если нужны явные команды «каркас + сборка» - /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard - включите их:

openspec config profile
openspec update

Назначение терминальных команд config и update разобрано в уроке 15.6; полный список слэш-команд - в уроке 15.5.

Паттерны workflow в расширенном режиме

Быстрая фича

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

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

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

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

AI:  Created openspec/changes/add-logout-button/
     Ready to create: proposal

Вы:  /opsx:ff

AI:  Creating all planning artifacts...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

Вы:  /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

Вы:  /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

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

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

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

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

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

Вы:  /opsx:explore

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

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

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

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

     С какого начать?

Вы:  Возьмем загрузку данных.

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

AI:  Created change. Ready to create: proposal

Вы:  /opsx:continue

AI:  Creating proposal based on our exploration...
     [пишет proposal с учетом находок исследования]

     Ready to create: specs, design
     Что делаем дальше?

Вы:  /opsx:continue

AI:  Creating specs...

Ключевое отличие от быстрой фичи: планирование идет шаг за шагом (/opsx:continue создает следующий артефакт), и результаты исследования попадают прямо в proposal.

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

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

Несколько изменений могут находиться в работе одновременно:

Пример диалога - работу над темной темой прерывает срочный багфикс:

Вы:  Работаю над add-dark-mode, но срочно нужно исправить баг

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

AI:  Created openspec/changes/fix-login-redirect/

Вы:  /opsx:ff

AI:  ✓ Created planning artifacts

Вы:  /opsx:apply

AI:  Working on fix-login-redirect...
     [реализует исправление]
     All tasks complete!

Вы:  /opsx:archive

AI:  ✓ Archived fix-login-redirect

Вы:  Возвращаемся к темной теме

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

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

Прерывание не теряет контекст: артефакты и чекбоксы в tasks.md хранят состояние каждого изменения, поэтому /opsx:apply <имя> возобновляет работу с прерванного места.

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

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

Вы:  /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (all tasks done)
     - fix-login-redirect (all tasks done)
     - update-footer (all tasks done)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will apply in chronological order.

     Archive all 3 changes?

Вы:  Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

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

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

Рекомендуемый финальный поток:

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

/opsx:verify: проверьте свою работу

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

You: /opsx:verify

AI:  Verifying add-auth...

     COMPLETENESS
     ✓ All 12 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Session timeout after inactivity" not tested

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "event-driven" but implementation uses polling

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for session timeout scenario
     2. Consider refactoring to event-driven as designed, or update design.md

Что проверяет каждая размерность:

Verify не блокирует архивацию, но подсвечивает проблемы, которые имеет смысл закрыть до нее: в примере выше - непротестированный сценарий и расхождение между «event-driven» в design.md и polling в коде.

/opsx:archive: финализация изменения

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

You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

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

Что когда применять

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

Практическое правило: если можете описать весь объем заранее - /opsx:ff; если разбираетесь по ходу дела - /opsx:continue.

Обновить существующее изменение или начать новое

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

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

• замысел тот же, уточняется только исполнение;
• объем сужается (сначала MVP, остальное позже);
• исправления по итогам изучения кода: кодовая база оказалась не такой, как ожидалось;
• правки design по находкам, сделанным в ходе реализации.

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

• замысел принципиально изменился;
• объем разросся в совершенно другую работу;
• исходное изменение можно закрыть как «готовое» само по себе;
• заплатки запутают больше, чем прояснят.

Пример на изменении «добавить темную тему»:

• «нужно еще поддержать пользовательские темы» → новое изменение (объем разросся);
• «определение системной настройки оказалось сложнее, чем думали» → обновить (тот же замысел);
• «выпустим сначала переключатель, настройки позже» → обновить и архивировать, затем новое изменение.

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

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

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

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

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

Неясные требования - сначала /opsx:explore

До фиксации изменения исследуйте проблемное поле:

Вы:  /opsx:explore

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

Вы:  Как нам организовать rate limiting для API?

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

     Вижу три подхода:
     1. Middleware (просто, на уровне endpoint)
     2. На Redis (масштабируемо, общее состояние)
     3. Token bucket на пользователя (справедливо, сложнее)

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

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

Verify перед архивацией

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

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

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

Сводная матрица: ситуация → команды

Матрица ниже собрана курсом из паттернов исходного документа - как быстрый выбор пути по ситуации. Полные пошаговые примеры - в уроке 15.9.

Инженерный вывод курса: почти каждая строка матрицы - это один и тот же цикл «спланируй → реализуй → проверь → архивируй», отличающийся только точкой входа (explore или сразу propose/new) и зерном планирования (propose, ff или continue). Выбор паттерна - это выбор того, сколько неопределенности осталось перед первым артефактом.

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

Полные детали и опции команд - в уроке 15.5.

Практика

1. В тестовом проекте из урока 15.2 пройдите быстрый путь профиля core на маленьком изменении с понятным объемом (например, «add-footer-link»): /opsx:propose → ревью артефактов → /opsx:apply → /opsx:archive.
2. Включите расширенный режим (openspec config profile, затем openspec update) и повторите то же изменение паттерном «быстрая фича»: /opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive. Сравните, где проверка verify нашла что-то неожиданное.
3. Проведите эксперимент с параллельностью: начните изменение A, посреди реализации создайте срочное изменение B, завершите и заархивируйте его, затем вернитесь командой /opsx:apply <имя A> и убедитесь, что работа продолжилась с прерванной задачи.
4. Выполните openspec list и оцените имена своих изменений по правилам из раздела «Лучшие практики».

Краткое резюме

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

• Профиль core по умолчанию: /opsx:explore, /opsx:propose, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive; типичный поток - explore → propose → apply → sync → archive.
• Расширенный режим (openspec config profile + openspec update) добавляет /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard.
• Паттерны: быстрая фича (new → ff → apply → verify → archive), исследование (explore → new → continue → …), параллельные изменения (/opsx:apply <имя> возобновляет прерванную работу) и завершение (apply → verify → archive).
• Verify проверяет реализацию по трем измерениям: полнота, корректность, согласованность - и не блокирует архивацию.
• Существующее изменение обновляют при том же замысле; новое начинают, когда замысел или объем принципиально изменились.
• Лучшие практики: одна логическая единица работы на изменение, explore при неясных требованиях, verify перед архивацией, понятные имена.

Вопросы для самопроверки

1. Чем подход «действия, а не фазы» отличается от фазового workflow и что означает принцип «зависимости - это возможности»?
2. Какие шесть команд входят в профиль core и как включить расширенный набор команд?
3. Когда выбирать /opsx:ff, а когда /opsx:continue? Сформулируйте практическое правило.
4. По каким трем измерениям /opsx:verify сверяет реализацию с артефактами и что делает каждая проверка?
5. Перечислите признаки того, что существующее изменение нужно обновить, и признаки того, что пора начать новое.
6. Как /opsx:bulk-archive разрешает ситуацию, когда несколько завершенных изменений затрагивают одни и те же спецификации?

Что дальше

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

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md