Урок 15.15. FAQ, Troubleshooting и Migration Guide

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

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

• FAQ - ответы на вопросы, которые задают чаще всего: где вводить слэш-команды, чем /opsx:propose отличается от /opsx:new, коммитить ли openspec/;
• Troubleshooting - конкретные исправления конкретных симптомов: команда не находится, команды не появляются, validate ругается, archive не завершается;
• Migration Guide - переход со старого phase-locked workflow /openspec:* на OPSX: что сохраняется, что удаляется, что требует ручного внимания.

По ходу урока много отсылок к предыдущим урокам: здесь собраны вопросы, которые в них уже разобраны, - FAQ дает краткие ответы и указывает, где полный разбор.

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

Три документа отвечают на три разных типа вопросов:

«Как это устроено?»      → FAQ: короткий ответ + ссылка на полный урок
«Что-то сломалось»       → Troubleshooting: симптом → причина → исправление
«Я на старом workflow»   → Migration Guide: что сохранится, что переедет

Общий знаменатель: почти все проблемы новичка сводятся к двум корням - перепутать терминал с чатом агента (урок 15.4) и устаревшая версия CLI без openspec update (урок 15.1).

Часть 1. FAQ

Основы

Что такое OpenSpec одним предложением?

Легкий слой, который заставляет вас и вашего AI-ассистента письменно согласовать, что строится, до написания кода.

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

AI-ассистенты уверены в себе даже когда неправы. Когда требования живут только в треде чата, AI заполняет пробелы догадками - и вы обнаруживаете это после появления кода. OpenSpec переносит соглашение на более ранний этап, где ошибки дешевы. Полное обоснование - урок 15.3.

Обязательно использовать это для всего?

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

Работает ли на большом существующем codebase, или только на новых проектах?

Существующие codebase - главная сцена. OpenSpec brownfield-first: вы не описываете всё приложение заранее, а пишете спецификации только на то, что затрагивает каждое изменение, и specs достраиваются со временем вокруг реальной работы. Отдельный разбор - урок 15.11.

Привязан ли к одному AI-инструменту?

Нет. OpenSpec работает с 30+ ассистентами, включая Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex и других. Полный список - урок 15.13.

Запуск команд

Где вводить /opsx:propose?

В чате AI-ассистента, не в терминале. Это единственная самая частая путаница; ей посвящен урок 15.4. Коротко: openspec ... выполняется в терминале, /opsx:... - в чате.

Как «включить интерактивный режим»?

Отдельного режима нет. Вы просто открываете AI-ассистент как обычно и вводите слэш-команду в его чат - слэш-команда и есть способ «войти» в OpenSpec. Единственная по-настоящему интерактивная терминальная функция - openspec view, дашборд для просмотра specs и изменений.

Ввел слэш-команду - ничего не произошло. Почему?

Вероятнее всего: вы ввели ее в терминале вместо чата, использовали написание, которое инструмент не регистрирует, или команды еще не установлены. Если файлы отсутствуют или инструмент не настроен - выполните openspec init; openspec update только обновляет уже существующие файлы. Затем перезапустите ассистента и используйте форму из подсказки «Getting started».

Почему в одном инструменте синтаксис /opsx:propose, а в другом /opsx-propose?

Каждый инструмент представляет кастомные команды немного по-разному, и OpenSpec пишет имена так, как инструмент загружает файл. Файл opsx-propose.md вводится как /opsx-propose; файл в commands/opsx/ - как /opsx:propose. Инструменты со skills вместо команд используют имя skill: Codex требует $openspec-propose, Kimi Code - /skill:openspec-propose. Полная таблица - уроки 15.4 и 15.13.

Чем skill отличается от command?

И то и другое - файлы, которые пишет OpenSpec, чтобы ассистент мог выполнять workflow. Skills (.../skills/openspec-*/SKILL.md) - новый межинструментный стандарт; commands (.../commands/opsx-*) - старые per-tool слэш-файлы. Выбирать не нужно: вы вводите слэш-команду, а OpenSpec ставит то, что использует ваш инструмент.

Workflow

С чего начать, если неясно, что строить?

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

Какой самый простой поток?

/opsx:explore (опционально)   затем   /opsx:propose <что хотите>   затем   /opsx:apply   затем   /opsx:archive

Explore - продумать, propose - черновик плана, apply - построить, archive - подшить. Пропустите explore, если точно знаете, что хотите.

