OpenSpec

Миграция на OPSX ​

Это руководство поможет вам перейти от устаревшего рабочего процесса OpenSpec к OPSX. Миграция спроектирована так, чтобы быть максимально плавной: ваша текущая работа сохраняется, а новая система предоставляет больше гибкости.

Что меняется? ​

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

АспектУстаревшийOPSX
Команды/openspec:proposal, /openspec:apply, /openspec:archiveПо умолчанию: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (дополнительные команды расширенного рабочего процесса)
Рабочий процессСоздание всех артефактов одновременноСоздание поэтапно или все сразу — на ваш выбор
Возврат назадНеудобные контрольные точки фазЕстественный — обновляйте любой артефакт в любое время
КастомизацияФиксированная структураНа основе схемы, полностью настраиваемая
КонфигурацияCLAUDE.md с маркерами + project.mdЧистая конфигурация в openspec/config.yaml

Изменение философии: Работа не является линейной. OPSX перестает делать вид, что это так.

Перед началом ​

Ваши существующие данные в безопасности ​

Процесс миграции разработан с учётом сохранения данных:

  • Активные изменения в openspec/changes/ — Полностью сохраняются. Вы можете продолжить работу с ними с помощью команд OPSX.
  • Архивированные изменения — Не изменяются. Ваша история остаётся нетронутой.
  • Основные спецификации в openspec/specs/ — Не изменяются. Это ваш источник истины.
  • Ваше содержимое в CLAUDE.md, AGENTS.md и т.д. — Сохраняется. Удаляются только маркерные блоки OpenSpec; всё, что вы написали, остаётся.

Что будет удалено ​

Только файлы, управляемые OpenSpec, которые заменяются:

ЧтоПочему
Устаревшие каталоги/файлы slash-командЗаменены новой системой skills
openspec/AGENTS.mdУстаревший триггер рабочего процесса
Маркеры OpenSpec в CLAUDE.md, AGENTS.md и т.д.Больше не нужны

Расположение устаревших команд по инструментам (примеры — ваш инструмент может отличаться):

  • Claude Code: .claude/commands/openspec/
  • Cursor: .cursor/commands/openspec-*.md
  • Devin Desktop, ранее Windsurf: .windsurf/workflows/openspec-*.md
  • Cline: .clinerules/workflows/openspec-*.md
  • Roo: .roo/commands/openspec-*.md
  • GitHub Copilot: .github/prompts/openspec-*.prompt.md (только расширения IDE; не поддерживается в Copilot CLI)
  • Codex: OpenSpec теперь использует канонический путь .agents/skills/openspec-*. Файлы SKILL.md, управляемые OpenSpec, в бывшем пути .codex/skills согласуются только после появления замен; пользовательские файлы и расходящиеся копии остаются на месте. Если дерево .agents без маркеров уже содержит skills OpenSpec, OpenSpec сохраняет существующий рендеринг Codex ($openspec-*) или универсальный (/openspec-*), вместо того чтобы угадывать из устаревшего каталога. Выберите codex явно с помощью openspec init, чтобы переключить владельца. Очистка устаревших prompt-файлов по-прежнему нацелена только на разрешённые OpenSpec имена файлов в $CODEX_HOME/prompts или ~/.codex/prompts.
  • И другие (Augment, Continue, Amazon Q и т.д.)

Миграция определяет, какие инструменты у вас настроены, и очищает их устаревшие файлы.

Список удалений может показаться длинным, но это все файлы, которые OpenSpec изначально создал. Ваше собственное содержимое никогда не удаляется.

Что требует вашего внимания ​

Один файл требует ручной миграции:

openspec/project.md — Этот файл не удаляется автоматически, так как может содержать контекст проекта, который вы написали. Вам нужно:

  1. Оценить его содержимое
  2. Переместить полезный контекст в openspec/config.yaml (см. рекомендации ниже)
  3. Удалить файл, когда будете готовы

Почему мы внесли это изменение:

Старый project.md был пассивным — агенты могли его прочитать, могли не прочитать, могли забыть прочитанное. Мы обнаружили, что надёжность была непостоянной.

Новый контекст в config.yaml активно внедряется в каждый запрос планирования OpenSpec. Это означает, что ваши соглашения о проекте, технологический стек и правила всегда присутствуют, когда ИИ создаёт артефакты. Более высокая надёжность.

Компромисс:

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

  • Технологический стек и ключевые соглашения
  • Непринятые ограничения, о которых ИИ нужно знать
  • Правила, которые часто игнорировались ранее

Не переживайте из-за идеальности. Мы всё ещё изучаем, что работает лучше всего, и будем улучшать механизм внедрения контекста по мере экспериментов.

Запуск миграции ​

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

  • Новые установки по умолчанию используют профиль core (propose, explore, apply, update, sync, archive).
  • Мигрированные установки сохраняют ваши ранее установленные рабочие процессы, записывая профиль custom при необходимости.

Использование openspec init ​

Выполните это, если вы хотите добавить новые инструменты или перенастроить, какие инструменты настроены:

bash
openspec init

