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

Конкретные решения для конкретных проблем. Каждая запись содержит описание симптома, объяснение вероятной причины в одном предложении и способ устранения. Если вы не нашли свою проблему здесь, возможно, поможет часто задаваемые вопросы (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, вместо того чтобы самостоятельно редактировать файлы автозагрузки оболочки.

"Requires Node.js 20.19.0 or higher"

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

node --version

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

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

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

openspec init --tools claude,cursor

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

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

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

1. Возможно, вы находитесь не там. Слэш-команды вводятся в чате вашего ИИ-ассистента, а не в терминале. Если вы ввели /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 получает файлы команд, но загружает их в библиотеку подсказок, а не в меню слэш-команд — вводите там @opsx-propose, а не /opsx. Форма для каждого инструмента указана в разделе Как вызвать.

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

"Change not found"

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

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

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

"No artifacts ready"

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

openspec status --change <name>

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

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

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

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

Частые причины — отсутствие обязательного раздела (например, спецификация без сценариев) или неверно оформленный заголовок дельты. Исправьте файл и запустите проверку снова. Формат вывода документируется в справке 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"

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

openspec schemas --json

"Context too large"

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

"Schema not found"

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

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

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

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

"Legacy files detected in non-interactive mode"

Вы находитесь в 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 "what went wrong" создаст issue за вас.

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