Кастомизация

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

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

---

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

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

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

Быстрый старт

openspec init

Эта команда пошагово проведет вас через интерактивное создание конфигурации. Или создайте файл вручную:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

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

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

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

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

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

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

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in 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>, изменения, контекст и рекомендации берутся из этого хранилища, а не из текущего репозитория. Команда инструкции archive является только для чтения: она не анализирует и не объединяет delta-спецификации, не записывает основные спецификации, не перемещает изменения и не запускает статический рабочий процесс archive.

Контекст проекта является обязательным входным параметром на уровне запроса. Сгенерированные рабочие процессы читают его и применяют соответствующие факты, соглашения и ограничения проекта. Рекомендации операций являются дополнительными советами: рабочие процессы учитывают каждую запись и следуют тем, которые применимы и совместимы со встроенным рабочим процессом.

Оба поля остаются отдельными от управляемого CLI состояния, разрешенных путей, встроенных шагов, явного выбора пользователя и правил артефактов. Рабочий процесс сообщает о конфликтах контекста, сохраняя контролирующее значение. Он не следует неприменимым или конфликтующим рекомендациям и объясняет причину. Ни одно из полей не является проверяемым ограничением, и рабочие процессы не копируют их текст в файлы реализации, спецификации, артефакты изменений или сводки, если пользователь отдельно не запросит этот контент.

Безопасность ввода для archive и spec-sync:

Archive, массовый archive и автономный sync используют artifactPaths.specs.existingOutputPaths из openspec status --json в качестве единственного источника delta-спецификаций. Схема без артефакта specs или изменение, у которого список конкретных выходов пуст, нечего синхронизировать; другие артефакты не используются для вывода delta-спецификаций.

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

Эта конфигурация не изменяет фазы выполнения archive, пользовательские запросы, операции с файловой системой, владение семантическим слиянием, прямую команду openspec archive или структуру и вывод правил артефактов.

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

Когда 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    # Нельзя создать дизайн, пока не существует предложение

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

---

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

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 (brainstorming, writing-plans, TDD via subagents, code review, finishing). Добавляет артефакт retrospective, ориентированный на доказательства, заполняя пробел, который Superpowers не покрывает нативно.
nanopm	@nmrtn	nmrtn/nanopm	Рабочий процесс, ориентированный на менеджмент продуктов. Запускает конвейер планирования nanopm (audit → strategy → roadmap → 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 лишь проверяет наличие артефактов, поэтому блокировку следует enforcing с помощью собственного CI или хука. test-plan сопоставляет каждый сценарий спецификации с именованным тестом и служит красной/зеленой книгой учета, которую проверяет verify.

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

---

См. также

• CLI Reference: Schema Commands - Полная документация по командам