Чем /opsx:propose отличается от /opsx:new?

/opsx:propose - дефолтная одношаговая команда: создает изменение и сразу черновит все планировочные артефакты. /opsx:new входит в расширенный набор и только создает пустой scaffold, оставляя создавать артефакты по одному через /opsx:continue (или все сразу через /opsx:ff). Используйте propose, если не нужен пошаговый контроль. Справочник команд - урок 15.5.

Что такое профили core и expanded?

Профиль решает, какие слэш-команды устанавливаются. Core (дефолт) дает propose, explore, apply, update, sync, archive. Expanded добавляет new, continue, ff, verify, bulk-archive, onboard для более тонкого контроля. Переключение - openspec config profile, применение - openspec update.

Нужно ли запускать /opsx:sync?

Обычно нет. Sync вливает дельта-спецификации изменения в основные specs, и /opsx:archive сам предложит это сделать. Запускайте sync вручную, только когда нужно слить specs до архивации - например, на долгоживущем изменении.

Как править proposal, spec или task после старта?

Просто правьте файл. Каждый артефакт - обычный Markdown в openspec/changes/<name>/, заблокированных фаз и специального режима правки нет. Правьте вручную или попросите AI («update the design to use a queue») - и продолжайте. AI всегда работает от текущего содержимого файлов. Разбор - урок 15.10.

Можно вернуться и изменить план, когда часть уже реализована?

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

Я правил код вручную. Как это согласовать со спецификацией?

Синхронизируйте до архивации: архивация делает specs записью истины. Если код теперь правильный - обновите дельта-спецификацию под то, что реально поставили; если правильная спецификация - продолжайте строить, пока код не согласуется. /opsx:verify выявляет расхождения.

Когда обновлять существующее изменение, а когда начинать новое?

Обновляйте, когда это та же работа в отточенном виде. Начинайте заново, когда intent принципиально изменился или scope взорвался в другую работу. Эвристика с примерами - урок 15.14.

Что если сессия теряет контекст или требования меняются посреди реализации?

Здесь specs отрабатывают себя. План живет в файлах, а не только в истории чата: можно очистить контекст, начать свежую сессию AI и продолжить с /opsx:apply - команда читает артефакты и продолжает с первой непроверенной задачи. Если требования изменились - отредактируйте артефакты под новую реальность и продолжайте. Чистое контекстное окно вообще дает лучшие результаты: очищайте его перед реализацией.

Коммитить ли openspec/ в git?

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

Спецификации и изменения

Что кладется в spec, а что в design?

Spec описывает наблюдаемое поведение: что система делает, входы, выходы, условия ошибок. Design описывает, как это построить: технический подход, архитектурные решения, изменения файлов. Если реализация может измениться без изменения видимого снаружи поведения - это в design, а не в spec. Подробно - урок 15.3.

Что такое дельта-спецификация?

Спецификация, описывающая только то, что меняется, - секциями ADDED, MODIFIED, REMOVED, - вместо пересказа всей спецификации. Так OpenSpec аккуратно обрабатывает правки существующих систем. Разбор - уроки 15.3 и 15.10.

Куда попадают архивные изменения?

В openspec/changes/archive/YYYY-MM-DD-<name>/, со всеми артефактами. Изменение уходит из списка активных. Изменение с явным retire_capabilities: true может также удалить основную спецификацию возможности, когда убирает ее последнее требование.

Конфигурация и кастомизация

Как сообщить AI о своем стеке?

Через context: в openspec/config.yaml. Текст инжектится в каждый запрос планирования, так что AI всегда знает ваш стек и конвенции. Разбор - урок 15.13.

Можно генерировать specs не на английском?

Да. Добавьте языковую инструкцию в context: конфига; шаблоны для нескольких языков - в уроке 15.13.

Можно изменить сам workflow?

Да, кастомными схемами. Схема определяет, какие артефакты существуют и как зависят друг от друга. Форкните дефолтную: openspec schema fork spec-driven my-workflow - и правьте. Разбор - урок 15.13.

Модели, приватность, обновления

Какую модель использовать?

OpenSpec лучше всего работает с моделями с высоким уровнем рассуждения; README рекомендует Codex 5.5 и Opus 4.7 и для планирования, и для реализации. Держите контекстное окно чистым: очищайте перед реализацией.

