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

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

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

openspec: command not found

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

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

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

"Requires Node.js 20.19.0 or higher" (Требуется Node.js 20.19.0 или выше)

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

node --version

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

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

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

openspec init --tools claude,cursor

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

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

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

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

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

   openspec update

   Это переписывает файлы навыков (skill) и команд для каждого настроенного вами инструмента.

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

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

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

6. Подтвердите, что ваш инструмент поддерживает файлы команд. Несколько инструментов (Kimi CLI, Trae, ForgeCode, Mistral Vibe) не генерируют файлы команд opsx-*; они используют вызовы на основе навыков. Формы различаются для каждого инструмента: см. Поддерживаемые инструменты и Как работают команды.

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

"Change not found" (Изменение не найдено)

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

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

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

"No artifacts ready" (Нет готовых артефактов)

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

openspec status --change <name>

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

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

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

openspec validate <name>           # проверить один элемент
openspec validate --all            # проверить все
openspec validate --all --strict   # более строгие проверки, полезно для CI

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

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

У ИИ не было достаточного контекста. Несколько способов помогут:

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

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

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

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

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

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

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

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

Ключ под rules: не соответствует ни одному из артефактов в вашей схеме. Для стандартной схемы spec-driven действительными ID являются 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>         # создать свою собственную

См. Кастомизация.

Миграция из устаревшего рабочего процесса

"Legacy files detected in non-interactive mode" (Обнаружены устаревшие файлы в неинтерактивном режиме)

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

openspec init --force

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

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

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

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

Все еще застряли?

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

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