Глосарій

Кожен термін OpenSpec в одному місці, визначений простою мовою. Прогляньте його один раз, і решта документації читатиметься швидше.

Терміни згруповані за темою, а потім алфавітно відсортовані всередині кожної групи.

Основні іменники (The core nouns)

Spec. Документ, що описує роботу певної частини вашої системи. Specs зберігаються у openspec/specs/, організовані за доменами та складаються з вимог (requirements) і сценаріїв (scenarios). Spec — це узгоджена відповідь на питання: «що робить це програмне забезпечення?». Дивіться Concepts.

Source of truth. Весь каталог openspec/specs/. Він містить поточну, узгоджену поведінку вашої системи. Зміни пропонують правки до нього; архівування застосовує їх.

Change. Одиниця роботи, упакована як папка у openspec/changes/<name>/. Change містить усюду інформацію про цю роботу: її пропозицію, дизайн, завдання та зміни специфікацій, які вона вносить. Один change — одна функція або виправлення.

Artifact. Документ всередині change. Стандартними артефактами є пропозиція (proposal), delta specs, дизайн та завдання (tasks). Вони створюються у порядку залежностей і взаємодіють між собою.

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

Domain. Логічна група для specs, наприклад, auth/, payments/ або ui/. Ви обираєте домени, які відповідають вашому розумінню своєї системи.

Всередині spec

Requirement. Єдинаксова поведінка, яку має мати система, зазвичай написана з ключовим словом RFC 2119: «Система SHALL завершує сесії через 30 хвилин». Requirements описують що, а не як.

Scenario. Конкретний, тестовий приклад вимоги в дії, типово у формі Given/When/Then. Scenarios роблять вимогу перевірюваною: з одного з них можна написати автоматизований тест.

RFC 2119 keywords. Слова MUST, SHALL, SHOULD та MAY, які несуть стандартизоване значення щодо того, наскільки суворо вимагається виконання. MUST та SHALL є абсолютними. SHOULD є рекомендованим із можливістю винятків. MAY є необов'язковим. Названа від документа інтернету, який їх визначив.

Артефакти (The artifacts)

Proposal (proposal.md). Чому і що стосується зміни: її намір, обсяг та високорівневий підхід. Це перший артефакт, який ви створюєте.

Design (design.md). Як: технічний підхід, архітектурні рішення та файли, які ви очікуєте змінити. Необов'язковий для простих змін.

Tasks (tasks.md). Чек-лист реалізації з чекбоксами. ШІ проходить його під час /opsx:apply і відмічає пункти по мірі виконання.

Життєвий цикл (The lifecycle)

Archive. Процес завершення зміни. Її delta specs об'єднуються з основними специфікаціями, а папка change переміщується до openspec/changes/archive/YYYY-MM-DD-<name>/. Після архівування ваші специфікації описують нову реальність. Дивіться Concepts.

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

Робочий процес і команди (Workflow and commands)

OPSX. Поточний стандартний робочий процес OpenSpec, побудований навколо плавних дій замість жорстких фаз. Його слэш-команди завжди починаються з /opsx:. Дивіться OPSX Workflow.

Slash command. Команда, яку ви вводите у чат-боті свого ШІ, наприклад, /opsx:propose. Slash commands керують робочим процесом. Це не термінальні команди. Дивіться How Commands Work.

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

CLI. Програма openspec, яку ви запускаєте у терміналі. Вона налаштовує проєкти, перераховує та валідує зміни, відкриває дашборд і архівує. Це термінална частина OpenSpec. Дивіться CLI.

Skill. Папка з інструкціями (.../skills/openspec-*/SKILL.md), яку ваш ШІ автоматично виявляє та виконує. Skills — це новітній крос-інструментальний стандарт для надання робочого процесу OpenSpec вашому асистенту.

Command file. Файл слэш-команди для певного інструменту (.../commands/opsx-*). Старіший механізм доставки, який все ще підтримується поряд зі skills. Ви рідко взаємодієте з ними напряму.

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

Delivery. Чи встановлює OpenSpec skills, command files чи обидва для ваших інструментів. Налаштовується глобально та застосовується командою openspec update.

Кастомізація (Customization)

Schema. Визначення того, які артефакти має робочий процес і як вони залежать один від одного. Вбудований стандарт — spec-driven (proposal → specs → design → tasks). Ви можете форкнути його або написати свій власний. Дивіться Customization.

Template. Файл Markdown всередині schema, який формує те, що генерує ШІ для певного артефакту. Редагування шаблону негайно змінює вивід ШІ без перезбірки.

Project config (openspec/config.yaml). Налаштування на рівні проєкту: стандартна схема, context:, який вставляється у кожен запит планування, та rules: для кожного артефакту. Найпростіший спосіб навчити OpenSpec про ваші стеки та конвенції. Дивіться Customization.

Context injection. Розміщення фону проєкту у полі context: файлу config.yaml, щоб він автоматично додавався до кожного артефакту, згенерованого ШІ. Це надійніше, ніж сподіватися, що ШІ прочитає окремий файл.

Dependency graph. Направлений граф, сформований за допомогою зв'язків requires: артефактів. Це DAG (directed acyclic graph: стрілки вказують лише вперед, ніколи не у циклі), і OpenSpec використовує його, щоб знати, що ви можете створити далі.

Enablers, not gates. Принцип полягає в тому, що залежності артефактів показують те, що стає можливим наступним кроком, а не те, що є вимогненим наступним кроком. Ви можете переглянути та відредагувати будь-який артефакт у будь-який час. Дивіться Core Concepts at a Glance.

Координація між репозиторіями (beta)

Ці терміни застосовуються лише, якщо ваше планування охоплює більше одного репо. Вони знаходяться у бета-версії. Більшість користувачів можуть їх ігнорувати. Дивіться Stores User Guide.

Store. Автономний репозиторій, чия єдина робота — планування. Він має таку саму структуру openspec/, яку ви вже знаєте (specs та changes), плюс невеликий ідентифікаційний файл. Ви реєструєте його на своїй машині один раз, за назвою, а потім будь-яка команда OpenSpec може працювати в ньому з будь-якого місця.

Reference. Декларація у файлі openspec/config.yaml репозиторію коду про store, на який цей репо посилається. References є лише для читання: репо зберігає свій власний корінь, а openspec instructions отримує індекс специфікацій з посиланняного store, кожен із яких має точну команду для їх отримання.

Working context. Те, що збирає openspec context для поточного репозиторію: його кореневий OpenSpec плюс кожен store, на який він посилається, з описом того, як його отримати. Відповідь на питання «з чим я працюю?».

Workset. Особистий набір папок на локальній машині, які ви відкриваєте разом (store поряд із репозиторіями коду, над якими ви працюєте). Створюється явно за допомогою openspec workset create; нічого з цих локальних шляхів не комітиться до спільного планувального репо.

Подивитися також (See also)

• Core Concepts at a Glance: п'ять ідей на одній сторінці
• Concepts: розгорнуте пояснення
• How Commands Work: слэш-команди проти CLI