schema.yaml

schema.yaml перечисляет файлы планирования, которые создаёт процесс. Он также определяет порядок их создания и переход к этапу реализации.

РасположениеCopy Anchor Link

Схема проекта размещается в каталоге openspec/schemas/<name>/:

openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

OpenSpec ищет этот каталог в трёх местах. Выбирается первое совпадение.

Если задана переменная XDG_DATA_HOME, пользовательский каталог на всех платформах перемещается в $XDG_DATA_HOME/openspec/schemas/<name>/.

Имя каталога служит ключом поиска, который используют флаг --schema, файл config.yaml и .openspec.yaml. Если значение поля name отличается от имени каталога, OpenSpec всё равно использует для поиска имя каталога.

Команда openspec schema which <name> выводит активный каталог и все скрытые им копии с более низким приоритетом.

Поля верхнего уровняCopy Anchor Link

Поля артефактаCopy Anchor Link

Каждая запись в списке artifacts определяет один файл или набор файлов планирования.

generatesCopy Anchor Link

Путь отсчитывается от каталога изменения. Для изменения с именем add-auth:

generates: proposal.md

Артефакт будет записан сюда:

openspec/changes/add-auth/proposal.md

Glob-выражение может соответствовать нескольким файлам:

generates: specs/**/*.md

Это выражение соответствует файлам Markdown внутри openspec/changes/add-auth/specs/.

OpenSpec поддерживает следующие формы glob-выражений в поле generates:

• Подстановочные знаки и классы символов: значения, содержащие *, ? или [, например specs/**/*.md и review-[ab].md.
• Раскрытие фигурных скобок: альтернативы вроде review-{api,ui}.md и диапазоны вроде file-{1..3}.md.
• Расширенные glob-выражения (extglobs): конструкции вида @(proposal|design).md, +(proposal|design).md и !(proposal|design).md.

Буквальные имена файлов: начальный символ ! сам по себе не делает строку glob-выражением. Используйте generates: '!review.md', чтобы задать такое имя файла. Обычные круглые скобки, например (proposal|design).md, и фигурные скобки с одним элементом, например review-{api}.md, также трактуются буквально.

OpenSpec отклоняет абсолютные пути, пути с сегментом .., а также glob-выражения, в которых фигурные или круглые скобки вложены более чем на 16 уровней вглубь, например {a,{b,{c,...}}}. На практике достаточно одного или двух уровней. Также отклоняются glob-выражения, чьи фигурные скобки раскрываются более чем в 1 024 варианта, например повторённая одиннадцать раз конструкция {a,b} или диапазон вроде file-{1..5000}.md. В этом случае выводится ошибка Artifact output pattern expands to more than 1024 patterns. Реальные выражения раскрываются лишь в несколько вариантов.

ЗавершённостьCopy Anchor Link

OpenSpec проверяет наличие выходного файла. Он не читает содержимое файла, чтобы определить, готов ли артефакт.

templateCopy Anchor Link

Путь отсчитывается от каталога templates/ схемы. В схеме review-first:

template: proposal.md

OpenSpec читает следующий файл:

openspec/schemas/review-first/templates/proposal.md

OpenSpec передаёт содержимое шаблона агенту в качестве формата вывода. Сам шаблон в каталог изменения не копируется.

OpenSpec отклоняет абсолютные пути и пути, содержащие сегмент ...

requiresCopy Anchor Link

• Зависимости: каждый идентификатор в requires должен указывать на другой артефакт в той же схеме.
• Состояние готовности: артефакт становится готов к созданию после завершения всех его зависимостей.
• Некорректные графы: несуществующие идентификаторы, дубликаты идентификаторов и циклические зависимости не проходят валидацию.
• Одинаковый приоритет: если к созданию готовы сразу несколько артефактов, порядок их следования в artifacts определяет, какой из них OpenSpec вернёт первым.

Поля этапа примененияCopy Anchor Link

Блок apply определяет, что должно существовать до начала реализации.

Поле requires у артефакта управляет порядком планирования. Поле apply.requires управляет моментом готовности инструкций для этапа применения.

tracksCopy Anchor Link

Путь отсчитывается от каталога изменения. Для изменения с именем add-auth настройка tracks: tasks.md обращается к файлу:

openspec/changes/add-auth/tasks.md

Glob-выражение, например tracks: "**/tasks.md", читает все подходящие файлы, такие как backend/tasks.md и frontend/tasks.md. OpenSpec объединяет содержащиеся в них задачи и общий прогресс. Используйте то же значение, что и в поле generates соответствующего артефакта, чтобы команды проверки статуса и вывода списка отслеживали одни и те же файлы. Ограничения на фигурные скобки из generates (глубина вложенности до 16 уровней, не более 1 024 вариантов при раскрытии) действуют и здесь.

Этап применения остаётся заблокированным, если ни один файл не найден или в найденных файлах нет ни одного чекбокса с текстом задачи. OpenSpec учитывает следующие форматы чекбоксов:

- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

Подходит любой маркер списка Markdown: -, *, + или число длиной до девяти цифр, за которым следует . или ). Допускаются начальные пробелы. В разделе tasks.md на странице схемы spec-driven описан более строгий формат, который создаётся схемой по умолчанию.

Отслеживаемые файлы определяют состояние этапа применения:

• blocked: не найдено ни одного файла или ни в одном доступном для чтения файле нет чекбокса с текстом задачи.
• ready: есть хотя бы одна невыполненная задача, либо один из найденных файлов не удалось прочитать, но задачи есть в другом файле.
• all_done: все отслеживаемые задачи отмечены как выполненные, и все подходящие файлы успешно прочитаны.

Если один из подходящих файлов не удаётся прочитать, этап применения сохраняет задачи и прогресс из доступных файлов, но не переводит изменение в состояние all_done. JSON-вывод этапа применения указывает каждый недоступный файл и причину ошибки.

OpenSpec отклоняет абсолютные пути и пути, содержащие сегмент ...

Значения по умолчанию для примененияCopy Anchor Link

Полный примерCopy Anchor Link

name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

ВалидацияCopy Anchor Link

Команда openspec schema validate <name> проверяет:

• Типы полей и наличие обязательных полей
• Относительные пути
• Идентификаторы артефактов, зависимости и циклы
• Идентификаторы в apply.requires: каждый должен указывать на артефакт в этой схеме
• Файлы шаблонов

Схема с неизвестным идентификатором в apply.requires не загружается, поэтому любая использующая её команда сообщит об ошибке.

Валидация выводит предупреждение (без завершения с ошибкой), если значение apply.tracks не совпадает в точности со значением generates какого-либо артефакта. OpenSpec находит отслеживаемый артефакт путём прямого сравнения этих двух строк, поэтому при любом расхождении он не сможет определить, к какому артефакту относится прогресс из файла. Это касается как опечаток вроде task.md, так и случаев вида tracks: tasks/main.md при generates: tasks/*.md, когда glob-выражение охватывает нужный файл, но сами строки различаются. Этап применения в любом случае прочитает указанный файл, однако команды openspec list и openspec status будут вести подсчёт по tasks.md.

Валидация не выявляет следующие ошибки: