Compare commits

...
2 Commits
5 changed files with 136 additions and 1 deletions
+65
View File
@@ -5,6 +5,7 @@
поведения; подробные правила схемы находятся в поведения; подробные правила схемы находятся в
[README схемы](openspec/schemas/use-case-driven/README.md). [README схемы](openspec/schemas/use-case-driven/README.md).
## Чем отличается от `spec-driven` ## Чем отличается от `spec-driven`
- В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`. - В базовой схеме сценарии оформляются краткими шагами Gherkin `WHEN` / `THEN`.
@@ -19,6 +20,70 @@
- Инструкции и пояснительный текст ориентированы на русский язык; технические - Инструкции и пояснительный текст ориентированы на русский язык; технические
идентификаторы и синтаксис 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, но не
создаёт эти пути внутри каждого проекта. Для таких файлов потребуется отдельная
проектная ссылка либо адаптация инструкций к расположению активной схемы.
## Статус ## Статус
Схема находится в стадии доработки. Описаны ещё не все типы функциональных Схема находится в стадии доработки. Описаны ещё не все типы функциональных
+2
View File
@@ -1,5 +1,7 @@
schema: use-case-driven schema: use-case-driven
# При настройке проекта YouTrack добавьте в context строку:
# YouTrack project key: <KEY>
context: | context: |
ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и ADR проекта хранятся в `openspec/context/adr/`. Перед проектированием и
реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если реализацией прочитай применимые ADR со статусом Accepted и следуй им. Если
@@ -147,6 +147,35 @@ Scenario в таких операциях не создаётся. В delta со
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
ссылок на неизменённые требования при проверке передай `--base <master-spec>`. ссылок на неизменённые требования при проверке передай `--base <master-spec>`.
## Учёт change в YouTrack
Каждый новый change, включая change с `skip_specs: true`, получает ровно одну
задачу типа Task в YouTrack-проекте соответствующего репозитория. Сначала
подготовь содержательный proposal с причиной, scope, capabilities и impact;
затем, до перехода к specs, design и tasks, создай задачу через подключённый
YouTrack MCP. Ключ проекта укажи в `context` файла `openspec/config.yaml`; добавь
строку `YouTrack project key: <KEY>`. Если строки нет или ключ нельзя однозначно
проверить через MCP, уточни его у пользователя; проект `Default` не является
автоматическим запасным вариантом. Перед созданием прочитай схему обязательных
полей проекта и используй только допустимые значения. Не добавляй произвольное
верхнеуровневое поле `youtrack_project`: оно не входит в контракт OpenSpec.
В задаче укажи slug change и краткую цель, а её ключ и URL сохрани в разделе
`## YouTrack` файла `proposal.md`. При создании задачи также внеси work item с
фактически затраченным временем на подготовку контекста change и proposal.
При каждом последующем редактировании proposal пересмотри заголовок и описание
задачи. Если изменились причина, scope, capabilities или impact, обнови связанную
задачу через MCP в соответствии с актуальным proposal; не создавай дубликат.
Если MCP недоступен, явно сообщи об этом и уточни дальнейшее действие.
На всех этапах change — от подготовки proposal до реализации — записывай
фактически затраченное время в YouTrack как work items, используя поддерживаемый
проектом тип работы и не дублируя уже внесённые записи. При архивировании учти
всё оставшееся время, затем выполни `openspec archive`; после успешной архивации
переведи связанную задачу в конечный статус, предусмотренный YouTrack-проектом.
Определи поле и значение статуса по схеме проекта, не угадывай их. Change
завершён только после успешного архивирования и закрытия задачи.
Если смысловые коды или сообщения ещё не выдаются приложением, это явно Если смысловые коды или сообщения ещё не выдаются приложением, это явно
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes. фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
Форматирование спецификации само по себе не реализует этот контракт в приложении. Форматирование спецификации само по себе не реализует этот контракт в приложении.
+35 -1
View File
@@ -43,6 +43,7 @@ artifacts:
Для каждой создай delta spec по точному существующему пути внутри Для каждой создай delta spec по точному существующему пути внутри
`openspec/specs/`. Оставь список пустым, если требования не меняются. `openspec/specs/`. Оставь список пустым, если требования не меняются.
- **Impact**: Затронутые участки кода, API, зависимости и системы. - **Impact**: Затронутые участки кода, API, зависимости и системы.
- **YouTrack**: После создания задачи укажи её ключ и URL.
ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs. ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs.
Перед его заполнением изучи существующие спецификации: выполни Перед его заполнением изучи существующие спецификации: выполни
@@ -63,6 +64,26 @@ artifacts:
(с тем же правилом для `--store`). Для каждой перечисленной capability (с тем же правилом для `--store`). Для каждой перечисленной capability
потребуется соответствующий файл спецификации. потребуется соответствующий файл спецификации.
После подготовки содержательного первого варианта proposal создай для
каждого нового change, в том числе с `skip_specs: true`, ровно одну задачу
типа Task в YouTrack-проекте этого репозитория через подключённый YouTrack
MCP. Создай задачу до перехода к specs, design и tasks, используя причину,
scope и impact из proposal. Бери ключ проекта из `context` файла
`openspec/config.yaml`; в нём должна быть строка `YouTrack project key: <KEY>`.
Если строка отсутствует или ключ нельзя однозначно проверить через MCP,
уточни его у пользователя. Проект `Default` не используй как запасной
вариант. Перед созданием проверь схему обязательных полей проекта; не выдумывай значения.
Укажи slug change и краткую цель в задаче, затем
заполни в proposal раздел YouTrack ключом и URL задачи. Добавь work item с
фактически затраченным до этого временем на подготовку контекста change и
proposal.
При каждом последующем редактировании proposal пересмотри формулировки
заголовка и описания связанной YouTrack-задачи. Если причина, scope,
capabilities или impact изменились, обнови задачу через MCP так, чтобы они
соответствовали актуальному proposal; не создавай новую задачу. Если MCP
недоступен, сообщи об этом и уточни, как продолжить.
В каждом изменении (`change`) должна быть указана хотя бы одна новая или В каждом изменении (`change`) должна быть указана хотя бы одна новая или
изменяемая capability либо явный отказ от спецификаций: `openspec validate` изменяемая capability либо явный отказ от спецификаций: `openspec validate`
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не
@@ -334,6 +355,12 @@ artifacts:
Связывай задачи с Requirement ID, FR и кодами завершения, если задача Связывай задачи с Requirement ID, FR и кодами завершения, если задача
затрагивает эти результаты. затрагивает эти результаты.
YouTrack-задача из proposal сопровождает весь change и не заменяет
чекбоксы реализации в tasks.md. На всех этапах change — от подготовки
proposal до реализации — записывай в YouTrack фактически затраченное время
отдельными work items через MCP, без дублирования уже внесённого времени.
Выбирай только тип работы, поддерживаемый проектом.
Если в design предусмотрен новый или заменяющий ADR, включи в tasks Если в design предусмотрен новый или заменяющий ADR, включи в tasks
отдельную задачу на его создание в `openspec/context/adr/` со статусом отдельную задачу на его создание в `openspec/context/adr/` со статусом
Proposed. При замене принятого решения свяжи новый и прежний ADR через Proposed. При замене принятого решения свяжи новый и прежний ADR через
@@ -348,4 +375,11 @@ apply:
instruction: | instruction: |
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
выполненными по мере работы. Остановись, если столкнёшься с препятствием или выполненными по мере работы. Остановись, если столкнёшься с препятствием или
потребуется уточнение. потребуется уточнение. Для change с задачей YouTrack записывай фактически
затраченное во время apply время в её work items через MCP; перед
архивированием проверь, что учтено всё время работы над change. После
успешного `openspec archive`
переведи задачу в конечный статус, предусмотренный проектом YouTrack,
используя доступную схему полей и значений. Не подставляй предполагаемое
название статуса. Считай change завершённым только после успешного
архивирования и закрытия YouTrack-задачи.
@@ -27,3 +27,8 @@
## Impact ## Impact
<!-- Затронутые код, API, зависимости и системы --> <!-- Затронутые код, API, зависимости и системы -->
## YouTrack
<!-- Заполни после подготовки proposal и создания задачи. -->
- Задача: `<PROJECT-123>` — <issue URL>