OpenSpec собирает данные?

Анонимную статистику использования: только имена команд и версию. Без аргументов, путей, содержимого и персональных данных; в CI отключается автоматически. Опция отключения: export OPENSPEC_TELEMETRY=0 или export DO_NOT_TRACK=1.

Как обновиться?

Два шага: обновить пакет (npm install -g @fission-ai/openspec@latest), затем выполнить openspec update внутри каждого проекта, чтобы перегенерировать skills и команды.

Как удалить OpenSpec?

Команды удаления нет: это просто глобальный пакет плюс файлы в проекте. Удалите пакет (npm uninstall -g @fission-ai/openspec) и опционально каталог openspec/ и сгенерированные файлы инструментов. Пошагово, включая что безопасно оставить, - урок 15.1.

Где задать вопрос или сообщить об ошибке?

Discord: https://discord.gg/YctCnvvshC; GitHub Issues: https://github.com/Fission-AI/OpenSpec/issues; из терминала: openspec feedback "your message" открывает GitHub issue.

Часть 2. Troubleshooting

Каждый пункт: симптом → вероятная причина → исправление.

Установка и настройка

openspec: command not found

CLI не установлен или shell его не находит. Установите глобально и проверьте:

npm install -g @fission-ai/openspec@latest
openspec --version

Если установился, но не находится - глобальный bin-каталог npm, вероятно, не в PATH. Выполните npm prefix -g, чтобы увидеть, где живут глобальные пакеты: на macOS и Linux бинарники - в bin/ этого каталога, на Windows - прямо в нем. Убедитесь, что путь в PATH (команда npm bin -g удалена в npm 9).

Если вы использовали AI-установку из урока 15.1, это ожидаемая точка передачи: промпт велит ассистенту показать вам изменение PATH, а не править shell-файлы самому.

«Requires Node.js 20.19.0 or higher»

OpenSpec исполняется на Node 20.19.0+. Проверьте и обновите: node --version. Если ставили через bun - помните, что OpenSpec все равно работает на Node: нужен Node 20.19.0+ в PATH.

openspec init не настроил мой AI-инструмент

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

openspec init --tools claude,cursor

Полный список ID - урок 15.13; --tools all - всё, --tools none - пропустить.

Команды не появляются

Если /opsx:propose (или эквивалент вашего инструмента) не появляется или ничего не делает - идите по списку, от самого быстрого к проверке:

1. Возможно, вы не там. Слэш-команды вводятся в чате AI-ассистента, не в терминале. Ввели /opsx:propose в shell - вот и проблема (урок 15.4).

2. Перегенерируйте файлы. Из корня проекта:

   bashCopy

   openspec update
   

   Команда перезаписывает файлы skills и команд для всех настроенных инструментов. Инструкции берутся из установленного CLI, поэтому устаревший CLI сообщает «всё актуально», не записывая новые workflow. openspec update теперь это проверяет и предлагает обновиться - соглашайтесь, если увидите.

3. Перезапустите ассистента. Большинство инструментов сканирует skills и команды при старте. Новое окно часто решает.

4. Подтвердите, что файлы существуют. Для Claude Code проверьте, что .claude/skills/ содержит каталоги openspec-*. У других инструментов свои каталоги - полный список в уроке 15.13.

5. Проверьте, что проект инициализирован. Skills пишутся по проектам. Если склонировали репозиторий или перешли в другую папку - выполните openspec init (или openspec update) там.

6. Подтвердите, что инструмент поддерживает командные файлы. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent и shared .agents не получают командных файлов opsx-* - они используют вызовы по skill: $openspec-propose в Codex, /skill:openspec-propose в Kimi Code, /openspec-propose у остальных. Amazon Q получает командные файлы, но загружает их в библиотеку промптов: там вводится @opsx-propose, не /opsx. Форма каждого инструмента - в уроке 15.13.

Работа с изменениями

«Change not found»

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

openspec list                    # активные изменения
/opsx:apply add-dark-mode        # назвать изменение в чате

И проверьте, что вы в правильном каталоге проекта.

«No artifacts ready»

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

openspec status --change <name>

Затем создайте недостающую зависимость. Помните порядок: proposal включает specs и design; specs и design вместе включают tasks.

openspec validate сообщает warnings или errors

Валидация проверяет specs и изменения на структурные проблемы. Читайте сообщение: оно называет файл и проблему.

