OPSX Workflow
Отзывы приветствуются в Discord.
Что это?
OPSX теперь является стандартным рабочим процессом для OpenSpec.
Это гибкий итеративный рабочий процесс для внесения изменений в OpenSpec. Больше нет строгих фаз — только действия, которые вы можете выполнять в любое время.
Зачем это существует
Устаревший рабочий процесс OpenSpec работает, но он заблокирован:
- Инструкции жестко закодированы — спрятаны в коде на TypeScript, их нельзя изменить
- Все или ничего — одна большая команда создает всё сразу, нельзя протестировать отдельные части
- Фиксированная структура — одинаковый рабочий процесс для всех, без возможности настройки
- Черный ящик — когда результат работы ИИ плохой, вы не можете подкорректировать промпты
OPSX открывает его. Теперь любой может:
- Экспериментировать с инструкциями — отредактируйте шаблон, посмотрите, станет ли ИИ работать лучше
- Тестировать детально — проверять инструкции для каждого артефакта отдельно
- Настраивать рабочие процессы — определяйте собственные артефакты и зависимости
- Итерировать быстро — измените шаблон, сразу протестируйте, без пересборки
Устаревший рабочий процесс: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Жестко закодировано в пакете │ │ schema.yaml │◄── Вы редактируете это
│ (нельзя изменить) │ │ templates/*.md │◄── Или это
│ ↓ │ │ ↓ │
│ Ждать нового релиза │ │ Мгновенный эффект │
│ ↓ │ │ ↓ │
│ Надеяться, что будет лучше │ │ Протестируйте сами │
└────────────────────────┘ └────────────────────────┘Это для всех:
- Команды — создавайте рабочие процессы, которые соответствуют тому, как вы действительно работаете
- Продвинутые пользователи — подкорректируйте промпты, чтобы получить лучшие результаты от ИИ для вашей кодовой базы
- Контрибьюторы OpenSpec — экспериментируйте с новыми подходами без необходимости выпускать релизы
Мы все еще учимся, что работает лучше всего. OPSX позволяет нам учиться вместе.
Пользовательский опыт
Проблема линейных рабочих процессов: Вы «находитесь в фазе планирования», потом «в фазе реализации», потом «готово». Но реальная работа устроена не так. Вы реализуете что-то, понимаете, что ваш дизайн был неправильный, нужно обновить спецификации, продолжить реализацию. Линейные фазы противоречат тому, как работа устроена на самом деле.
Подход OPSX:
- Действия, а не фазы — создавайте, реализуйте, обновляйте, архивируйте — делайте любое из этих действий в любой момент
- Зависимости — это возможности, а не требования к следующим шагам — они показывают, что возможно, а не что нужно делать дальше
proposal ──→ specs ──→ design ──→ tasks ──→ implementУстановка
bash
# Убедитесь, что у вас установлен openspec — навыки генерируются автоматически
openspec initЭто создает навыки в .claude/skills/ (или аналогичной директории), которые ассистенты для написания кода на ИИ обнаруживают автоматически.
По умолчанию OpenSpec использует профиль рабочего процесса core (propose, explore, apply, sync, archive). Если вы хотите использовать расширенные команды рабочего процесса (new, continue, ff, verify, bulk-archive, onboard), настроите их с помощью openspec config profile и примените с помощью openspec update.
Во время установки вам предложат создать конфигурацию проекта (openspec/config.yaml). Это необязательно, но рекомендуется.
Конфигурация проекта
Конфигурация проекта позволяет задать значения по умолчанию и добавить контекст проекта во все артефакты.
Создание конфигурации
Конфигурация создается во время выполнения openspec init, или может быть добавлена вручную:
yaml
# Конфигурация проекта (openspec/config.yaml)
schema: spec-driven
context: |
Технологический стек: TypeScript, React, Node.js
Конвенции API: RESTful, ответы в формате JSON
Тестирование: Vitest для юнит-тестов, Playwright для end-to-end тестов
Стиль кода: ESLint с Prettier, строгий TypeScript
rules:
proposal:
- Включить план отката
- Определить затронутые команды
specs:
- Использовать формат Given/When/Then для сценариев
design:
- Включить диаграммы последовательностей для сложных сценариевПоля конфигурации
| Поле | Тип | Описание |
|---|---|---|
schema | строка | Схема по умолчанию для новых изменений (например, spec-driven) |
context | строка | Контекст проекта, добавляемый ко всем инструкциям для артефактов |
rules | объект | Правила для отдельных артефактов, ключом является идентификатор артефакта |
Как это работает
Приоритет схемы (от высшего к низшему):
- Флаг CLI (
--schema <name>) - Метаданные изменения (
.openspec.yamlв директории изменения) - Конфигурация проекта (
openspec/config.yaml) - Значение по умолчанию (
spec-driven)
Добавление контекста:
- Контекст добавляется в начало всех инструкций для артефактов
- Оборачивается в теги
<context>...</context> - Помогает ИИ понять конвенции вашего проекта
Добавление правил:
- Правила добавляются только для соответствующих артефактов
- Оборачиваются в теги
<rules>...</rules> - Появляются после контекста, перед шаблоном
Идентификаторы артефактов по схемам
spec-driven (по умолчанию):
proposal— Предложение по изменениюspecs— Спецификацииdesign— Технический дизайнtasks— Задачи по реализации
Валидация конфигурации
- Неизвестные идентификаторы артефактов в поле
rulesгенерируют предупреждения - Названия схем проверяются на соответствие доступным схемам
- Размер контекста ограничен 50 КБ
- При невалидном YAML выводится отчет с номерами строк
Устранение неполадок
"Unknown artifact ID in rules: X"
- Проверьте, что идентификаторы артефактов соответствуют вашей схеме (см. список выше)
- Выполните
openspec schemas --json, чтобы увидеть идентификаторы артефактов для каждой схемы
Конфигурация не применяется:
- Убедитесь, что файл находится по пути
openspec/config.yaml(не.yml) - Проверьте синтаксис YAML с помощью валидатора
- Изменения в конфигурации применяются сразу (перезапуск не требуется)
Слишком большой контекст:
- Размер контекста ограничен 50 КБ
- Вместо этого сократите контекст или добавьте ссылку на внешнюю документацию
Команды
| Команда | Описание |
|---|---|
/opsx:propose | Создать изменение и сгенерировать артефакты планирования за один шаг (быстрый путь по умолчанию) |
/opsx:explore | Обдумать идеи, исследовать проблемы, уточнить требования |
/opsx:new | Создать каркас нового изменения (расширенный рабочий процесс) |
/opsx:continue | Создать следующий артефакт (расширенный рабочий процесс) |
/opsx:ff | Быстро создать все артефакты планирования (расширенный рабочий процесс) |
/opsx:apply | Реализовать задачи, обновляя артефакты по мере необходимости |
/opsx:update | Пересмотреть артефакты планирования изменения и сохранить их согласованность |
/opsx:verify | Проверить реализацию на соответствие артефактам (расширенный рабочий процесс) |
/opsx:sync | Синхронизировать дельта-спецификации с основной веткой (рабочий процесс по умолчанию, опционально) |
/opsx:archive | Архивировать изменение после завершения |
/opsx:bulk-archive | Архивировать несколько завершенных изменений (расширенный рабочий процесс) |
/opsx:onboard | Пошаговое руководство по прохождению полного цикла изменения (расширенный рабочий процесс) |
Использование
Обдумать идею
/opsx:exploreОбдумайте идеи, исследовайте проблемы, сравните варианты. Структура не требуется — просто партнер для размышлений. Когда идеи сформулируются, перейдите к /opsx:propose (по умолчанию) или /opsx:new//opsx:ff (расширенный).
Создать новое изменение
/opsx:proposeСоздает изменение и генерирует артефакты планирования, необходимые перед началом реализации.
Если вы включили расширенные рабочие процессы, вместо этого можно использовать:
text
/opsx:new # только каркас
/opsx:continue # создавать по одному артефакту за раз
/opsx:ff # создать все артефакты планирования сразуСоздать артефакты
/opsx:continueПоказывает, что готово к созданию на основе зависимостей, затем создает один артефакт. Используйте повторно, чтобы постепенно добавлять части вашего изменения.
/opsx:ff add-dark-modeСоздает все артефакты планирования сразу. Используйте, когда у вас есть четкое представление о том, что вы строите.
Реализация (гибкая часть)
/opsx:applyПроходит по задачам, отмечая их как выполненные по мере продвижения. Если вы работаете сразу с несколькими изменениями, можно выполнить /opsx:apply <name>; в противном случае система должна определить нужное изменение из контекста беседы и предложить выбрать, если не может понять.
Обновление изменения
/opsx:update add-dark-mode - we're storing the theme in a cookie nowПересматривает существующие артефакты планирования изменения и сохраняет их согласованность — в любом направлении (изменение дизайна может распространиться обратно на предложение). Только артефакты планирования: система никогда не редактирует код и никогда не создает отсутствующие артефакты (для этого используйте /opsx:continue). Каждое изменение подтверждается с вами сначала. Если изменение уже было реализовано, рекомендуется выполнить /opsx:apply, чтобы код соответствовал пересмотренному плану. Если ваше изменение меняет назначение изменения, начните с нуля вместо этого — см. Когда обновлять, а когда начинать с нуля.
Завершение
/opsx:archive # Переместить в архив после завершения (предлагает синхронизировать спецификации при необходимости)Когда обновлять существующее изменение, а когда начинать с нуля
Вы всегда можете редактировать свое предложение или спецификации перед реализацией. Но когда уточнение становится «это уже другая работа»?
Что описывает предложение по изменению
Предложение по изменению определяет три вещи:
- Назначение — Какую проблему вы решаете?
- Объем — Что входит в рамки, а что нет?
- Подход — Как вы будете решать ее?
Вопрос в том, что изменилось и насколько сильно?
Обновляйте существующее изменение, когда:
Одинаковое назначение, уточненная реализация
- Вы обнаружили крайние случаи, которые не учли
- Подход нуждается в корректировке, но цель остается прежней
- В процессе реализации выяснилось, что дизайн был немного неверным
Объем сужается
- Вы поняли, что полный объем слишком большой, хотите сначала выпустить минимально жизнеспособный продукт (MVP)
- «Добавить темную тему» → «Добавить переключатель темной темы (системные предпочтения в версии 2)»
Корректировки на основе полученного опыта
- Структура кодовой базы не соответствует вашим ожиданиям
- Зависимость работает не так, как ожидалось
- «Использовать CSS-переменные» → «Использовать префикс
dark:от Tailwind вместо этого»
Начинайте новое изменение, когда:
Назначение кардинально изменилось
- Сама проблема теперь другая
- «Добавить темную тему» → «Добавить полноценную систему тем с пользовательскими цветами, шрифтами, отступами»
Объем значительно вырос
- Изменение выросло настолько, что это по сути другая работа
- Исходное предложение будет неузнаваемым после уточнений
- «Исправить баг входа в систему» → «Переписать систему аутентификации»
Исходное изменение можно завершить
- Исходное изменение можно отметить как «выполненное»
- Новая работа является отдельной, а не уточнением старой
- Завершить «Добавить минимально жизнеспособный продукт темной темы» → Архивировать → Новое изменение «Улучшить темную тему»
Эвристические правила
┌─────────────────────────────────────┐
│ Это та же самая работа? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Одинаковое назначение? >50% совпадения? Можно ли завершить исходное
Одинаковая проблема? Одинаковый объем? без этих правок?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
ДА НЕТ ДА НЕТ НЕТ ДА
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
ОБНОВИТЬ НОВОЕ ОБНОВИТЬ НОВОЕ ОБНОВИТЬ НОВОЕ| Критерий | Обновить существующее | Начать новое |
|---|---|---|
| Суть | «Та же работа, уточненная» | «Другая работа» |
| Совпадение по объему | >50% совпадения | <50% совпадения |
| Завершимость | Нельзя завершить без правок | Можно завершить исходное, новая работа отдельна |
| История изменений | Цепочка обновлений дает понятную картину | Правки будут больше запутывать, чем прояснять |
Основной принцип
Обновление сохраняет контекст. Новое изменение дает ясность.
Выбирайте обновление, когда история ваших размышлений ценна. Выбирайте новое изменение, когда начать с нуля будет понятнее, чем вносить правки.
Представьте это как ветки в git:
- Делайте коммиты, пока работаете над одной и той же функцией
- Создайте новую ветку, когда это действительно новая работа
- Иногда объедините частично готовую функциональность и начните с нуля для второй фазы
В чем отличия?
Устаревший (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| Структура | Один большой документ с предложением | Отдельные артефакты с зависимостями |
| Рабочий процесс | Линейные фазы: планирование → реализация → архивация | Гибкие действия — делайте что угодно в любой момент |
| Итерации | Неудобно возвращаться назад | Обновляйте артефакты по мере получения нового опыта |
| Настройка | Фиксированная структура | На основе схем (определяйте собственные артефакты) |
Ключевая идея: работа не является линейной. OPSX перестает делать вид, что это так.
Глубокое погружение в архитектуру
В этом разделе объясняется, как работает OPSX на внутреннем уровне, и как он сравнивается с устаревшим рабочим процессом. Примеры в этом разделе используют расширенный набор команд (new, continue и т.д.); пользователи пакета core по умолчанию могут сопоставить тот же поток с propose → apply → sync → archive.
Философия: Фазы против Действий
┌─────────────────────────────────────────────────────────────────────────────┐
│ УСТАРЕВШИЙ РАБОЧИЙ ПРОЦЕСС │
│ (Фиксированные фазы, всё или ничего) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ФАЗА │ ───► │ ФАЗА │ ───► │ ФАЗА │ │
│ │ ПЛАНИРОВАНИЯ│ │ РЕАЛИЗАЦИИ │ │ АРХИВАЦИИ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Создаёт ВСЕ артефакты сразу │
│ • Невозможно вернуться и обновить спецификации во время реализации │
│ • Фазовые контрольные точки обеспечивают линейное продвижение │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ РАБОЧИЙ ПРОЦЕСС OPSX │
│ (Гибкие действия, итеративный) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ДЕЙСТВИЯ (не фазы) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ любой порядок │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Создавайте артефакты по одному ИЛИ пропускайте шаги │
│ • Обновляйте спецификации, дизайн и задачи во время реализации │
│ • Зависимости обеспечивают продвижение, фазы отсутствуют │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Архитектура компонентов
Устаревший рабочий процесс использует жестко закодированные шаблоны на TypeScript:
┌─────────────────────────────────────────────────────────────────────────────┐
│ КОМПОНЕНТЫ УСТАРЕВШЕГО РАБОЧЕГО ПРОЦЕССА │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Жестко закодированные шаблоны (строки на TypeScript) │
│ │ │
│ ▼ │
│ Конфигураторы/адаптеры под конкретные инструменты │
│ │ │
│ ▼ │
│ Сгенерированные файлы команд (.claude/commands/openspec/*.md) │
│ │
│ • Фиксированная структура, нет поддержки артефактов │
│ • Для внесения изменений требуется модификация кода и пересборка │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX использует внешние схемы и движок графа зависимостей:
┌─────────────────────────────────────────────────────────────────────────────┐
│ КОМПОНЕНТЫ OPSX │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Определения схем (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Зависимости │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Глоб-паттерны │ │
│ │ requires: [proposal] ◄── Включается после proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Движок графа артефактов │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Топологическая сортировка (упорядочивание по зависимостям) │ │
│ │ • Определение состояния (проверка наличия в файловой системе) │ │
│ │ • Генерация детальных инструкций (шаблоны + контекст) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Файлы навыков (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Совместимость с разными редакторами (Claude Code, Cursor, Windsurf) │
│ • CLI для запроса навыков для работы с структурированными данными │
│ • Полностью настраивается через файлы схем │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Модель графа зависимостей
Артефакты образуют ориентированный ациклический граф (DAG). Зависимости являются включителями, а не контрольными точками:
proposal
(корневой узел)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(требует: (требует:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(требует:
specs, design)
│
▼
┌──────────────┐
│ ФАЗА ПРИМЕНЕНИЯ │
│ (требует: │
│ tasks) │
└──────────────┘Переходы между состояниями:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Отсутствуют Все зависимости Файл существует
зависимости DONE в файловой системеПоток информации
Устаревший рабочий процесс — агент получает статические инструкции:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Статические инструкции: │
│ • Создать proposal.md │
│ • Создать tasks.md │
│ • Создать design.md │
│ • Создать specs/<capability>/spec.md │
│ │
│ Нет информации о существующих файлах │
│ или зависимостях между артефактами │
└─────────────────────────────────────────┘
│
▼
Агент создаёт ВСЕ артефакты сразуOPSX — агент запрашивает детальный контекст:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Шаг 1: Запрос текущего состояния │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── Первый готовый │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Шаг 2: Получение детальных инструкций для готового артефакта │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Шаг 3: Чтение зависимостей → Создание ОДНОГО артефакта → Показ │
│ разблокированных элементов │
└──────────────────────────────────────────────────────────────────────────┘Модель итераций
Устаревший рабочий процесс — неудобно для итераций:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── «Подождите, дизайн неверный»
│ │
│ ├── Варианты:
│ │ • Редактировать файлы вручную (сломает контекст)
│ │ • Отказаться от изменений и начать заново
│ │ • Пройти через все этапы и исправить потом
│ │
│ └── Нет официального механизма «возврата назад»
│
└── Создаёт ВСЕ артефакты сразуOPSX — естественная итерация:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── «Дизайн неверный»
│ │ │
│ │ ▼
│ │ Просто отредактируйте design.md
│ │ и продолжайте работу!
│ │ │
│ │ ▼
│ │ /opsx:apply продолжится
│ │ с того места, где вы остановились
│ │
│ └── Создаёт ОДИН артефакт, показывает, что разблокировано
│
└── Создаёт каркас изменения, ждёт указанийПользовательские схемы
Создавайте пользовательские рабочие процессы с помощью команд управления схемами:
bash
# Создать новую схему с нуля (интерактивно)
openspec schema init my-workflow
# Или форкнуть существующую схему как отправную точку
openspec schema fork spec-driven my-workflow
# Проверить структуру вашей схемы
openspec schema validate my-workflow
# Узнать, откуда разрешается схема (полезно для отладки)
openspec schema which my-workflowСхемы хранятся в openspec/schemas/ (локально для проекта, под версионным контролем) или в ~/.local/share/openspec/schemas/ (глобально для пользователя).
Структура схемы:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.mdПример schema.yaml:
yaml
name: research-first
artifacts:
- id: research # Добавлен перед proposal
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Теперь зависит от research
- id: tasks
generates: tasks.md
requires: [proposal]Граф зависимостей:
research ──► proposal ──► tasksСводка
| Аспект | Устаревшая версия | OPSX |
|---|---|---|
| Шаблоны | Жёстко закодированные на TypeScript | Внешние YAML + Markdown |
| Зависимости | Отсутствуют (все создаются сразу) | DAG с топологической сортировкой |
| Состояние | Фазовая ментальная модель | Наличие в файловой системе |
| Кастомизация | Редактировать исходный код, пересобирать | Создать schema.yaml |
| Итерация | Блокировка по фазам | Гибкая, можно редактировать что угодно |
| Поддержка редакторов | Конфигураторы/адаптеры под конкретные инструменты | Единая директория с навыками (skills) |
Схемы
Схемы определяют, какие артефакты существуют и их зависимости. В настоящее время доступны:
- spec-driven (по умолчанию): proposal → specs → design → tasks
bash
# Показать список доступных схем
openspec schemas
# Показать все схемы с источниками их разрешения
openspec schema which --all
# Создать новую схему интерактивно
openspec schema init my-workflow
# Форкнуть существующую схему для кастомизации
openspec schema fork spec-driven my-workflow
# Проверить структуру схемы перед использованием
openspec schema validate my-workflowСоветы
- Используйте
/opsx:exploreдля проработки идеи перед тем, как приступить к внесению изменений /opsx:ffиспользуйте, если вы точно знаете, что хотите сделать, а/opsx:continue— если вы ещё исследуете варианты- Во время выполнения
/opsx:apply, если что-то пошло не так — исправьте артефакт, затем продолжите - Задачи отслеживают прогресс с помощью чекбоксов в
tasks.md - Проверяйте статус в любой момент:
openspec status --change "name"
Обратная связь
Всё ещё сыровато. Это сделано намеренно — мы изучаем, что работает лучше всего.
Нашли ошибку? Есть идеи? Присоединяйтесь к нам на Discord или откройте issue на GitHub.