Команда init обнаруживает устаревшие файлы и направляет вас через очистку:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

Что происходит, когда вы говорите «да»:

  1. Устаревшие каталоги slash-команд удаляются
  2. Маркеры OpenSpec удаляются из CLAUDE.md, AGENTS.md и т.д. (ваше содержимое остаётся)
  3. openspec/AGENTS.md удаляется
  4. Новые skills устанавливаются в .claude/skills/
  5. Создаётся openspec/config.yaml с базовой схемой

Использование openspec update ​

Выполните это, если вы просто хотите мигрировать и обновить ваши существующие инструменты до последней версии:

bash
openspec update

Команда update также обнаруживает и очищает устаревшие артефакты, а затем обновляет сгенерированные skills/commands в соответствии с вашим текущим профилем и настройками доставки.

Непроактивные / CI-окружения ​

Для скриптовой миграции:

bash
openspec init --force --tools claude

Флаг --force пропускает запросы и автоматически принимает очистку.

Это включает очистку prompt-файлов Codex, управляемых OpenSpec, в глобальном каталоге prompt Codex. Очистка нацелена только на разрешённые OpenSpec имена устаревших prompt-файлов Codex, удаляет их только после появления замен .agents/skills/openspec-*, и сохраняет все остальные файлы.

Миграция project.md в config.yaml ​

Старый openspec/project.md был свободным markdown-файлом для контекста проекта. Новый openspec/config.yaml структурирован и — что критично — внедряется в каждый запрос планирования, так что ваши соглашения всегда присутствуют, когда ИИ работает.

До (project.md) ​

markdown
# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

После (config.yaml) ​

yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Ключевые различия ​

project.mdconfig.yaml
Свободный markdownСтруктурированный YAML
Один блок текстаОтдельный контекст и правила для каждого артефакта
Непонятно, когда используетсяКонтекст появляется во ВСЕХ артефактах; правила — только в соответствующих
Нет выбора схемыЯвное поле schema: задаёт рабочий процесс по умолчанию

Что оставить, что убрать ​

При миграции будьте избирательны. Спросите себя: «Нужно ли ИИ это для каждого запроса планирования?»

Хорошие кандидаты для context:

  • Технологический стек (языки, фреймворки, базы данных)
  • Ключевые архитектурные паттерны (monorepo, микросервисы и т.д.)
  • Непринятые ограничения («мы не можем использовать библиотеку X, потому что...»)
  • Критические соглашения, которые часто игнорируются

Переместите в rules:

  • Форматирование, специфичное для артефакта («используйте Given/When/Then в specs»)
  • Критерии ревью («предложения должны включать планы отката»)
  • Они появляются только для соответствующего артефакта, делая другие запросы легче

Полностью исключите

  • Общие лучшие практики, которые ИИ уже знает
  • Развёрнутые объяснения, которые можно суммировать
  • Исторический контекст, не влияющий на текущую работу

Шаги миграции ​

  1. Создайте config.yaml (если он ещё не создан при init):

    yaml
    schema: spec-driven

  2. Добавьте ваш контекст (будьте лаконичны — это попадает в каждый запрос):

    yaml
    context: |
  Your project background goes here.
  Focus on what the AI genuinely needs to know.

  3. Добавьте правила для каждого артефакта (необязательно):

    yaml
    rules:
  proposal:
    - Your proposal-specific guidance
  specs:
    - Your spec-writing rules

  4. Удалите project.md, когда переместите всё полезное.

Не переусложняйте. Начните с основного и итерируйте. Если вы заметите, что ИИ пропускает что-то важное, добавьте это. Если контекст кажется раздутым, сократите его. Это живой документ.

Нужна помощь? Используйте этот промпт ​

Если вы не уверены, как дистиллировать ваш project.md, спросите вашего ИИ-ассистента:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

ИИ поможет вам определить, что является существенным, а что можно сократить.

Новые команды ​

Доступность команд зависит от профиля:

По умолчанию (профиль core):

КомандаНазначение
/opsx:proposeСоздать изменение и сгенерировать артефакты планирования за один шаг
/opsx:exploreОбсудить идеи без структуры
/opsx:applyРеализовать задачи из tasks.md
/opsx:updateПересмотреть артефакты планирования изменения и сохранить их согласованность
/opsx:syncСлить delta-спецификации в основные спецификации
/opsx:archiveЗавершить и архивировать изменение

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

КомандаНазначение
/opsx:newНачать новый каркас изменения
/opsx:continueСоздать следующий артефакт (по одному)
/opsx:ffБыстрое продвижение — создать артефакты планирования сразу
/opsx:verifyПроверить, что реализация соответствует спецификациям
/opsx:bulk-archiveАрхивировать несколько изменений сразу
/opsx:onboardРуководимый сквозной процесс онбординга

Включите расширенные команды с помощью openspec config profile, затем выполните openspec update.

Соответствие команд от устаревших ​

УстаревшаяЭквивалент OPSX
/openspec:proposal/opsx:propose (по умолчанию) или /opsx:new, затем /opsx:ff (расширенный)
/openspec:apply/opsx:apply
/openspec:archive/opsx:archive

