Перейти к содержимому

Выбрать язык

Текущий язык: Русский

Рабочий процесс OPSX

Отзывы приветствуются в Discord.

OPSX — стандартный рабочий процесс OpenSpec.

Это гибкий итеративный рабочий процесс для изменений OpenSpec. Больше никаких жёстких этапов — только действия, которые можно выполнять в любое время.

Устаревший рабочий процесс OpenSpec работает, но он ограничивает пользователя:

  • Инструкции заданы жёстко — они скрыты в TypeScript, и изменить их нельзя.
  • Всё или ничего — одна большая команда создаёт всё сразу, отдельные части проверить нельзя.
  • Фиксированная структура — один процесс для всех без возможности настройки.
  • Чёрный ящик — если результат ИИ плохой, настроить запросы нельзя.

OPSX открывает эту систему. Теперь каждый может:

  1. Экспериментировать с инструкциями — изменить шаблон и посмотреть, улучшится ли результат ИИ.
  2. Проверять отдельные части — независимо проверять инструкции каждого артефакта.
  3. Настраивать рабочие процессы — определять собственные артефакты и зависимости.
  4. Быстро итерировать — изменить шаблон и сразу проверить его без повторной сборки.
Устаревший процесс: 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: |
Технологический стек: TypeScript, React, Node.js
Соглашения API: REST, ответы в формате JSON
Тестирование: Vitest для модульных тестов, Playwright для e2e
Стиль: ESLint с Prettier, строгий TypeScript
rules:
proposal:
- Добавлять план отката
- Указывать затронутые команды
specs:
- Использовать формат Given/When/Then для сценариев
design:
- Добавлять диаграммы последовательностей для сложных процессов
Поле Тип Описание
schema string Схема по умолчанию для новых изменений (например, spec-driven)
context string Контекст проекта, добавляемый ко всем инструкциям артефактов
rules object Правила для отдельных артефактов, индексируемые по ID

Приоритет схем (от высшего к низшему):

  1. CLI flag (--schema <name>)
  2. Change metadata (.openspec.yaml in change directory)
  3. Project config (openspec/config.yaml)
  4. Default (spec-driven)

Передача контекста:

  • контекст добавляется в начало инструкций каждого артефакта;
  • заключается в теги <context>...</context>;
  • помогает ИИ понять соглашения проекта.

Передача правил:

  • правила добавляются только к соответствующим артефактам;
  • заключаются в теги <rules>...</rules>;
  • помещаются после контекста и перед шаблоном.

spec-driven (по умолчанию):

  • proposal — предложение об изменении;
  • specs — спецификации;
  • design — техническое проектное решение;
  • tasks — задачи реализации.
  • Неизвестные ID артефактов в rules вызывают предупреждение.
  • Имена схем сверяются со списком доступных схем.
  • Размер контекста ограничен 50 КБ.
  • Для некорректного YAML указываются номера строк.

«Unknown artifact ID in rules: X» (неизвестный ID артефакта в rules)

  • Убедитесь, что 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 - теперь мы храним тему в cookie

Изменяет существующие артефакты планирования и сохраняет их согласованность в любом направлении (правка проектного решения может потребовать обновления предложения). Код при этом не меняется. Каждая правка предварительно согласуется с вами. См. справочник команды update: там описано, как она обрабатывает отсутствующие файлы, не создавая новый артефакт.

Если изменение уже реализовано, команда предложит запустить /opsx:apply, чтобы обновить код по новому плану. Если правки меняют цель изменения, начните заново. См. раздел Когда обновить изменение, а когда начать заново.

/opsx:sync

Объединяет дельта-спецификации текущего изменения с основными в openspec/specs/, не архивируя изменение: оно остаётся активным. Применяется вся дельта: требование в ## REMOVED удаляется из основной спецификации, а переименованное требование получает новое название на месте. Содержимое, не затронутое дельтой, остаётся без изменений. Синхронизация необязательна — если вы её не выполнили, archive предложит сделать это. Используйте sync, когда нужно обновить основные спецификации до архивации, когда параллельное изменение зависит от только что добавленных спецификаций или когда вы хотите проверить объединённую основную спецификацию.

/opsx:archive # После завершения переместить в архив (при необходимости предложит синхронизировать спецификации)

Когда обновить изменение, а когда начать заново

