FAQ

Швидкі відповіді на найпоширеніші запитання. Якщо ваше запитання фактично є питанням типу «щось зламано», краще зверніться до сторінки Відновлення роботи. Якщо вам потрібне визначення терміна, дивіться Глосарій.

Основи

Що таке OpenSpec, одним реченням?

Легкий шар, який допомагає вам і вашому AI-асистенту з кодуванням узгодити, що саме будувати, у письмовій формі, до того, як буде написано хоча б рядок коду.

Навіщо мені це потрібно?

Тому що AI-асистенти впевнені навіть тоді, коли помиляються. Коли вимоги існують лише в чаті, AI заповнює прогалини здогадками, і ви дізнаєтесь про це лише після того, як код уже існує. OpenSpec переносить узгодження на раннішу стадію, де помилки легко виправити. Повне обґрунтування — у розділі Основні концепції.

Чи маю я використовувати це для всього?

Ні. Використовуйте там, де узгодження важливе, тобто для більшості нетривіальних задач. Для виправлення однієї літери в опечатці церемонія, ймовірно, не варта того, і це цілком нормально.

Чи можна використовувати на великому наявному кодовому базі, чи тільки для нових проєктів?

Наявні кодові бази — це основний сценарій використання. OpenSpec спочатку розроблений для brownfield-проєктів: вам не потрібно документувати весь додаток заздалегідь. Ви пишете специфікації лише для того, що торкається кожної зміни, і ваші специфікації поступово наповнюються навколо реальної роботи. Є окремий посібник: Використання OpenSpec у наявному проєкті.

Чи прив'язаний він до одного AI-інструменту?

Ні. OpenSpec працює з понад 30 асистентами, включаючи Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex та інші. Повний список і деталі по інструментах — у розділі Підтримувані інструменти.

Виконання команд

Де мені вводити /opsx:propose?

У чаті вашого AI-асистента, а не в терміналі. Це найпоширеніша точка незрозумілості, тому для неї є окрема сторінка: Як працюють команди. Коротко: openspec ... виконується в терміналі, /opsx:... — у чаті.

Як мені «запустити інтерактивний режим»?

Окремого режиму для запуску немає. Ви відкриваєте AI-асистента як зазвичай і вводите slash-команду в його чат. Slash-команда — це спосіб «увійти» в OpenSpec. (Єдиний справді інтерактивний функціонал терміналу — це openspec view, панель для перегляду специфікацій і змін.) Повне пояснення — у розділі Як працюють команди.

Я ввів slash-команду, і нічого не сталося. Чому?

Найімовірніше, ви ввели її в терміналі замість чату AI, використали написання, яке ваш інструмент не розпізнає, або команди ще не встановлені. Якщо файлів немає — або ви ніколи не налаштували інструмент — виконайте openspec init; openspec update лише оновлює файли, які вже існують. Потім перезапустіть асистента і використовуйте форму, надруковану під розділом «Getting started» — дивіться Як викликати. Повний чек-лист — у розділі Відновлення роботи.

Чому синтаксис /opsx:propose в одному інструменті, а /opsx-propose в іншому?

Кожен AI-інструмент відображає користувацькі команди трохи по-різному, і OpenSpec записує їх так, як ваш інструмент завантажує файл, який він створив. Файл команди з назвою opsx-propose.md вводиться як /opsx-propose; файл у папці commands/opsx/ вводиться як /opsx:propose. Інструменти, які використовують skills замість команд, використовують назву skill — Codex потребує $openspec-propose, Kimi Code — /skill:openspec-propose. Рядок «Getting started» у openspec init уже друкує правильну форму для обраних вами інструментів; повна таблиця — у розділі Як викликати.

Яка різниця між skill і командою?

Обидва — це файли, які OpenSpec створює, щоб ваш асистент міг виконувати workflow. Skills (.../skills/openspec-*/SKILL.md) — це новіший крос-інструментальний стандарт; команди (.../commands/opsx-*) — це старіші slash-файли для кожного інструменту окремо. Вам не потрібно обирати. Ви просто вводите slash-команду, і OpenSpec встановлює те, що використовує ваш інструмент.

Workflow

З чого почати, якщо я не впевнений, що будувати?

З /opsx:explore. Це партнер для роздумів без ризику, який читає вашу кодову базу, розглядає варіанти та перетворює розмиту проблему на конкретний план, усе це до того, як існує будь-яка зміна чи код. Він є у профілі за замовчуванням, тому завжди доступний. Коли план стає чітким, він передає управління /opsx:propose. Це найкраща звичка, яку варто виробити, бо вона запобігає тому, щоб нетерплячий AI впевнено будував не те. Дивіться Спочатку дослідіть.

Який найпростіший можливий потік?

