Схемы

Схема определяет, что создаётся в рамках предложения об изменении: какие артефакты, в каком порядке и из каких шаблонов. Например, spec-driven, встроенная схема по умолчанию, создаёт эти четыре артефакта примерно в таком порядке, где каждый последующий опирается на предыдущие:

proposal → specs → design → tasks

Создайте форк схемы, если вам нужны другие документы — меньшее их количество, другие названия или иная структура.

Где хранятся схемыCopy Anchor Link

OpenSpec ищет схему в трёх местах по порядку и использует первую найденную:

1. Ваш проект: openspec/schemas/, закоммиченный в репозиторий, чтобы схема была доступна всей команде.
2. Ваша машина: ~/.local/share/openspec/schemas на macOS и Linux (или в $XDG_DATA_HOME, если переменная задана), либо %LOCALAPPDATA%\openspec\schemas на Windows. Схемы здесь доступны в каждом проекте, над которым вы работаете.
3. Пакет: встроенные схемы, такие как spec-driven, поставляются внутри самого openspec.

Одно и то же имя может существовать в нескольких местах, при этом приоритет имеет более специфичное расположение. Команда openspec schema which показывает, какая копия используется:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Что входит в схемуCopy Anchor Link

Схема определяется папкой с обычными файлами: одним файлом schema.yaml, в котором объявляются артефакты, и шаблоном для каждого из них. Вот встроенная схема spec-driven:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: объявляет каждый артефакт, генерируемый им файл, исходный шаблон, предварительные зависимости и инструкцию, которую получает агент при его создании. Описание каждого поля приведено в schema.yaml.
• templates/: по одному каркасу в формате Markdown на каждый артефакт, который заполняет агент.

Вот сокращённая запись для артефакта задач в schema.yaml:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

Встроенные схемы поставляются внутри пакета openspec, поэтому вы никогда не редактируете их напрямую. Чтобы получить собственную копию, создайте форк.

Создание собственной пользовательской схемыCopy Anchor Link

Получить собственную схему можно двумя способами:

1. Сделать форк существующей схемы и отредактировать свою копию. Начните с этого варианта, если существующая схема близка к тому, что вам нужно, так как в ней уже всё работает.
2. Начать с нуля, если ни одна схема не подходит, сгенерировав каркас пустой схемы с помощью openspec schema init.

Форк существующей схемыCopy Anchor Link

1. Сделайте форк схемы, которую хотите взять за основу, запустив команду из корня проекта:

   Copy Text

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Передайте второй аргумент, чтобы выбрать имя (openspec schema fork spec-driven team-flow). Имена задаются в формате kebab-case.

2. Отредактируйте копию: schema.yaml и шаблоны. В разделе Редактирование вашего форка описано, что именно нужно менять.

3. Выполните валидацию:

   Copy Text

   openspec schema validate spec-driven-custom

   Эта команда позволяет выявить ошибки в схеме (отсутствующие шаблоны, некорректный YAML, циклические зависимости) до того, как вы окажетесь в середине работы над изменением.

4. Укажите схему для вашего проекта в файле openspec/config.yaml. Этот шаг нужно выполнить вручную, так как форк не изменяет config.yaml:

   Copy Text

   schema: spec-driven-custom

5. Новые предложения об изменениях теперь будут следовать вашей схеме. Изменения, созданные ранее, сохранят схему, с которой они были начаты.

Чтобы заменить схему по умолчанию везде, не затрагивая config.yaml, создайте форк с тем же именем: openspec schema fork spec-driven spec-driven. В этом случае копия в вашем проекте перекроет встроенную схему, как объясняется в разделе Где хранятся схемы.

Создание с нуляCopy Anchor Link

Команда openspec schema init генерирует каркас новой схемы вместо копирования существующей:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

Сгенерированный каркас минимален. Артефакты выбираются только из четырёх встроенных идентификаторов, а созданные шаблоны не содержат инструкций, поэтому агент будет получать меньше указаний, пока вы не напишете собственные. В остальном применяются те же шаги, что и при создании форка: выполните валидацию схемы, а затем укажите её в config.yaml.

Редактирование вашего форкаCopy Anchor Link

В форке есть два типа файлов для редактирования:

• templates/ изменяют каркас каждого документа. Добавьте раздел в шаблон задач, и каждый новый файл tasks.md будет начинаться с него. Сохраняйте заголовок с # на первой строке: артефакт наследует его, поэтому каждый сгенерированный файл открывается как документ с заголовком.
• schema.yaml изменяет сам процесс: какие артефакты существуют, от каких артефактов зависит каждый из них и какую инструкцию получает агент при его создании.

Например, чтобы исключить документ дизайна для упрощения процесса:

1. Удалите запись design из schema.yaml.

2. Удалите design из списка requires у артефакта tasks.

3. Выполните валидацию:

   Copy Text

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Если пропустить шаг 2, валидация обнаружит ошибку:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Выполняйте валидацию после каждого ручного редактирования. В противном случае проблема со схемой проявится в середине работы над изменением, когда процесс запросит несуществующий файл. Как и в случае с config.yaml, правки схемы станут доступны агенту при следующем запуске.

Форк — это снимок состоянияCopy Anchor Link

Команда openspec update обновляет установленные навыки и команды, но никогда не затрагивает openspec/schemas/. Ваш форк продолжает работать именно так, как вы его настроили, но это также означает, что он перестаёт получать улучшения по мере развития встроенной схемы. Чтобы перенести их позже, снова создайте форк встроенной схемы под новым именем и перенесите в него свои отличия.

Обмен схемамиCopy Anchor Link

Поделиться схемой — значит просто скопировать её папку.

• С вашей командой: закоммитьте openspec/schemas/, и все участники репозитория смогут её использовать.
• Между вашими проектами: поместите папку в пользовательскую директорию, указанную в разделе Где хранятся схемы.
• От сообщества: в каталоге сообщества перечислены общие схемы. Скопируйте нужную в openspec/schemas/<name>, и она будет работать как ваша собственная.

Мы работаем над реестром схем (публичным и приватным), чтобы схемы можно было устанавливать по имени, а не копировать вручную.

Использование OpenSpec с SuperpowersCopy Anchor Link

Поддерживаемая сообществом схема superpowers-bridge связывает артефакты OpenSpec с навыками выполнения Superpowers. Перед копированием схемы в свой проект ознакомьтесь с примечаниями по установке и совместимости моста.

Этот мост выпускается отдельно от OpenSpec. OpenSpec не тестирует и не версионирует свою интеграцию с Superpowers.