Новые возможности ​

Эти возможности являются частью набора команд расширенного рабочего процесса.

Постепенное создание артефактов:

/opsx:continue

Создаёт один артефакт за раз на основе зависимостей. Используйте это, когда вы хотите просмотреть каждый шаг.

Режим исследования:

/opsx:explore

Обсудите идеи с партнёром перед принятием изменения.

Понимание новой архитектуры ​

От фиксированных фаз к гибкости ​

Устаревший процесс заставлял линейное продвижение:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

If you're in implementation and realize the design is wrong?
Too bad. Phase gates don't let you go back easily.

OPSX использует действия, а не фазы:

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

Граф зависимостей ​

Артефакты образуют ориентированный граф. Зависимости являются активаторами, а не шлюзами:

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

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

Skills и команды ​

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

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX использует развивающийся стандарт skills:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Skills распознаются во многих инструментах ИИ-кодирования и предоставляют более полные метаданные.

Codex в OPSX поддерживает только skills. OpenSpec больше не генерирует пользовательские файлы подсказок для Codex; вместо этого используйте сгенерированные директории .agents/skills/openspec-*.

Продолжение существующих изменений ​

Ваши текущие изменения бесшовно работают с командами OPSX.

У вас есть активное изменение из устаревшего рабочего процесса?

/opsx:apply add-my-feature

OPSX читает существующие артефакты и продолжает с того места, где вы остановились.

Хотите добавить дополнительных артефактов к существующему изменению?

/opsx:continue add-my-feature

Показывает, что готово к созданию на основе уже существующего.

Нужно увидеть статус?

bash
openspec status --change add-my-feature

Новая система конфигурации ​

Структура config.yaml ​

yaml
# Обязательно: Схема по умолчанию для новых изменений
schema: spec-driven

# Необязательно: Контекст проекта (макс 50КБ)
# Внедряется во все инструкции артефактов
context: |
  Your project background, tech stack,
  conventions, and constraints.

# Необязательно: Правила для каждого артефакта
# Внедряется только в соответствующие артефакты
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

Разрешение схемы ​

При определении, какую схему использовать, OPSX проверяет по порядку:

  1. Флаг CLI: --schema <name> (наивысший приоритет)
  2. Метаданные изменения: .openspec.yaml в директории изменения
  3. Конфигурация проекта: openspec/config.yaml
  4. По умолчанию: spec-driven

Доступные схемы ​

СхемаАртефактыЛучше всего для
spec-drivenproposal → specs → design → tasksБольшинство проектов

Список всех доступных схем:

bash
openspec schemas

Пользовательские схемы ​

Создайте свой собственный рабочий процесс:

bash
openspec schema init my-workflow

Или ответвите существующую:

bash
openspec schema fork spec-driven my-workflow

Смотрите Кастомизация для подробностей.

Устранение неполадок ​

"Legacy files detected in non-interactive mode" ​

Вы работаете в CI или среде без интерактивного режима. Используйте:

bash
openspec init --force

Команды не появляются после миграции ​

Перезапустите вашу IDE. Skills обнаруживаются при запуске.

"Unknown artifact ID in rules" ​

Проверьте, что ключи в rules: соответствуют идентификаторам артефактов вашей схемы:

  • spec-driven: proposal, specs, design, tasks

Запустите это, чтобы увидеть допустимые идентификаторы:

bash
openspec schemas --json

Конфигурация не применяется ​

  1. Убедитесь, что файл находится в openspec/config.yaml (не .yml)
  2. Проверьте синтаксис YAML
  3. Изменения конфигурации вступают в силу немедленно — перезапуск не требуется

project.md не перенесён ​

Система намеренно сохраняет project.md, потому что он может содержать ваш пользовательский контент. Просмотрите его вручную, перенесите полезные части в config.yaml, затем удалите.

Хотите увидеть, что будет очищено? ​

Запустите init и отклоните запрос очистки — вы увидите полную сводку обнаружения без внесения каких-либо изменений.

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

Файлы после миграции ​

project/
├── openspec/
│   ├── specs/                    # Unchanged
│   ├── changes/                  # Unchanged
│   │   └── archive/              # Unchanged
│   └── config.yaml               # NEW: Project configuration
├── .claude/
│   └── skills/                   # NEW: OPSX skills
│       ├── openspec-propose/     # default core profile
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # expanded profile adds new/continue/ff/etc.
├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
└── AGENTS.md                     # OpenSpec markers removed, your content preserved

Что удалено ​

  • .claude/commands/openspec/ — заменено на .claude/skills/
  • openspec/AGENTS.md — устарело
  • openspec/project.md — перенесите в config.yaml, затем удалите
  • Блоки маркеров OpenSpec в CLAUDE.md, AGENTS.md и др.

Шпаргалка команд ​

text
/opsx:propose      Start quickly (default core profile)
/opsx:apply        Implement tasks
/opsx:archive      Finish and archive

# Expanded workflow (if enabled):
/opsx:new          Scaffold a change
/opsx:continue     Create next artifact
/opsx:ff           Create planning artifacts

Получение помощи ​