Настройка

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 и отдельная команда sync используют artifactPaths.specs.existingOutputPaths из вывода openspec status --json как единственный источник дельта-спецификаций. Если в схеме нет артефакта specs или конкретный список выходных файлов изменения пуст, синхронизировать нечего; другие артефакты не используются для определения дельта-спецификаций.

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

Эта конфигурация не меняет этапы выполнения архивации, запросы пользователю, операции файловой системы, владение семантическим слиянием, непосредственную команду 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: Пользовательский рабочий процесс команды

artifacts:
  - id: proposal
    generates: proposal.md
    description: Первоначальный документ с предложением
    template: proposal.md
    instruction: |
      Создай предложение, объясняющее, ЗАЧЕМ нужно это изменение.
      Сосредоточься на проблеме, а не на решении.
    requires: []

  - id: design
    generates: design.md
    description: Техническое проектное решение
    template: design.md
    instruction: |
      Создай документ проектного решения с объяснением того, КАК выполнить работу.
    requires:
      - proposal    # Сначала нужно создать предложение

  - id: tasks
    generates: tasks.md
    description: Контрольный список реализации
    template: tasks.md
    requires:
      - design

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

Основные поля:

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

Перечисляйте артефакты в порядке их создания. Поле requires определяет, что можно создать; порядок элементов в списке artifacts: определяет, какой из нескольких готовых артефактов будет создан первым.

Шаблоны

Шаблоны — это Markdown-файлы, направляющие работу ИИ. Они добавляются в запрос при создании соответствующего артефакта.

templates/proposal.md

## Why

<!-- Объясни причину изменения. Какую проблему оно решает? -->

## Что меняется

<!-- Опиши, что изменится. Укажи новые возможности или модификации. -->

## Impact

<!-- Затронутый код, API, зависимости и системы -->

Шаблоны могут включать:

• заголовки разделов, которые должен заполнить ИИ;
• HTML-комментарии с инструкциями для ИИ;
• примеры формата ожидаемой структуры.

Проверка схемы

Перед использованием пользовательской схемы проверьте её:

openspec schema validate my-workflow

Проверяется следующее:

• синтаксис schema.yaml корректен;
• все указанные шаблоны существуют;
• циклических зависимостей нет;
• ID артефактов допустимы.

Использование пользовательской схемы

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

# Указать в команде
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: Быстрая итерация с минимальными накладными расходами

artifacts:
  - id: proposal
    generates: proposal.md
    description: Краткое предложение
    template: proposal.md
    instruction: |
      Создай краткое предложение для этого изменения.
      Сосредоточься на том, что меняется и зачем; подробные спецификации не нужны.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Контрольный список реализации
    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: Контрольный список проверки перед реализацией
    template: review.md
    instruction: |
      Создай контрольный список проверки на основе проектного решения.
      Учти безопасность, производительность и тестирование.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Теперь перед задачами нужно выполнить проверку

---

Схемы сообщества

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

Схемы сообщества не входят в OpenSpec core: они находятся в отдельных репозиториях и выпускаются по собственному расписанию. Чтобы использовать такую схему, скопируйте её комплект файлов в 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	Рабочий процесс с приоритетом управления продуктом. До реализации запускает конвейер планирования nanopm (аудит → стратегия → дорожная карта → PRD). Связывает продуктовое планирование с инженерным процессом OpenSpec на основе спецификаций. При наличии артефакты читаются из .nanopm/: предложение опирается на аудит, проектное решение — на стратегию, а задачи — на декомпозицию PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Инструкции для сквозного тестирования на уровне возможностей. Для каждой возможности создаются неизменяемая спецификация, неизменяемый шаблон задач и отдельная запись о каждом запуске с отметкой времени. Проверки ограничены наблюдаемым поведением (статус 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 сопоставляет каждый сценарий спецификации с именованным тестом и служит журналом red/green, который проверяет verify.

Хотите внести вклад в схему сообщества? Создайте issue со ссылкой на репозиторий или отправьте PR, добавив строку в эту таблицу.

---

См. также

• Справочник CLI: команды схем — полная документация по командам