Вирішення проблем

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

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

openspec: command not found

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

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

Якщо воно встановилося, але все одно не знаходиться, ймовірно, ваш глобальний каталог npm bin не додається до 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 не налаштував мій інструмент ШІ

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>

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

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:, який ви можете скопіювати. Якщо ви мали на увазі вибрати зі списку, передайте назву зміни явно: вибірнику також потрібна відповідь.

Якщо ви натомість виконали архівування з перенаправленням виводу в файл або захопленням інструментом і дійсно передали відповідь через pipe (printf 'y\n' | openspec archive …), старіші версії записували термінальні escape-коди в це захоплення під час малювання запиту — в деяких середовищах достатньо, щоб сильно роздути файл. Поточні версії читають запити на підтвердження як звичайний текст, коли 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. Щоб побачити ідентифікаторi для будь-якої схеми:

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. Це очищення обмежене дозволеними OpenSpec іменами файлів запитів Codex із legacy-списку, і неінтерактивний openspec init видаляє лише ті файли, для яких існують замісні навички .agents/skills/openspec-*. Неінтерактивний openspec update залишає все legacy-очищення недоторканим, якщо ви не передасте --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" відкриває для вас іssue.

Коли ви повідомляєте про проблему, включіть вашу версію OpenSpec (openspec --version), вашу версію Node (node --version), ваш інструмент ШІ та точну команду і вивід. Це значно прискорить допомогу.