Настройка

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

Уровень	Что делает	Лучше всего подходит для
Конфигурация проекта	Установка значений по умолчанию, внедрение контекста/правил	Большинства команд
Пользовательские схемы	Определение собственных артефактов рабочего процесса	Команд с уникальными процессами
Глобальные переопределения	Общий доступ к схемам во всех проектах	Продвинутых пользователей

---

Конфигурация проекта

Файл openspec/config.yaml — самый простой способ настроить OpenSpec для вашей команды. Он позволяет:

• Установить схему по умолчанию — пропускайте --schema в каждой команде
• Внедрить контекст проекта — ИИ будет видеть ваш технологический стек, соглашения и т.д.
• Добавить правила для артефактов — пользовательские правила для определенных артефактов

Быстрая настройка

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
    - Ссылаться на существующие паттерны перед изобретением новых

Как это работает

Схема по умолчанию:

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

# С конфигурацией - схема выбирается автоматически
openspec new change my-feature

Внедрение контекста и правил:

При генерации любого артефакта ваш контекст и правила внедряются в промпт ИИ:

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

<rules>
- Включить план отката
- Указать затронутые команды
</rules>

<template>
[Встроенный шаблон схемы]
</template>

• Контекст появляется во ВСЕХ артефактах
• Правила появляются ТОЛЬКО для соответствующего артефакта

Порядок разрешения схемы

Когда OpenSpec нужна схема, она проверяется в следующем порядке:

1. Флаг CLI: --schema <имя>
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       # Шаблон для артефакта proposal
    ├── spec.md           # Шаблон для спецификаций
    ├── design.md         # Шаблон для дизайна
    └── tasks.md          # Шаблон для задач

Теперь отредактируйте schema.yaml для изменения рабочего процесса или отредактируйте шаблоны для изменения того, что генерирует ИИ.

Создание схемы с нуля

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

# Интерактивно
openspec schema init research-first

# Неинтерактивно
openspec schema init rapid \
  --description "Рабочий процесс быстрой итерации" \
  --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    # Невозможно создать дизайн, пока не существует proposal

  - id: tasks
    generates: tasks.md
    description: Чеклист реализации
    template: tasks.md
    requires:
      - design

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

Ключевые поля:

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

Шаблоны

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

<!-- templates/proposal.md -->
## Почему

<!-- Объясните мотивацию для этих изменений. Какую проблему они решают? -->

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

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

## Влияние

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

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

• Заголовки разделов, которые ИИ должен заполнить
• 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: Быстрая итерация с минимальными накладными расходами

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
    # ... существующая конфигурация задач ...
    requires:
      - specs
      - design
      - review    # Теперь задачи также требуют проверки

---

Смотрите также

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