Рабочий процесс OPSX
Мы будем рады вашим отзывам в Discord.
Что это такое?
OPSX теперь является стандартным рабочим процессом для OpenSpec.
Это гибкий, итеративный рабочий процесс для изменений в OpenSpec. Больше никаких жёстких фаз — только действия, которые вы можете выполнять в любое время.
Зачем это нужно
Устаревший рабочий процесс OpenSpec работает, но он закрыт:
- Инструкции захардкожены — спрятаны в TypeScript, их нельзя изменить
- Всё или ничего — одна большая команда создаёт всё сразу, нельзя протестировать отдельные части
- Жёсткая структура — одинаковый рабочий процесс для всех, без кастомизации
- Чёрный ящик — когда вывод ИИ неудовлетворительный, нельзя подправить промпты
OPSX открывает всё это. Теперь любой может:
- Экспериментировать с инструкциями — отредактировать шаблон и проверить, станет ли ИИ работать лучше
- Тестировать по частям — валидировать инструкции каждого артефакта независимо
- Адаптировать рабочие процессы — определять собственные артефакты и зависимости
- Быстро итерировать — изменить шаблон, сразу протестировать, без пересборки
Устаревший процесс: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Захардкожено в пакете │ │ schema.yaml │◄── Вы редактируете это
│ (нельзя изменить) │ │ templates/*.md │◄── Или это
│ ↓ │ │ ↓ │
│ Ждать новый релиз │ │ Мгновенный эффект │
│ ↓ │ │ ↓ │
│ Надеяться, что лучше │ │ Протестировать самому │
└────────────────────────┘ └────────────────────────┘Это для всех:
- Команды — создавайте рабочие процессы, соответствующие вашему реальному способу работы
- Продвинутые пользователи — подправляйте промпты для получения лучших результатов ИИ для вашего кода
- Вкладчики в OpenSpec — экспериментируйте с новыми подходами без выпуска релизов
Мы все ещё учимся, что работает лучше всего. OPSX позволяет нам учиться вместе.
Пользовательский опыт
Проблема линейных рабочих процессов: Вы «находитесь на этапе планирования», затем «на этапе реализации», затем «готово». Но реальная работа устроена иначе. Вы реализуете что-то, понимаете, что дизайн был неправильным, нужно обновить спецификации, продолжить реализацию. Линейные этапы противоречат тому, как работа происходит на самом деле.
Подход OPSX:
- Действия, а не этапы — создавать, реализовывать, обновлять, архивировать — любое действие можно выполнить в любой момент
- Зависимости — это возможности — они показывают, что возможно, а не что обязательно делать следующим
proposal ──→ specs ──→ design ──→ tasks ──→ implementНастройка
# Убедитесь, что openspec установлен — навыки генерируются автоматически
openspec initЭто создаёт навыки в .claude/skills/ (или эквивалентном месте), которые ИИ-ассистенты для программирования обнаруживают автоматически.
По умолчанию OpenSpec использует профиль рабочего процесса core (propose, explore, apply, update, sync, archive). Если вам нужны расширенные команды рабочего процесса (new, continue, ff, verify, bulk-archive, onboard), настройте их через openspec config profile и примените через openspec update.
Во время настройки вам будет предложено создать конфигурацию проекта (openspec/config.yaml). Это необязательно, но рекомендуется.
Конфигурация проекта
Конфигурация проекта позволяет задавать значения по умолчанию и внедрять контекст, специфичный для проекта, во все артефакты.
Создание конфигурации
Конфигурация создаётся во время openspec init или вручную:
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flowsПоля конфигурации
| Поле | Тип | Описание |
|---|---|---|
schema | string | Схема по умолчанию для новых изменений (например, spec-driven) |
context | string | Контекст проекта, внедряемый во все инструкции артефактов |
rules | object | Правила для каждого артефакта, с ключами по ID артефакта |
Как это работает
Приоритет схемы (от высшего к низшему):
- Флаг CLI (
--schema <name>) - Метаданные изменения (
.openspec.yamlв каталоге изменения) - Конфигурация проекта (
openspec/config.yaml) - Значение по умолчанию (
spec-driven)
Внедрение контекста:
- Контекст добавляется в начало инструкций каждого артефакта
- Оборачивается в теги
<context>...</context> - Помогает ИИ понять конвенции вашего проекта
Внедрение правил:
- Правила внедряются только для соответствующих артефактов
- Оборачиваются в теги
<rules>...</rules> - Появляются после контекста, перед шаблоном
ID артефактов по схемам
spec-driven (по умолчанию):
proposal— Предложение об измененииspecs— Спецификацииdesign— Технический дизайнtasks— Задачи реализации
Валидация конфигурации
- Неизвестные ID артефактов в
rulesгенерируют предупреждения - Имена схем проверяются по доступным схемам
- Контекст ограничен размером 50 КБ
- Некорректный YAML сообщается с номерами строк
Устранение неполадок
"Неизвестный ID артефакта в rules: X"
- Проверьте, что ID артефактов соответствуют вашей схеме (см. список выше)
- Выполните
openspec schemas --json, чтобы увидеть ID артефактов для каждой схемы
Конфигурация не применяется:
- Убедитесь, что файл находится в
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Создаёт изменение и генерирует артефакты планирования, необходимые перед реализацией.
Если вы включили расширенные рабочие процессы, вы можете использовать вместо этого:
/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, чтобы код догнал пересмотренный план. Если ваша правка меняет намерение изменения, начните зановo — см. Когда обновлять, а когда начинать заново.
Синхронизация дельта-спецификаций
/opsx:syncСливает дельта-спецификации текущего изменения в основные openspec/specs/ без архивирования — изменение остаётся активным. Применяется весь дельта: требование под ## REMOVED удаляется из основной спецификации, а переименованное переименовывается на месте, при этом содержимое, не упомянутое в дельте, остаётся нетронутым. Синхронизация необязательна — при архивировании вас спросят, нужно ли сначала синхронизировать. Используйте, когда хотите обновить основные спецификации до архивирования, когда параллельное изменение должно строиться на спецификациях, только что добавленных этим, или когда хотите просмотреть слитую основную спецификацию до архивирования.
Завершение
/opsx:archive # Переместить в архив после завершения (предложит синхронизировать спецификации, если нужно)Когда обновлять, а когда начинать заново
Вы всегда можете отредактировать предложение или спецификации до реализации. Но когда уточнение превращается в «это другая работа»?
Что фиксирует предложение
Предложение определяет три вещи:
- Намерение — Какую проблему вы решаете?
- Объём — Что входит/не входит в рамки?
- Подход — Как вы будете её решать?
Вопрос в том: что изменилось и насколько?
Обновляйте существующее изменение, когда:
То же намерение, уточнённое исполнение
- Вы обнаруживаете граничные случаи, которые не учитывали
- Подход нужно подправить, но цель не изменилась
- Реализация показывает, что дизайн был немного неточным
Объём сужается
- Вы понимаетe, что полный объём слишком большой, хотите сначала выпустить MVP
- «Добавить тёмную тему» → «Добавить переключатель тёмной темы (системное предпочтение в v2)」
Корректировки на основе обучения
- Кодовая база устроена не так, как вы думали
- Зависимость работает не так, как ожидалось
- «Использовать CSS-переменные」 → 「Использовать префикс dark: из Tailwind вместо этого」
Начинайте новое изменение, когда:
Намерение фундаментально изменилось
- Сама проблема теперь другая
- 「Добавить тёмную тему」 → 「Добавить комплексную систему тем с кастомными цветами, шрифтами, отступами」
Объём разросся
- Изменение выросло настолько, что это по сути другая работа
- Оригинальное предложение будет неузнаваемо после обновлений
- 「Исправить баг входа」 → 「Переписать систему аутентификации」
Оригинал можно завершить
- Оригинальное изменение можно пометить как «готово」
- Новая работа самостоятельна, а не уточнение
- Завершить 「Добавить MVP тёмной темы」 → Архивировать → Новое изменение 「Улучшить тёмную тему」
Эвристики
┌─────────────────────────────────────┐
│ Это та же самая работа? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
То же намерение? >50% пересечения? Можно ли
Та же проблема? Тот же объём? оригинал
│ │ пометить как
│ │ «готово」 без
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
ДА НЕТ ДА НЕТ НЕТ ДА
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
ОБНОВИТЬ НОВОЕ ОБНОВИТЬ НОВОЕ ОБНОВИТЬ НОВОЕ| Тест | Обновить | Новое изменение |
|---|---|---|
| Идентичность | 「То же самое, уточнённое」 | 「Другая работа」 |
| Пересечение объёма | >50% пересечения | <50% пересечения |
| Завершение | Нельзя пометить как 「готово」 без изменений | Можно завершить оригинал, новая работа самостоятельна |
| История | Цепочка обновлений рассказывает связную историю | Патчи запутают больше, чем прояснят |
Принцип
Обновление сохраняет контекст. Новое изменение обеспечивает ясность.
Выбирайте обновление, когда история ваших размышлений ценна. Выбирайте новое, когда начать заново будет яснее, чем латать.
Представьте это как ветки в git:
- Продолжайте коммитить, работая над той же функцией
- Создавайте новую ветку, когда это по-настоящему новая работа
- Иногда объедините частичную функцию и начните заново для фазы 2
Что изменилось?
Устаревший подход (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| Структура | Один большой документ с предложением | Отдельные артефакты со связями зависимостей |
| Рабочий процесс | Линейные фазы: планирование → реализация → архивирование | Гибкие действия — выполняйте любые операции в любое время |
| Итерации | Возврат назад затруднён | Обновляйте артефакты по мере получения новых знаний |
| Настраиваемость | Фиксированная структура | На основе схемы (определяйте собственные артефакты) |
Ключевой вывод: работа не является линейным процессом. OPSX больше не делает вид, что это так.
Глубокий анализ архитектуры
В этом разделе объясняется внутреннее устройство OPSX и его сравнение с устаревшим рабочим процессом. Примеры в этом разделе используют расширенный набор команд (new, continue и т.д.); пользователи по умолчанию core могут сопоставить тот же процесс с propose → apply → sync → archive.
Философия: фазы против действий
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW │
│ (Phase-Locked, All-or-Nothing) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ │
│ │ PHASE │ │ PHASE │ │ PHASE │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Creates ALL artifacts at once │
│ • Can't go back to update specs during implementation │
│ • Phase gates enforce linear progression │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX WORKFLOW │
│ (Fluid Actions, Iterative) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Create artifacts one at a time OR fast-forward │
│ • Update specs/design/tasks during implementation │
│ • Dependencies enable progress, phases don't exist │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Архитектура компонентов
Устаревший рабочий процесс использует жёстко закодированные шаблоны на TypeScript:
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Hardcoded Templates (TypeScript strings) │
│ │ │
│ ▼ │
│ Tool-specific configurators/adapters │
│ │ │
│ ▼ │
│ Generated Command Files (.claude/commands/openspec/*.md) │
│ │
│ • Fixed structure, no artifact awareness │
│ • Change requires code modification + rebuild │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX использует внешние схемы и движок графа зависимостей:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Schema Definitions (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Artifact Graph Engine │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Topological sort (dependency ordering) │ │
│ │ • State detection (filesystem existence) │ │
│ │ • Rich instruction generation (templates + context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Cross-editor compatible (Claude Code, Cursor, Devin) │
│ • Skills query CLI for structured data │
│ • Fully customizable via schema files │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Модель графа зависимостей
Артефакты образуют ориентированный ациклический граф (DAG). Зависимости являются разблокировщиками, а не шлюзами:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY PHASE │
│ (requires: │
│ tasks) │
└──────────────┘Переходы состояний:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Missing All deps File exists
dependencies are DONE on filesystemПоток информации
Устаревший рабочий процесс — агент получает статические инструкции:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Static instructions: │
│ • Create proposal.md │
│ • Create tasks.md │
│ • Create design.md │
│ • Create delta spec files │
│ │
│ No awareness of what exists or │
│ dependencies between artifacts │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one goOPSX — агент запрашивает подробный контекст:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1: Query current state │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── First ready │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", │ │
│ │ "missingDeps": ["specs", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Get rich instructions for ready artifact │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Read dependencies → Create ONE artifact → Show what's unlocked │
└──────────────────────────────────────────────────────────────────────────┘Модель итераций
Устаревший рабочий процесс — итерации затруднены:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "Wait, the design is wrong"
│ │
│ ├── Options:
│ │ • Edit files manually (breaks context)
│ │ • Abandon and start over
│ │ • Push through and fix later
│ │
│ └── No official "go back" mechanism
│
└── Creates ALL artifacts at onceOPSX — естественные итерации:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "The design is wrong"
│ │ │
│ │ ▼
│ │ Just edit design.md
│ │ and continue!
│ │ │
│ │ ▼
│ │ /opsx:apply picks up
│ │ where you left off
│ │
│ └── Creates ONE artifact, shows what's unlocked
│
└── Scaffolds change, waits for directionПользовательские схемы
Создавайте пользовательские рабочие процессы с помощью команд управления схемами:
# Create a new schema from scratch (interactive)
openspec schema init my-workflow
# Or fork an existing schema as a starting point
openspec schema fork spec-driven my-workflow
# Validate your schema structure
openspec schema validate my-workflow
# See where a schema resolves from (useful for debugging)
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:
name: research-first
artifacts:
- id: research # Added before proposal
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Now depends on 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
# Список доступных схем
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.