Усунення несправностей

Конкретні рішення для конкретних проблем. Кожна стаття називає симптом, пояснює ймовірну причину в одному реченні та пропонує виправлення. Якщо ви не знайшли свою проблему тут, FAQ може допомогти, а Discord — точно.

Встановлення та налаштування

openspec: command not found

CLI не встановлено або ваша оболонка (shell) не може його знайти. Встановіть його глобально та перевірте:

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

Якщо він встановився, але все ще не знайдений, ймовірно, директорія глобальних бінарних файлів npm не міститься у вашому PATH. Виконайте npm bin -g, щоб побачити, де зберігаються глобальні бінарні файли, і переконайтеся, що цей шлях є у профілі вашої оболонки.

"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 не сконфігурував мій AI-інструмент

Init запитує, які інструменти потрібно налаштувати. Якщо ви пропустили свій інструмент або хочете додати ще один, просто запустіть його знову або скористайтеся неінтерактивною формою:

openspec init --tools claude,cursor

Повний список ID інструментів є у Supported Tools. Використовуйте --tools all для всього та --tools none, щоб пропустити налаштування інструментів.

Команди не відображаються

Якщо /opsx:propose (або еквівалент вашого інструменту) не з'являється або нічого не робить, пройдіть цю перелік. Вони відсортовані від найшвидше для перевірки до більш складних.

1. Ви можете бути не на тому місці. Слэш-команди (slash commands) вводяться у чат свого AI-асистента, а не в терміналі. Якщо ви ввели /opsx:propose у свою оболонку, це проблема. Дивіться Як працюють команди.

2. Згенеруйте файли знову. З кореня вашого проєкту:

   openspec update

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

3. Перезапустіть свого асистента. Більшість інструментів сканують навички та команди при запуску. Свіже вікно часто це робить.

4. Підтвердіть, що файли існують. Для Claude Code перевірте, чи містить .claude/skills/ папки openspec-*. Інші інструменти використовують власні директорії, усі перелічені у Supported Tools.

5. Переконайтеся, що ви ініціалізували цей проєкт. Навички пишуться для кожного проєкту. Якщо ви клонували репозиторій або змінили папку, запустіть openspec init (або openspec update) там.

6. Підтвердіть, що ваш інструмент підтримує файли команд. Деякі інструменти (Kimi CLI, Trae, ForgeCode, Mistral Vibe) не генерують файли команд opsx-*; вони використовують виклики на основі навичок. Форми відрізняються для кожного інструменту: дивіться Supported Tools та How Commands Work.

Робота зі змінами

"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

Поширені причини — це відсутній обов'язковий розділ (наприклад, специфікація без сценаріїв) або некоректно сформований заголовок дельта-змін. Виправте файл та повторно запустіть. CLI reference документує формат виводу.

AI створив неповні або неправильні артефакти

AI не мав достатнього контексту. Кілька важелів можуть допомогти:

• Додайте контекст проєкту у openspec/config.yaml, щоб ваш стек та конвенції були впроваджені в кожен запит. Дивіться Customization.
• Додайте правила (rules:) для кожного артефакта, щоб надати керівництво, яке стосується, скажімо, лише специфікацій.
• Надайте більш детальну описовувальну інформацію при пропозиції.
• Використовуйте розширений /opsx:continue, щоб створювати по одному артефакту і переглядати кожен з них, замість того, щоб /opsx:ff робив їх усі одразу.

Archive не завершується або попереджає про незавершені завдання

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>         # створити власну

Дивіться Customization.

Міграція зі старого робочого процесу

"Legacy files detected in non-interactive mode" (Виявлено файли попередньої версії в неінтерактивному режимі)

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

openspec init --force

Команди не з'явилися після міграції

Перезапустіть свою IDE. Навички виявляються при запуску. Якщо вони все ще не з'являються, виконайте openspec update та перевірте розташування файлів у Supported Tools.

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

Це навмисно. OpenSpec ніколи автоматично не видаляє project.md, оскільки він може містити контекст, який ви писали. Перенесіть корисні частини у розділ context: файлу config.yaml, а потім видаліть його самостійно. Migration Guide описує цей процес, включаючи запит, який ви можете передати своєму 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-інструмент, а також точну команду та вивід. Це значно прискорює допомогу.