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

Конкретні виправлення для конкретних проблем. Кожен запис містить назву симптома, пояснює ймовірну причину одним реченням і пропонує виправлення. Якщо ви не знайшли тут свою проблему, може допомогти 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 20.19.0+. Перевірте вашу версію та оновіть її за потреби:

node --version

Якщо ви використовуєте bun для встановлення OpenSpec, зауважте, що OpenSpec все одно запускається на Node, тому вам потрібно мати Node 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. Можливо, ви перебуваєте не в тому місці. Слеш-команди вводяться в чат вашого AI-асистента, а не в термінал. Якщо ви ввели /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                    # переглянути активні зміни
/opsx:apply add-dark-mode        # назвіть зміну в чаті

Також переконайтеся, що ви перебуваєте в правильному каталозі проекту.

"No artifacts ready"

Кожен артефакт або вже створено, або заблоковано в очікуванні залежності. Перевірте, що саме блокує роботу:

openspec status --change <name>

Потім спочатку створіть відсутню залежність. Пам'ятайте про порядок: пропозиція дає змогу створити специфікації та дизайн; специфікації та дизайн разом дають змогу створити завдання.

openspec validate reports warnings or errors

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

openspec validate <name>           # перевірити один елемент
openspec validate --all            # перевірити всі елементи
openspec validate --all --strict   # суворіші перевірки, зручні для CI

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

The AI created incomplete or wrong artifacts

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

• Додайте контекст проекту в 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                    # переглянути доступні схеми
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 видаляє лише ті файли, для яких існують замінюючі навички .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, а потім видаліть файл самі. Посібник з міграції описує цей процес крок за кроком, включно з підказкою, яку ви можете передати вашому 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-інструмент, а також точну команду та вивід, який ви отримали. Це значно прискорить процес вирішення проблеми.