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

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

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

openspec: command not found

Интерфейс командной строки (CLI) не установлен, или ваша оболочка не может его найти. Установите его глобально и проверьте работоспособность:

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

Если он установлен, но все равно не находится, скорее всего глобальная директория bin npm отсутствует в переменной PATH. Запустите npm bin -g, чтобы узнать путь к глобальным исполняемым файлам, и убедитесь, что этот путь указан в профиле вашей оболочки.

"Requires Node.js 20.19.0 or higher"

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

node --version

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

openspec init didn't configure my AI tool

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

openspec init --tools claude,cursor

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

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

Если /opsx:propose (или аналог для вашего инструмента) не появляется или не работает, последовательно проверяйте пункты из списка ниже. Они отсортированы по порядку от самого быстрого к проверке до более сложного.

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

2. Пересоздайте файлы. Выполните команду из корня вашего проекта:

   openspec update

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

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

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

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

6. Убедитесь, что ваш инструмент поддерживает файлы команд. Для Codex и нескольких других инструментов (CodeArts, Kimi CLI, ForgeCode, Mistral Vibe) не генерируются файлы команд с префиксом opsx-* — вместо этого они используют вызовы через навыки. Для Codex проверьте наличие папок .codex/skills/openspec-*. Синтаксис вызова отличается для разных инструментов: см. разделы Поддерживаемые инструменты и Как работают команды.

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

"Change not found"

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

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

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

"No artifacts ready"

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

openspec status --change <name>

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

openspec validate reports warnings or errors

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

openspec validate <name>           # validate one item
openspec validate --all            # validate everything
openspec validate --all --strict   # stricter checks, good for CI

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

The AI created incomplete or wrong artifacts

У ИИ не было достаточно контекста. Есть несколько способов это исправить:

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

Archive won't finish, or warns about incomplete tasks

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

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

My config.yaml isn't being applied

Три самые частые причины проблемы:

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

"Unknown artifact ID in rules: X"

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

openspec schemas --json

"Context too large"

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

"Schema not found"

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

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

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

Миграция со старого рабочего процесса

"Legacy files detected in non-interactive mode"

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

openspec init --force

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

Commands didn't appear after migrating

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

My old project.md wasn't migrated

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

Все еще не получается?

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

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