Налаштування

OpenSpec пропонує три рівні налаштування:

Рівень	Що дає змогу	Найкраще підходить для
Конфігурація проєкту	Встановлює значення за замовчуванням, впроваджує контекст/правила	Більшості команд
Користувацькі схеми	Визначає власні артефакти робочого процесу	Команд із унікальними процесами
Глобальні перевизначення	Ділиться схемами між усіма проєктами	Просунутих користувачів

---

Конфігурація проєкту

Файл openspec/config.yaml — це найпростіший спосіб налаштувати OpenSpec для вашої команди. Він дозволяє:

• Встановити схему за замовчуванням – Пропустити --schema у кожній команді
• Додати контекст проєкту – ШІ бачить ваш технологічний стек, узгодження тощо.
• Додати правила для кожного артефакту – Користувацькі правила для конкретних артефактів
• Додати вказівки для кожної операції – Рекомендаційні налаштування для роботи з apply та archive
• Запам’ятати вибір інтеграцій – наприклад, згоду на використання хмарного агента для написання коду GitHub Copilot

Швидке налаштування

openspec init

Це покроково проведе вас через створення конфігурації в інтерактивному режимі. Або створіть вручну:

# openspec/config.yaml
schema: spec-driven

context: |
  Технологічний стек: TypeScript, React, Node.js, PostgreSQL
  Стиль API: RESTful, задокументовано в docs/api.md
  Тестування: Jest + React Testing Library
  Ми цінуємо зворотну сумісність для всіх публічних API

rules:
  proposal:
    - Додати план відкату
    - Визначити залучені команди
  specs:
    - Використовувати формат Given/When/Then
    - Посилатися на існуючі шаблони перед створенням нових

operations:
  apply:
    guidance:
      - Запустити вибіркові тести перед повним набором
  archive:
    guidance:
      - Зробити підсумок завершення стислим

# Встановлено командою `openspec init`, коли ви вибираєте (або відхиляєте) хмарний агент
# для написання коду GitHub Copilot; керує тим, чи генерують його файли команди `init`/`update`.
githubCopilot:
  cloudAgent: false

Як це працює

Схема за замовчуванням:

# Без конфігурації
openspec new change my-feature --schema spec-driven

# З конфігурацією - схема автоматична
openspec new change my-feature

Додавання контексту та правил:

Під час генерування будь-якого артефакту ваш контекст і правила додаються до підказки ШІ-моделі:

<context>
Технологічний стек: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Додати план відкату
- Визначити залучені команди
</rules>

<template>
[Вбудований шаблон схеми]
</template>

• Контекст з’являється в УСІХ артефактах
• Правила з’являються ТІЛЬКИ для відповідного артефакту

Вказівки для операцій:

operations.apply.guidance та operations.archive.guidance — це необов’язкові масиви рекомендованих інструкцій щодо того, як агент повинен виконувати ці операції. Вони відокремлені від rules: вказівки для операцій не обмежують вміст артефактів, а правила артефактів ніколи не переосмислюються як вказівки для операцій.

Команди apply та archive отримують ці вхідні дані під час виконання:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Обидва виклики повертають поточний context проєкту та відповідний operationGuidance як окремі необов’язкові поля. Кожен виклик зчитує новий знімок з визначеного кореня. Якщо вибрано --store <id>, зміна, контекст і вказівки будуть взяті з цього сховища, а не з поточного репозиторію. Команда інструкції для архівування є лише для читання: вона не перевіряє та не об’єднує дельта-специфікації, не записує основні специфікації, не переміщує зміни та не запускає статичний процес архівування.

Контекст проєкту є обов’язковим вхідним параметром на рівні підказки. Згенеровані робочі процеси зчитують його та застосовують відповідні факти, узгодження та обмеження проєкту. Вказівки для операцій є необов’язковими додатковими порадами: робочі процеси розглядають кожен запис і дотримуються тих записів, які застосовні та сумісні з вбудованим робочим процесом.

Обидва поля залишаються окремими від стану, контрольованого CLI, розв’язаних шляхів, вбудованих кроків, явних виборів користувача та правил артефактів. Робочий процес повідомляє про конфлікти контексту, зберігаючи контрольне значення. Він не дотримується непридатних чи суперечливих вказівок і пояснює чому. Жодне з полів не є обов’язковою перевіркою, і робочі процеси не копіюють їхній текст у файли реалізації, специфікації, артефакти змін або підсумки, якщо користувач окремо не запросить цей вміст.

