Files
openspec-schema/README.md
T

95 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Схема OpenSpec `use-case-driven`
`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
базовой `spec-driven`. Она задаёт формат артефактов change и спецификаций
поведения; подробные правила схемы находятся в
[README схемы](openspec/schemas/use-case-driven/README.md).
## Чем отличается от `spec-driven`
- В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`.
Здесь используются сценарии использования без Gherkin: полные или
сокращённые, связанные с функциональными требованиями.
- Один `Requirement` описывает завершённую функцию и содержит один `Scenario`.
Подробные правила, устойчивые контракты и обязательные ограничения
фиксируются в локальных `FR`; HTTP-контракт размещается в `CONTRACT`.
- Master-спецификация явно описывает `Purpose`, `Границы` ответственности
capability и полный набор `Requirements`. Delta-спецификации меняют требования
стандартными операциями OpenSpec.
- Инструкции и пояснительный текст ориентированы на русский язык; технические
идентификаторы и синтаксис OpenSpec сохраняются.
## Подключение схемы в проектах
Схему можно подключить один раз для всех проектов пользователя. OpenSpec ищет
пользовательские схемы в `~/.local/share/openspec/schemas` на macOS и Linux,
а в `%LOCALAPPDATA%\openspec\schemas` на Windows. Если задана переменная
`XDG_DATA_HOME`, OpenSpec использует `$XDG_DATA_HOME/openspec/schemas` вместо
стандартного пути.
1. Клонируйте этот репозиторий в удобную папку. Путь к клону можно выбрать
самостоятельно.
2. В пользовательской папке схем создайте ссылку с именем `use-case-driven`,
ведущую на `openspec/schemas/use-case-driven` внутри клона.
### macOS и Linux
Команды учитывают `XDG_DATA_HOME`, если он задан. Замените путь в `ln -s` на
путь к своему клону:
```sh
schemas_dir="${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas"
mkdir -p "$schemas_dir"
ln -s "/path/to/openspec-schema/openspec/schemas/use-case-driven" \
"$schemas_dir/use-case-driven"
```
### Windows PowerShell
Замените путь в `$schemaSource` на путь к своему клону. Junction создаёт ссылку
на папку без копирования файлов:
```powershell
$schemasDir = if ($env:XDG_DATA_HOME) {
Join-Path $env:XDG_DATA_HOME 'openspec\schemas'
} else {
Join-Path $env:LOCALAPPDATA 'openspec\schemas'
}
$schemaSource = 'D:\path\to\openspec-schema\openspec\schemas\use-case-driven'
New-Item -ItemType Directory -Force -Path $schemasDir
New-Item -ItemType Junction -Path (Join-Path $schemasDir 'use-case-driven') -Target $schemaSource
```
После этого изменения схемы в клоне сразу доступны всем проектам, в которых
указано `schema: use-case-driven`. Проверьте подключение из каталога проекта:
```sh
openspec schema which use-case-driven
openspec schema validate use-case-driven
```
Если в проекте есть собственная схема `openspec/schemas/use-case-driven`, она
имеет приоритет над пользовательской.
Команды создания ссылки предполагают, что путь назначения ещё не занят. Если
там уже есть папка или ссылка `use-case-driven`, сначала проверьте её содержимое
и источник, прежде чем заменять.
В текущей схеме инструкции также ссылаются на дополнительные файлы по путям
относительно проекта, например
`openspec/schemas/use-case-driven/validate_format.py` и `patterns/`. Одна
пользовательская ссылка делает схему и шаблоны доступными OpenSpec, но не
создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная
проектная ссылка либо адаптация инструкций к расположению активной схемы.
## Статус
Схема находится в стадии доработки. Описаны ещё не все типы функциональных
требований и форматы контрактов: например, для FR `[UI]` пока нет подробного
паттерна; могут отсутствовать и другие типы. Поэтому схема пока не гарантирует,
что при подготовке спецификации будут выявлены все применимые требования — в
том числе к безопасности, аудиту и ролевой модели. Эти аспекты нужно явно
учитывать при анализе изменения.