/opsx:explore (необов'язково)   потім   /opsx:propose <що ви хочете>   потім   /opsx:apply   потім   /opsx:archive

Explore — щоб продумати, propose — щоб скласти план, apply — щоб побудувати, archive — щоб зберегти. Пропустіть explore, якщо ви вже точно знаєте, що хочете.

Яка різниця між /opsx:propose і /opsx:new?

/opsx:propose — це командна одиниця за замовчуванням: вона створює зміну та складає всі планувальні артефакти одразу. /opsx:new — частина розширеного набору команд і лише створює порожню зміну, залишаючи вам можливість створювати артефакти по одному через /opsx:continue (або всі одразу через /opsx:ff). Використовуйте propose, якщо не хочете покрокового контролю. Дивіться Команди.

Що таке профілі core і розширені?

Профіль визначає, які slash-команди встановлюються. Core (за замовчуванням) надає вам propose, explore, apply, update, sync, archive. Розширений набір додає new, continue, ff, verify, bulk-archive та onboard для більш детального контролю. Перемикайте через openspec config profile, потім застосовуйте через openspec update.

Чи потрібно мені виконувати /opsx:sync?

Зазвичай ні. Sync об'єднує delta-специфікації зміни у ваші основні специфікації, і /opsx:archive запропонує зробити це за вас. Виконуйте sync вручну лише тоді, коли хочете об'єднати специфікації до архівування, наприклад для довготривалої зміни. Дivіться Команди.

Як мені редагувати пропозицію, специфікацію чи задачу після того, як я почав?

Просто редагуйте файл. Кожен артефакт — це звичайний Markdown у openspec/changes/<name>/, і немає заблокованих фаз чи спеціального режиму редагування. Змініть вручну або попросіть AI переглянути («оновіть дизайн, щоб використовувати чергу»), потім продовжуйте. AI завжди працює з поточним змістом файлів. Повний посібник: Редагування та ітерації зміни.

Чи можна повернутися і змінити план після часткової реалізації?

Так, будь-коли. Workflow є гнучким, тому перегляд і редагування — це не фази, з яких вас блокують. Редагуйте артефакт і продовжуйте. Якщо хочете структуровану перевірку, що код все ще відповідає плану, виконайте /opsx:verify. Дивіться Редагування та ітерації зміни.

Я відредагував код вручну. Як мені узгодити його зі специфікацією?

Узгодьте їх до архівування, оскільки архівування робить ваші специфікації джерелом істини. Якщо код тепер правильний, оновіть delta-специфікацію відповідно до того, що ви випустили; якщо специфікація правильна, продовжуйте будувати, доки код не узгодиться. /opsx:verify виявляє розбіжності. Дивіться Редагування та ітерації зміни.

Коли оновлювати наявну зміну, а коли почати нову?

Оновлюйте, коли це та сама робота, вдосконалена. Починайте заново, коли намір фундаментально змінився або масштаб вибухнув у різну роботу. Діаграма прийняття рішень і приклади — у розділі Workflow.

Що робити, якщо моя сесія вичерпує контекст, або вимоги змінюються під час реалізації?

Саме тут специфікації доводять свою цінність. Оскільки план зберігається у файлах (а не лише в історії чату), ви можете очистити контекст, розпочати нову сесію AI і продовжити з /opsx:apply; він читає артефакти та відновлює роботу з першого невиконаного завдання. Якщо вимоги змінились, редагуйте артефакти відповідно до нової реальності та продовжуйте. Чисте вікно контексту також дає кращі результати; очищуйте його перед реалізацією.

Чи слід комітити папку openspec/ у git?

Так. Ваші специфікації, активні зміни та архів — це частина історії вашого проєкту. Комітіть їх як будь-який інший код. Архів особливо стає стійким записом того, чому ваша система працює саме так.

Специфікації та зміни

Що входить до специфікації, а що до дизайну?

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

Що таке delta-специфікація?

Специфікація, яка описує лише те, що змінюється, використовуючи розділи ADDED, MODIFIED та REMOVED, замість повторення всієї специфікації. Саме так OpenSpec чистим чином обробляє зміни в наявних системах. Дивіться Концепції.

Куди потрапляють заархівовані зміни?

У openspec/changes/archive/YYYY-MM-DD-<name>/, зі збереженням усіх артефактів зміни. Зміна виїжджає зі списку активних. Зміна, яка явно декларує retire_capabilities: true, також може видалити основну специфікацію здатності, коли вона прибирає останню вимогу цієї здатності.

Конфігурація та кастомізація

Як повідомити AI про мій стек технологій?

Вкажіть це у openspec/config.yaml під context:. Цей текст ін'єктується у кожне планувальне запитання, тому AI завжди знає ваш стек і конвенції. Дивіться Кастомізація.

Чи можна генерувати специфікації мовою, іншою за англійську?

Так. Додайте інструкцію щодо мови у context: вашої конфігурації. Розділ Багатомовність містить фрагменти для копіювання для кількох мов.

Чи можна змінити сам workflow?

Так, за допомогою кастомних схем. Схема визначає, які артефакти існують і як вони залежать одне від одного. Відгалужте стандартну через openspec schema fork spec-driven my-workflow, потім відредагуйте. Дивіться Кастомізація.

Моделі, конфіденційність та оновлення

Яку AI-модель мені використовувати?

OpenSpec найкраще працює з моделями високого рівня міркувань. README рекомендує моделі на кшталт Codex 5.5 та Opus 4.7 як для планування, так і для реалізації. Також тримайте вікно контексту чистим: очищуйте його перед реалізацією для найкращих результатів.

Чи збирає OpenSpec дані?

Він збирає анонімну статистику використання: лише назви команд і версію. Без аргументів, шляхів, вмісту чи особистих даних, і вимикається автоматично в CI. Відмовтеся через export OPENSPEC_TELEMETRY=0 або export DO_NOT_TRACK=1.

Як оновити?

Два кроки. Оновіть пакет (npm install -g @fission-ai/openspec@latest), потім виконайте openspec update у кожному проєкті, щоб оновити згенеровані skills та команди.

Як видалити OpenSpec?

Команди видалення немає, бо це просто глобальний пакет плюс файли у вашому проєкті. Видаліть пакет (npm uninstall -g @fission-ai/openspec) та за бажанням видаліть каталог openspec/ і згенеровані файли інструментів. Покроково, включаючи те, що безпечно залишити, — у розділі Встановлення: Видалення.

Отримання допомоги

Де ставити запитання або повідомляти про вади?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• З терміналу: openspec feedback "your message" відкриває GitHub issue за вас.

Ця документація неправильна або незрозуміла. Що робити?

Повідомте нас або виправте. Документаційні PR-и вітаються та цінуються. Відкрийте issue або надішліть pull request.