openspec validate <name>           # один item
openspec validate --all            # всё
openspec validate --all --strict   # строже, хорошо для CI
openspec validate --archived       # провал, если у архивных изменений есть непроверенные задачи

Типовые причины - отсутствующая обязательная секция (спека без сценариев) или кривой заголовок дельты. Исправьте файл и перезапустите. Формат вывода - урок 15.6.

Одно сообщение заслуживает отдельной notes:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Требование MODIFIED заменяет весь блок требования целиком, поэтому должно нести все сценарии, которые переживают изменение, - не только отредактированные. Скопируйте названные сценарии из openspec/specs/<capability-path>/spec.md обратно в дельту, сохраняя каталоги домена в пути. Часто проявляется на старом изменении после того, как чужое изменение добавило сценарий в то же требование: archive такое изменение отклонит в любом случае, а валидация теперь сообщает об этом до реализации.

AI создал неполные или неверные артефакты

У AI не хватило контекста. Помогают несколько рычагов:

• добавьте контекст проекта в openspec/config.yaml, чтобы стек и конвенции инжектились в каждый запрос;
• добавьте rules: по артефактам - для указаний, относящихся, например, только к specs;
• дайте более детальное описание при propose;
• используйте расширенный /opsx:continue - создавать по одному артефакту за раз и ревьюить каждый, вместо /opsx:ff, делающего всё сразу.

Archive не завершается или предупреждает о незавершенных задачах

Archive не блокируется на незавершенных задачах, но предупреждает: архивация обычно означает, что работа сделана. Если задачи остались намеренно (подшиваете частичное изменение) - продолжайте. Иначе сначала завершите задачи. Archive также предложит синхронизировать дельта-спецификации в основные, если вы еще не синхронизировали, - соглашайтесь, если нет причин не соглашаться.

«User force closed the prompt with 0 null»

Что-то запустило openspec archive там, где никто не может ответить на вопрос - агент, вызывающий команду из инструмента, CI-джоба или любой shell с закрытым stdin. Archive задает до трех подтверждений, и безответное раньше падало с сырым сообщением.

Передайте --yes, чтобы ответить заранее:

openspec archive <change-name> --yes

Сохраняйте флаги, которые уже передавали: --skip-specs и --no-validate меняют поведение archive, поэтому голый --yes - не та же команда. Текущие версии сами называют нужный флаг и печатают строку Fix: для копирования. Если имели в виду выбор из списка - передайте имя изменения явно: пикеру тоже нужен ответ.

Если же вы запускали archive с выводом, перенаправленным в файл, и передавали ответ (printf 'y\n' | openspec archive ...), старые версии писали escape-коды терминала в захват при отрисовке промпта - местами достаточно, чтобы раздуть файл. Текущие версии читают промпты как простой текст, когда stdout - не терминал, а archive без аргументов просит передать имя изменения вместо отрисовки меню в захват. Так что перенаправленные и агентные запуски остаются чистыми; --yes (с именем изменения) пропускает промпты целиком.

Конфигурация

config.yaml не применяется

Три обычных подозреваемых:

1. Неверное имя файла. Должно быть openspec/config.yaml, не .yml.
2. Невалидный YAML. Прогоните через валидатор; CLI тоже сообщает синтаксические ошибки с номерами строк.
3. Вы ждали перезапуска. Он не нужен: изменения конфига вступают в силу немедленно.

«Unknown artifact ID in rules: X»

Ключ под rules: не совпадает ни с одним артефактом вашей схемы. Для дефолтной spec-driven валидны proposal, specs, design, tasks. ID любой схемы:

openspec schemas --json

«Context too large»

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

«Schema not found»

Имени схемы не существует. Посмотрите доступные и проверьте написание:

openspec schemas                    # доступные схемы
openspec schema which <name>        # откуда резолвится
openspec schema init <name>         # создать свою

Миграция со старого workflow

«Legacy files detected in non-interactive mode»

Вы в CI или неинтерактивном shell, и OpenSpec нашел старые файлы для очистки, но не может спросить. Одобрите автоматически:

openspec init --force

Для Codex OpenSpec может найти старые управляемые prompt-файлы в $CODEX_HOME/prompts или ~/.codex/prompts. Очистка ограничена allowlist-именами легаси-промптов OpenSpec, неинтерактивный openspec init удаляет только файлы, у которых существуют замены .agents/skills/openspec-*. Неинтерактивный openspec update вообще не трогает легаси-очистку без --force.