Безпека вхідних даних при архівуванні та синхронізації специфікацій:

Команди archive, bulk archive та автономна синхронізація використовують artifactPaths.specs.existingOutputPaths з openspec status --json як єдине джерело дельта-специфікацій. Схема без артефакту specs або зміна, чий конкретний список виводу порожній, не має що синхронізувати; інші артефакти не використовуються для визначення дельта-специфікацій.

Перед тим як семантичне об’єднання запише основну специфікацію, робочий процес використовує поточний вивід команди openspec instructions specs --change <name> --json. Повернені правила specs обмежують лише основні специфікації, створені цим об’єднанням. Одиночне архівування передає цей знімок у внутрішню синхронізацію, автономна синхронізація отримує його безпосередньо, а пакетне архівування отримує всі необхідні знімки перед першим записом специфікації. Ненульова або некоректна JSON-відповідь на команду інструкцій для архівування/специфікацій вважається помилкою пошуку, а не порожнім введенням: робочий процес зупиняється перед записом відповідної специфікації або переміщенням зміни (для пакетного архівування — перед будь-яким пакетним записом або переміщенням).

Ця конфігурація не змінює фази виконання архівування, підказки користувача, операції з файловою системою, власність семантичного об’єднання, безпосередню команду openspec archive або структуру та вивід rules артефактів.

Порядок визначення схеми

Коли OpenSpec потрібна схема, вона перевіряється в такому порядку:

1. Прапорець CLI: --schema <name>
2. Метадані зміни (.openspec.yaml у папці зміни)
3. Конфігурація проєкту (openspec/config.yaml)
4. Типово (spec-driven)

---

Користувацькі схеми

Коли конфігурації проєкту недостатньо, створіть власну схему з повністю кастомним робочим процесом. Користувацькі схеми зберігаються у каталозі openspec/schemas/ вашого проєкту та контролюються версіями разом із вашим кодом.

your-project/
├── openspec/
│   ├── config.yaml        # Конфігурація проєкту
│   ├── schemas/           # Користувацькі схеми зберігаються тут
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Ваші зміни
└── src/

Розгалуження наявної схеми

Найшвидший спосіб кастомізації — розгалужити вбудовану схему:

openspec schema fork spec-driven my-workflow

Це копіює всю схему spec-driven до openspec/schemas/my-workflow/, де ви можете вільно її редагувати.

Що ви отримаєте:

openspec/schemas/my-workflow/
├── schema.yaml           # Визначення робочого процесу
└── templates/
    ├── proposal.md       # Шаблон для артефакту пропозиції
    ├── spec.md           # Шаблон для специфікацій
    ├── design.md         # Шаблон для проєктування
    └── tasks.md          # Шаблон для завдань

Тепер редагуйте schema.yaml, щоб змінити робочий процес, або редагуйте шаблони, щоб змінити те, що генерує ШІ.

Створення схеми з нуля

Для повністю нового робочого процесу:

# Інтерактивний режим
openspec schema init research-first

# Неінтерактивний режим
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Структура схеми

Схема визначає артефакти вашого робочого процесу та їхні залежності:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Ключові поля:

Поле	Призначення
id	Унікальний ідентифікатор, використовується в командах і правилах
generates	Назва файлу виводу (підтримує глоби, наприклад specs/**/*.md)
template	Файл шаблону у каталозі templates/
instruction	Інструкції для ШІ щодо створення цього артефакту
requires	Залежності — які артефакти мають існувати першими

Перелічте артефакти у порядку, в якому ви хочете їх записувати. requires визначає, що є можливим; порядок списку artifacts: визначає, що йде першим, коли кілька артефактів готові одночасно.

Шаблони

Шаблони — це файли Markdown, які спрямовують ШІ. Вони вставляються у запит під час створення відповідного артефакту.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Шаблони можуть містити:

• Заголовки розділів, які ШІ має заповнити
• HTML-коментарі з настановами для ШІ
• Приклади формату, що демонструють очікувану структуру

Валідація вашої схеми

Перед використанням користувацької схеми перевірте її:

