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

Конкретные решения для конкретных проблем. В каждой записи описан симптом, кратко указана вероятная причина и приведено решение. Если здесь нет вашей проблемы, возможно, поможет раздел FAQ; в Discord вам точно постараются помочь.

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

openspec: command not found (команда не найдена)

CLI не установлен или оболочка не может его найти. Установите его глобально и проверьте:

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

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

Если вы выполняли установку с помощью ИИ-ассистента, это ожидаемый момент передачи управления: инструкция просит ассистента показать вам изменение PATH, а не редактировать файлы запуска оболочки самостоятельно.

«Требуется Node.js версии 20.19.0 или новее»

OpenSpec работает на Node.js версии 20.19.0 или новее. Проверьте версию и при необходимости обновите её:

node --version

Если вы установили OpenSpec с помощью bun, помните, что OpenSpec по-прежнему выполняется на Node.js, поэтому Node.js версии 20.19.0 или новее должна быть доступна в PATH. См. раздел Установка.

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

Команда init спрашивает, какие инструменты нужно настроить. Если вы пропустили свой инструмент или хотите добавить ещё один, запустите команду повторно либо используйте неинтерактивный вариант:

openspec init --tools claude,cursor

Полный список ID инструментов приведён в разделе Поддерживаемые инструменты. Используйте --tools all, чтобы выбрать всё, или --tools none, чтобы пропустить настройку инструментов.

Команды не отображаются

Если /opsx:propose (или её аналог в вашем инструменте) не отображается или ничего не делает, проверьте следующие пункты — начиная с самых быстрых.

1. Возможно, вы вводите команду не там. Slash-команды вводятся в чате с ИИ-ассистентом, а не в терминале. Если вы ввели /opsx:propose в командной оболочке, проблема именно в этом. См. Как работают команды.

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

   openspec update

   Файлы навыков и команд для всех настроенных инструментов будут созданы заново.

   Файлы инструкций создаются установленным CLI, поэтому устаревший CLI может сообщить, что всё обновлено, хотя новые рабочие процессы ещё не записаны. Теперь openspec update проверяет это и предлагает обновление — согласитесь, если увидите такое предложение.

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

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

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

6. Убедитесь, что ваш инструмент поддерживает файлы команд. Для Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent и общей цели .agents файлы команд opsx-* не создаются: вместо этого используются вызовы навыков, поэтому автодополнение /opsx работать не будет. Введите $openspec-propose в Codex, /skill:openspec-propose в Kimi Code и /openspec-propose в остальных. Общая цель .agents не привязана к поставщику, поэтому /openspec-propose — распространённый, но не гарантированный вариант. Если ассистент его не распознаёт, найдите в его документации способ вызова навыков. Для Amazon Q файлы команд создаются, но загружаются в библиотеку запросов, а не в меню slash-команд: вводите @opsx-propose, а не /opsx. Форматы всех инструментов перечислены в разделе Вызов команд.

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

«Изменение не найдено»

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

openspec list                    # see active changes
/opsx:apply add-dark-mode        # name the change in chat

Также проверьте, что вы находитесь в каталоге нужного проекта.

«Нет готовых артефактов»

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

openspec status --change <name>

Сначала создайте недостающую зависимость. Помните порядок: предложение позволяет создать спецификации и проектное решение; спецификации и проектное решение вместе позволяют создать задачи.

openspec validate сообщает о предупреждениях или ошибках

Проверка ищет структурные проблемы в спецификациях и изменениях. Прочитайте сообщение: в нём указаны файл и проблема.

openspec validate <name>           # validate one item
openspec validate --all            # validate everything
openspec validate --all --strict   # stricter checks, good for CI
openspec validate --archived       # fail if archived changes have unchecked tasks

Обычно отсутствует обязательный раздел (например, в спецификации нет сценариев) или неверно оформлен заголовок дельты. Исправьте файл и запустите команду повторно. Формат вывода описан в справочнике CLI.

Отдельно стоит упомянуть сообщение:

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

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

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

ИИ не хватило контекста. Попробуйте следующее:

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

Архивация не завершается или сообщает о незавершённых задачах

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

«User force closed the prompt with 0 null»

Команда openspec archive была запущена там, где некому отвечать на вопросы: например, ИИ-агентом через инструмент, в задании CI или в оболочке с закрытым stdin. Архивация запрашивает подтверждение до трёх раз, а раньше неотвеченный запрос завершался этой ошибкой.

Чтобы заранее подтвердить все запросы, укажите --yes:

openspec archive <change-name> --yes

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

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

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

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

Обычно причина одна из трёх:

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

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

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

openspec schemas --json

«Контекст слишком большой»

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

«Схема не найдена»

Указанной схемы не существует. Выведите список доступных схем и проверьте написание:

openspec schemas                    # list available schemas
openspec schema which <name>        # see where a schema resolves from
openspec schema init <name>         # create a custom one

См. раздел Настройка.

Переход с устаревшего рабочего процесса

«В неинтерактивном режиме обнаружены устаревшие файлы»

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

openspec init --force

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

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

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

Мой старый project.md не был перенесён

Так задумано. OpenSpec никогда не удаляет project.md автоматически, поскольку там может храниться написанный вами контекст. Перенесите полезные сведения в поле context: файла config.yaml, а затем удалите старый файл самостоятельно. В Руководстве по миграции описаны все шаги и приведена инструкция, которую можно поручить ИИ для извлечения нужной информации.

Проблема осталась?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Из терминала: команда openspec feedback "что пошло не так" создаст задачу от вашего имени.

При сообщении о проблеме укажите версию OpenSpec (openspec --version), версию Node.js (node --version), используемый ИИ-инструмент, а также точную команду и её вывод. Это ускорит получение помощи.