FAQ

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

Основи (The basics)

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

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

Чому мені це може бути потрібно?

Тому що асистенти на базі AI впевнені навіть тоді, коли вони помиляються. Коли вимоги існують лише у чаті, AI заповнює прогалини здогадками, і ви дізнаєтеся про це лише після того, як код існуватиме. OpenSpec переносить узгодження на більш ранній етап, де помилки дешевіші для виправлення. Для повного розуміння дивіться Core Concepts at a Glance.

Чи мушу я використовувати його для всього?

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

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

Існуючі кодові бази — це головна справа. OpenSpec створений для роботи з існуючими системами (brownfield-first): ви не повинні документувати весь свій додаток одразу. Ви пишете специфікації лише для тих змін, які торкаються кожного разу, а ваші специфікації формуються з часом навколо тієї роботи, яку ви насправді виконуєте. Є спеціальний посібник: Using OpenSpec in an Existing Project.

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

Ні. OpenSpec працює з 25+ асистентами, включаючи Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex та інші. Повний список і деталі для кожного інструмента є у Supported Tools.

Виконання команд (Running commands)

Де я вводжу /opsx:propose?

У чаті вашого асистента AI, а не в терміналі. Це найпоширеніша точка плутанини, тому про це є окрема сторінка: How Commands Work. Коротко: openspec ... працює у терміналі, /opsx:... — у чаті.

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

Окремого режиму для запуску немає. Ви відкриваєте свого асистента AI як зазвичай і вводите слеш-команду у його чат. Слеш-команда — це те, що дозволяє вам «увійти» в OpenSpec. (Єдина справді інтерактивна функція терміналу — це openspec view, панель для перегляду специфікацій та змін.) Повний опис у How Commands Work.

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

Найімовірніше, ви ввели її в терміналі замість чату свого AI, або команди ще не встановлені. Запустіть openspec update у своєму проєкті, перезапустіть асистента, а потім спробуйте ввести /opsx у чаті та подивіться на автозаповнення. Troubleshooting містить повний чекліст.

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

Кожен інструмент AI відображає власні кастомні команди трохи по-різному. Намір однаковий; змінюється лише пунктуація. Введіть слеш у чаті, і автозаповнення покаже вам форму, яку очікує ваш інструмент. Таблиця за кожним інструментом є в How Commands Work.

Яка різниця між навичкою (skill) та командою (command)?

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

Робочий процес (The workflow)

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

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

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

/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, якщо не хочете мати покроковий контроль. Дивіться Commands.

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

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

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

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

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

Просто відредагуйте файл. Кожен артефакт — це звичайний Markdown у openspec/changes/<name>/, і немає жодного замкненого етапу чи спеціального режиму редагування. Змініть його вручну або попросіть свій AI переглянути ("оновіть дизайн, щоб використати чергу"), а потім продовжуйте. AI завжди працює на основі поточного вмісту файлу. Повний посібник: Editing & Iterating on a Change.

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

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

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

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

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

Оновлюйте, якщо це та сама робота, але вона була вдосконалена. Починайте з нуля, якщо намір кардинально змінився або обсяг розширився до іншої роботи. Є блок-схема рішень та приклади у Workflows.

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

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

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

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

Специфікації та зміни (Specs and changes)

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

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

Що таке delta spec?

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

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

У openspec/changes/archive/YYYY-MM-DD-<name>/, з усіма збереженими артефактами. Нічого не видаляється; зміна просто виходить зі списку активних.

Конфігурація та кастомізація (Configuration and customization)

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

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

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

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

Чи можу я змінити сам робочий процес?

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

Моделі, конфіденційність та оновлення (Models, privacy, and upgrades)

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

Як мені видалити OpenSpec?

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

Отримання допомоги (Getting help)

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

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

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

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