OpenSpec

Глосарій ​

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

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

Основні іменники ​

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

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

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

Artifact. Документ всередині зміни. Стандартні артефакти — це пропозиція, дельта-специфікації, дизайн і завдання. Вони створюються в порядку залежностей і впливають один на одного.

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

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

Всередині специфікації ​

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

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

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

Артефакти ​

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

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

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

Життєвий цикл ​

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

Sync. Злиття дельта-специфікацій зміни з основними специфікаціями без архівування зміни. Зазвичай автоматичне (архівування пропонує зробити це), але також доступне окремо як /opsx:sync для довготривалих змін. Див. Команди.

Робочий процес і команди ​

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

Slash command. Команда, яку ви вводите в чат вашого ШІ-асистента, наприклад /opsx:propose. Команди з косими рисками керують робочим процесом. Вони не є командами термінала. Див. Як працюють команди.

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

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

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

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

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

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

Кастомізація ​

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

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

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

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

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

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

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

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

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

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

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

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

Див. також ​