После миграции команды не появились

Перезапустите IDE: skills обнаруживаются при старте. Если не появились - openspec update и проверка путей по уроку 15.13.

Мой старый project.md не мигрировал

Это намеренно. OpenSpec никогда не удаляет project.md автоматически: там может быть ваш контекст. Перенесите полезное в context: конфига, затем удалите файл сами - ниже, в части 3, есть готовый промпт для AI.

Часть 3. Migration Guide: переход на OPSX

Что меняется

OPSX заменяет старый phase-locked workflow гибким, action-подходом:

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

Прежде чем начать: что сохраняется

Миграция спроектирована с расчетом на сохранение:

• активные изменения в openspec/changes/ - полностью сохраняются; продолжайте их командами OPSX;
• архивные изменения - нетронуты; история цела;
• основные specs в openspec/specs/ - нетронуты; это ваш источник истины;
• ваш контент в CLAUDE.md, AGENTS.md и т.д. - сохраняется; удаляются только маркерные блоки OpenSpec, всё написанное вами остается.

Что удаляется

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

Примеры легаси-расположений команд: .claude/commands/openspec/ (Claude Code), .cursor/commands/openspec-*.md (Cursor), .windsurf/workflows/openspec-*.md (Devin Desktop), .clinerules/workflows/openspec-*.md (Cline), .roo/commands/openspec-*.md (Roo), .github/prompts/openspec-*.prompt.md (GitHub Copilot, только IDE-расширения). Для Codex OpenSpec теперь использует канонический путь .agents/skills/openspec-*: управляемые SKILL.md под бывшим .codex/skills сверяются только после появления замен; кастомные файлы остаются на месте. Миграция сама находит настроенные инструменты и чистит их легаси-файлы.

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

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

Один файл требует ручной миграции - openspec/project.md. Он не удаляется автоматически, потому что может содержать написанный вами контекст. Порядок:

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

Зачем: старый project.md был пассивным - агенты могли его прочесть, могли не прочесть, могли забыть прочитанное. Надежность была непостоянной. Новый context в config.yaml активно инжектится в каждый запрос планирования OpenSpec: конвенции, стек и правила всегда присутствуют, когда AI создает артефакты. Плата: контекст попадает в каждый запрос, поэтому должен быть сжатым - только то, что действительно важно.

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

И openspec init, и openspec update находят легаси-файлы и проводят одну и ту же очистку. Новые установки дефолтятся на профиль core; мигрированные сохраняют ранее установленные workflow, при необходимости записывая профиль custom.

openspec init - если нужно добавить инструменты или перенастроить, какие настроены:

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)

По «да» происходит: удаление легаси-каталогов команд, снятие маркеров OpenSpec из CLAUDE.md/AGENTS.md (ваш контент остается), удаление openspec/AGENTS.md, установка новых skills в .claude/skills/, создание openspec/config.yaml с дефолтной схемой.

openspec update - если нужно просто мигрировать и обновить существующие инструменты до последней версии. Команда тоже находит и чистит легаси, затем перегенерирует skills/команды под текущий профиль.

Неинтерактивные/CI-среды:

openspec init --force --tools claude

--force пропускает промпты и авто-принимает очистку (включая легаси-промпты Codex в глобальном каталоге промптов - только allowlist-имена OpenSpec и только при существующих заменах).

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

До:

# 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

После:

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

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

Что оставить, что выбросить. Спрашивайте себя: «Нужно ли это AI в каждом запросе планирования?»

Хорошие кандидаты в context: - стек (языки, фреймворки, базы), ключевые архитектурные паттерны, неочевидные ограничения («не можем использовать библиотеку X, потому что...»), критичные конвенции, которые часто игнорировались.

В rules: переносите форматирование уровня артефакта («Given/When/Then в specs») и критерии ревью («proposal обязан включать план отката») - они появляются только у соответствующего артефакта, облегчая остальные запросы.

Выбрасывайте общие лучшие практики, которые AI и так знает, многословие, которое можно сжать, и исторический контекст, не влияющий на текущую работу.

Промпт для AI, если тяжело дистиллировать самому:

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 (таблица команд с назначениями - урок 15.5); расширенный набор включается openspec config profile + openspec update. Соответствие легаси:

Архитектурные отличия (фазы против действий, граф зависимостей, skills вместо per-tool команд) подробно разобраны в уроке 15.14 - здесь не повторяются.

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

Изменения в работе продолжаются командами OPSX без конвертации:

/opsx:apply add-my-feature        ← продолжить существующее изменение
/opsx:continue add-my-feature     ← добавить артефакты по готовности

openspec status --change add-my-feature   ← состояние

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

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

project/
├── openspec/
│   ├── specs/                    # без изменений
│   ├── changes/                  # без изменений
│   │   └── archive/              # без изменений
│   └── config.yaml               # НОВОЕ: конфигурация проекта
├── .claude/
│   └── skills/                   # НОВОЕ: skills OPSX
│       ├── openspec-propose/
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       └── ...
├── CLAUDE.md                     # маркеры OpenSpec сняты, контент сохранен
└── AGENTS.md                     # маркеры OpenSpec сняты, контент сохранен

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

/opsx:propose      начать быстро (дефолтный профиль core)
/opsx:apply        реализовать задачи
/opsx:archive      завершить и архивировать

# Расширенный набор (если включен):
/opsx:new          scaffold изменения
/opsx:continue     следующий артефакт
/opsx:ff           все планировочные артефакты

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

Практика

1. Смоделируйте три типовые поломки в тестовом проекте: выполните /opsx:propose в терминале (получите «command not found» от shell), выполните openspec status без изменений (ошибка выбора) и openspec show nonexistent --json (JSON с диагностикой). Сверьте симптомы с этим уроком.
2. Найдите форму вызова для своего инструмента в уроке 15.13 и проверьте чек-лист «команды не появляются» по шагам 1-6.
3. Если у вас есть легаси-проект OpenSpec (project.md, старые команды /openspec:*) - пройдите миграцию: openspec update, перенос project.md в config.yaml, перезапуск IDE.
4. В config.yaml проверьте лимиты: напишите context: больше 50 КБ и посмотрите на ошибку; исправьте, сжав текст.

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

• FAQ решает по верхам: слэш-команды - в чате агента, openspec - в терминале; самый простой поток - explore → propose → apply → archive; openspec/ коммитится в git; артефакты можно править в любой момент.
• Troubleshooting - по симптомам: «command not found» - PATH или отсутствие пакета; «команды не появляются» - шестишаговый чек-лист от «не туда ввели» до «инструмент skills-only»; validate ругается на структуру - читайте файл и строку; MODIFIED-требование обязано нести все выживающие сценарии; archive --yes - для неинтерактивных сред.
• Migration Guide: активные изменения, архив и specs сохраняются; удаляются только файлы, созданные OpenSpec; project.md переносится в context:/rules: конфига вручную; легаси-команды /openspec:* эквивалентны /opsx:*.
• Два корня большинства проблем новичка: терминал вместо чата и устаревший CLI без openspec update.

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

1. Почему «ввел слэш-команду и ничего не произошло» почти всегда сводится к одному из трех причин, и каких?
2. Какие шесть шагов чек-листа «команды не появляются» и почему они упорядочены от быстрой проверки к медленной?
3. Что означает сообщение MODIFIED ... omits scenario(s) и как его исправить?
4. Почему openspec archive в CI-среде падает с «User force closed the prompt» и какие два способа это обойти?
5. Почему project.md не удаляется автоматически при миграции, и по какому принципу его содержимое распределяется между context: и rules:?
6. Чем легаси /openspec:proposal отличается от пары /opsx:new + /opsx:ff и когда какую форму выбирать?
7. Как увидеть полный список легаси-файлов, которые миграция удалила бы, ничего фактически не удаляя?

Что дальше

Модуль 15 завершен: вы прошли от установки (15.1) и первого изменения (15.2) через концепции, команды, повседневные практики и командную работу к архитектуре OPSX и справочникам.

Дальше - практика: возьмите рабочий проект, выполните openspec init, проведите одно реальное изменение по полному циклу explore → propose → review → apply → sync → archive и сравните с capstone-потоком модуля 14. OpenSpec здесь - готовая реализация принципов, которые курс разбирал с урока 2.10 до capstone: маленькое изменение, письменное согласие до кода, проверяемые артефакты и история решений в git.

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/docs/faq.md
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/troubleshooting.md
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/migration-guide.md