Заголовок раздела «Когда обновить изменение, а когда начать заново»

Предложение и спецификации можно менять до начала реализации. Но в какой момент уточнение превращается в «другую работу»?

A proposal описывает три вещи:

  1. Цель — какую проблему вы решаете?
  2. Область работ — что входит и что не входит в задачу?
  3. Подход — как вы будете её решать?

Вопрос в том, что именно изменилось и насколько.

Цель не изменилась, уточнилась реализация

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

Область работ сужается

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

Исправления с учётом полученных знаний

  • структура кодовой базы оказалась не такой, как вы предполагали;
  • зависимость работает не так, как ожидалось;
  • «использовать переменные CSS» → «вместо этого использовать префикс dark: в Tailwind».

Цель принципиально изменилась

  • теперь решается другая проблема;
  • «добавить тёмную тему» → «создать полноценную систему тем с пользовательскими цветами, шрифтами и интервалами».

Область работ слишком разрослась

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

Исходное изменение можно завершить

  • исходную работу уже можно отметить как «готово»;
  • новая работа самостоятельна, а не является уточнением старой;
  • завершите «добавить MVP тёмной темы» → архивируйте → создайте новое изменение «улучшить тёмную тему».
┌─────────────────────────────────────┐
│ Это та же самая работа? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Та же цель? Совпадение >50%? Можно ли считать
Та же проблема? Та же область? исходную работу
│ │ «готовой» без этих правок?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
ОБНОВИТЬ НОВОЕ ОБНОВИТЬ НОВОЕ ОБНОВИТЬ НОВОЕ
Проверка Обновление Новое изменение
Суть «То же самое, но уточнённое» «Другая работа»
Пересечение областей Более 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 ◄── Glob-шаблон │ │
│ │ requires: [proposal] ◄── Доступно после proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Движок графа артефактов │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Топологическая сортировка (порядок зависимостей) │ │
│ │ • Определение состояния (наличие файлов) │ │
│ │ • Создание подробных инструкций (шаблоны + контекст) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Совместимость с редакторами (Claude Code, Cursor, Devin) │
│ • Навыки запрашивают структурированные данные у CLI │
│ • Полная настройка через файлы схем │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

Артефакты образуют направленный ациклический граф (DAG). Зависимости — опоры, а не ограничения:

proposal
(корневой узел)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(требуется: (требуется:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(требуется:
specs, design)
│
▼
┌──────────────┐
│ APPLY │
│ (требуется: │
│ tasks) │
└──────────────┘

Переходы состояния:

ЗАБЛОКИРОВАНО ──────────► ГОТОВО ───────────────► ВЫПОЛНЕНО
│ │ │
Нет всех Все зависимости Файл существует
зависимостей ВЫПОЛНЕНЫ в файловой системе

Устаревший процесс — агент получает статические инструкции:

User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Статические инструкции: │
│ • Создать proposal.md │
│ • Создать tasks.md │
│ • Создать design.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", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Шаг 2: получить подробные инструкции для готового артефакта │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Спецификация\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 продолжит
│ │ с места остановки
│ │
│ └── Создаёт ОДИН артефакт и показывает, что разблокировано
│
└── Создаёт каркас изменения и ждёт указаний

Создавайте пользовательские рабочие процессы с помощью команд управления схемами:

Окно терминала
# Создать новую схему с нуля (интерактивный режим)
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:

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
Итерации Фиксированные этапы Гибкий процесс, можно изменить любой материал
Поддержка редакторов Конфигураторы/адаптеры отдельных инструментов Единый каталог навыков

Схемы определяют доступные артефакты и их зависимости. Сейчас доступна следующая схема:

  • 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.

HagiCode

HagiCode — агентная среда разработки со структурированными процессами, параллельным выполнением несколькими агентами и интерфейсами Hero Dungeon.

Превращайте идеи в полезное ПО с более умным, быстрым и увлекательным агентным рабочим процессом.

Главный экран HagiCode в светлой теме
  • SmartСтруктурированные процессы превращают намерение в исполнимый путь от идеи до готового изменения.
  • EfficientМультиагентные процессы параллельно продвигают исследование, реализацию и проверку.
  • FunHero Dungeon делает длительную совместную разработку наглядной и увлекательной.
Перейти на HagiCode