openspec schema validate my-workflow

Це перевіряє:

• Синтаксис schema.yaml правильний
• Усі посилані шаблони існують
• Немає циклічних залежностей
• Ідентифікатори артефактів валідні

Використання вашої користувацької схеми

Після створення використовуйте свою схему за допомогою:

# Вкажіть у команді
openspec new change feature --schema my-workflow

# Або встановіть як типову у config.yaml
schema: my-workflow

Відлагодження визначення схеми

Не впевнені, яку схему використано? Перевірте за допомогою:

# Дивіться, звідки визначається конкретна схема
openspec schema which my-workflow

# Перелічте всі доступні схеми
openspec schema which --all

Вивід показує, чи схема походить із вашого проєкту, каталогу користувача чи пакета:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Примітка: OpenSpec також підтримує схеми рівня користувача у ~/.local/share/openspec/schemas/ для спільного використання між проєктами, але схеми рівня проєкту у openspec/schemas/ рекомендовані, оскільки вони контролюються версіями разом із вашим кодом.

---

Приклади

Робочий процес швидких ітерацій

Мінімальний робочий процес для швидких ітерацій:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Додавання артефакту перегляду

Розгалужте типову схему та додайте крок перегляду:

openspec schema fork spec-driven with-review

Потім відредагуйте schema.yaml, додавши:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

Схеми спільноти

OpenSpec також підтримує схеми, підтримувані спільнотою, які розповсюджуються через незалежні репозиторії. Вони надають робочі процеси з власними поглядами, що інтегрують OpenSpec з іншими інструментами чи системами, подібно до того, як каталог розширень спільноти github/spec-kit працює для spec-kit.

Схеми спільноти не вбудовані у ядро OpenSpec — вони зберігаються у власних репозиторіях зі своїм графіком випусків. Щоб скористатися ними, скопіюйте пакет схеми до каталогу openspec/schemas/<schema-name>/ вашого проєкту (у README кожного репозиторію є інструкції з встановлення).

Схема	Підтримувач	Репозиторій	Опис
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Захоплює намір змін, спостережувану поведінку, технічне проєктування та стійкі архітектурні рішення до реалізації. Додає локальний для змін маніфест перегляду ADR та записує відповідні довгоживучі рішення як незмінні, замінювані ADR.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Інтегрує управління артефактами OpenSpec із навичками виконання obra/superpowers (бурхливе обговорення, написання планів, TDD через субагентів, перегляд коду, завершення). Додає артефакт retrospective з пріоритетом доказів, що заповнює прогалину, яку Superpowers не покриває нативно.
nanopm	@nmrtn	nmrtn/nanopm	Робочий процес із пріоритетом PM. Запускає конвеєр планування nanopm (аудит → стратегія → дорожня карта → PRD) до реалізації. Зв'язує продуктове планування з робочим процесом інженерії на основі специфікацій OpenSpec. Артефакти читаються з .nanopm/, якщо він наявний — пропозиція бере аудит, проєктування бере стратегію, а завдання беруть розклад PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Кінцеві до кінця (end-to-end) сценарії тестування на рівні функціональності. Кожна функціональність отримує незмінну специфікацію, незмінний шаблон завдань та один запис виконання з позначкою часу на кожне запуску. Асерції — лише спостережувана поведінка (HTTP-статус, тіло відповіді, збережений стан — ніколи не підланцюжки логів); кожне виконання записує початок/кінець UTC, тривалість та оцінку споживання токенів LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Робочий процес на основі специфікацій із дисципліною TDD та кроком протилежного перегляду. Потік: proposal → specs → design → review → test-plan → tasks → apply → verify. review пишеться переглядачем із свіжим контекстом і лише для читання (другою моделлю, коли вона доступна) та видає рядок VERDICT:, який наказує агенту блокувати test-plan, tasks та apply; OpenSpec перевіряє лише наявність артефактів, тому примусово виконуйте блокування власним CI або хуком. test-plan відповідає кожному сценарію специфікації іменований тест і слугує червоно-зеленим реєстром, який аудитує verify.

Хочете додати схему спільноти? Відкрийте issue з посиланням на ваш репозиторій або надішліть PR, додавши рядок до цієї таблиці.

---

Дивіться також

• Довідник CLI: Команди схеми - Повна документація команд