Template
256 lines
21 KiB
Markdown
256 lines
21 KiB
Markdown
# Схема use-case-driven
|
||
|
||
`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
|
||
`spec-driven`. Она задаёт workflow `proposal → specs / design → tasks`;
|
||
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
|
||
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
|
||
|
||
## Настройка YouTrack
|
||
|
||
Правила YouTrack входят в `schema.yaml`. Для каждого проекта укажи в блоке
|
||
`context` файла `openspec/config.yaml` ключ проекта и имя приложения. Добавь
|
||
строки в существующий блок, сохранив остальной проектный контекст:
|
||
|
||
```yaml
|
||
context: |
|
||
YouTrack project key: <KEY>
|
||
YouTrack application label: <APP-NAME>
|
||
```
|
||
|
||
Схема создаёт одну задачу `Task` на change, добавляет к ней тег с указанным
|
||
именем приложения и учитывает фактическое время от Explore до архивации. В
|
||
YouTrack этот механизм называется тегом; настройка `application label` задаёт
|
||
точное имя этого тега. Если интеграция или тег недоступны, workflow останавливается
|
||
и сообщает о проблеме, а не создаёт задачу без метки приложения.
|
||
Завершающие действия YouTrack для команды `openspec archive` настраиваются отдельно
|
||
от схемы — в `operations.archive.guidance` файла `openspec/config.yaml`:
|
||
|
||
```yaml
|
||
operations:
|
||
archive:
|
||
guidance:
|
||
- >-
|
||
Перед openspec archive внеси в связанную задачу YouTrack оставшееся
|
||
фактическое время, учитывая только ещё не записанное. После успешной
|
||
архивации переведи задачу в конечный статус проекта по доступным полям;
|
||
не угадывай статус. Change завершён после архивации и закрытия задачи.
|
||
```
|
||
|
||
## Уровни спецификации
|
||
|
||
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
|
||
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
|
||
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
|
||
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
||
- FR — подробные правила и контракты сообщений за пределами Scenario;
|
||
контракт HTTP endpoint размещается в завершающем CONTRACT.
|
||
|
||
Requirements и FR включают только сведения, влияющие на наблюдаемое поведение,
|
||
устойчивый контракт или обязательное техническое ограничение. Раздел «Границы»
|
||
кратко фиксирует ответственность и владение capability, не повторяя Requirements.
|
||
Повторы и пояснения без такого влияния удаляются.
|
||
|
||
Составной префикс Requirement строится из сокращений сегментов пути capability:
|
||
для однословного сегмента используй первые три буквы, для сегмента с дефисами —
|
||
первые буквы его частей. Приводи сокращения к верхнему регистру. Например,
|
||
`domain/capability-name` получает `DOM.CN`. Если префикс уже занят, удлиняй
|
||
сокращения новых сегментов до уникальности; ранее назначенные префиксы не меняй.
|
||
Сохраняй префикс при переименовании capability. Валидатор проверяет уникальность
|
||
по ID в master specs и активных changes; отдельный реестр кодов не ведётся.
|
||
|
||
ID Requirement имеет вид `AREA.CAP-01`; его номер уникален внутри capability.
|
||
Полный ID уникален в проекте благодаря уникальному префиксу и номеру.
|
||
ID FR включает ID Requirement и локальный номер: `AREA.CAP-01.FR-01`,
|
||
`AREA.CAP-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement.
|
||
В новых и изменяемых Requirements используй составные ID. Неизменённые legacy
|
||
specs могут сохранять прежние ID до отдельного рефакторинга.
|
||
|
||
## Формат Requirement
|
||
|
||
Markdown-рендерер автоматически создаёт якоря из заголовков Requirement и FR.
|
||
Не добавляй HTML `<a id="..."></a>`. Ссылки используй на slug заголовка; при
|
||
переименовании заголовка обновляй все ссылки на него. Семантический ID Requirement
|
||
остаётся в строке `**ID:**`; полный ID FR входит в заголовок и подпись ссылки.
|
||
|
||
```text
|
||
### Requirement: Завершённая техническая функция
|
||
**ID:** AREA.CAP-01
|
||
Система SHALL ...
|
||
|
||
#### Scenario: Завершённый процесс
|
||
##### Участники
|
||
##### Предусловия
|
||
##### Основной поток
|
||
##### Альтернативы и ошибки
|
||
##### Результат
|
||
##### Коды завершения
|
||
|
||
#### Функциональные требования
|
||
##### AREA.CAP-01.FR-01: Правило обработки
|
||
##### AREA.CAP-01.FR-02 [DB]: Структура таблицы
|
||
##### AREA.CAP-01.FR-03 [API]: Контракт сообщения
|
||
##### AREA.CAP-01.FR-04 [UI]: Требования к интерфейсу
|
||
```
|
||
|
||
В Scenario «Назначение» опционально и добавляется только при наличии сведений,
|
||
которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток —
|
||
нумерованные короткие шаги «Что делаем — как делаем», например:
|
||
«Получаем данные — вызываем GET /api/resources по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)».
|
||
|
||
## Форматы Use case
|
||
|
||
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания.
|
||
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
|
||
|
||
```text
|
||
#### Scenario: Сокращенный use case: описание функции
|
||
##### Основной поток
|
||
1. Описываем первый аспект по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
|
||
2. Уточняем второй аспект по [AREA.CAP-01.FR-02](#areacap-01fr-02-дополнительное-правило).
|
||
```
|
||
|
||
Сокращенный Use case не содержит участников, предусловий, альтернатив и ошибок,
|
||
результата и кодов завершения.
|
||
|
||
Шаг, альтернатива или абзац Scenario содержит не более 240 знаков текста
|
||
без URL Markdown-ссылок. Сценарий не содержит Gherkin, блоков кода, таблиц
|
||
полей и подробных алгоритмов. Технические детали, тексты сообщений и логика находятся в FR; контракт HTTP
|
||
endpoint — в завершающем CONTRACT. Единственная таблица
|
||
Scenario — `Код | Смысл | Связанные FR`.
|
||
|
||
Ссылки ведут на автоматически сгенерированные slugs заголовков FR, например
|
||
`[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-контракт-api-структура-бд-форма-ui)`.
|
||
Полный ID используется внутри Requirement и при ссылке на другую capability.
|
||
Адрес фрагмента соответствует заголовку FR назначения. Каждый код ссылается
|
||
хотя бы на один FR, в котором он описан. Смысл кода понятен без `stage` или текста исключения.
|
||
FR задаёт тексты, дальнейшие действия и связи с другими требованиями.
|
||
Одинаковая обработка нескольких диагностических причин допускает один код.
|
||
Промежуточные события trace не включаются в коды завершения.
|
||
|
||
## Форматы FR
|
||
|
||
Обычный FR не имеет метки типа и описывает логику, правила или последовательность шагов. Специальный формат указывается после ID в заголовке: `[DB]`, `[API]` или `[UI]`. Метка не входит в ID FR и не меняет ссылки на него.
|
||
|
||
- [DB] описывает структуру базы данных по паттерну таблицы БД.
|
||
- FR [API] описывает контракт асинхронного сообщения или сериализуемой записи, включая технический лог. HTTP endpoint описывается в CONTRACT.
|
||
- [UI] зарезервирован для требований к интерфейсу; детальный паттерн будет добавлен отдельно.
|
||
|
||
## HTTP-контракт в Requirement
|
||
|
||
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный
|
||
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце
|
||
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
|
||
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
|
||
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
|
||
отдельные FR для частей HTTP-контракта.
|
||
|
||
Таблица тела Request содержит пять колонок по
|
||
patterns/message-contract.md. Таблица Response содержит те же колонки и
|
||
последнюю колонку «Формирование значения», описывающую источник или правило
|
||
формирования каждого поля. Для отсутствующего тела запроса укажи это явно и не
|
||
добавляй пустую таблицу.
|
||
|
||
## Паттерны FR
|
||
|
||
FR, описывающий таблицу БД, оформляется по
|
||
[`patterns/database-table.md`](patterns/database-table.md): таблица содержит поля,
|
||
типы, ограничения/default и назначение. Паттерн не требует писать SQL DDL.
|
||
Контракт сообщения или технического лога в FR оформляется по
|
||
[`patterns/message-contract.md`](patterns/message-contract.md): таблица задаёт направление,
|
||
поля, wire-типы, обязательность и ограничения. Один FR описывает одно направление.
|
||
В response-таблице также указывается источник или правило формирования каждого поля.
|
||
Другие паттерны добавляются отдельными файлами по мере появления потребности.
|
||
|
||
## Форматы master и delta specs
|
||
|
||
- `templates/main-spec.md` — краткая схема постоянной master spec: Purpose, Границы и Requirements; это не артефакт change.
|
||
- `templates/spec.md` — полный шаблон delta для change, предоставляемый `openspec instructions specs`.
|
||
- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow.
|
||
|
||
В master spec раздел `## Границы` располагается между Purpose и Requirements.
|
||
Он описывает ответственность capability, её включённую область и явные
|
||
исключения или передачу ответственности другим capabilities и приложению.
|
||
В delta spec этот раздел не повторяется: delta меняет отдельные Requirements.
|
||
|
||
ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration,
|
||
RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный
|
||
Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и
|
||
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
|
||
ссылок на неизменённые требования при проверке передай `--base <master-spec>`.
|
||
|
||
Если смысловые коды или сообщения ещё не выдаются приложением, это явно
|
||
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
|
||
Форматирование спецификации само по себе не реализует этот контракт в приложении.
|
||
|
||
## Постоянный контекст проекта
|
||
|
||
Для начальной настройки проекта можно скопировать заготовки из
|
||
[`examples/project-bootstrap/`](../../../examples/project-bootstrap/):
|
||
`AGENTS.md`, `openspec/context/index.md` и инструкции с шаблоном ADR. Они не
|
||
устанавливаются вместе с пользовательской ссылкой на схему и должны быть
|
||
адаптированы к структуре конкретного проекта.
|
||
|
||
При подготовке каждого change оценивай влияние на постоянный контекст в разделе
|
||
`Project Context` файла `proposal.md`. Если индекс контекста существует, изучай
|
||
релевантные документы выборочно. В design сверяй необходимость ADR и других
|
||
документов; задачи на их создание или обновление, включая актуализацию индекса,
|
||
добавляй в `tasks.md`. Выполняй эти задачи в рамках OpenSpec Apply. Не переноси
|
||
функциональные требования из Specs в Context.
|
||
|
||
## Архитектурные решения (ADR)
|
||
|
||
Храни ADR проекта в `openspec/context/adr/` и называй файлы
|
||
`ADR-<номер>-<краткое-описание>.md`, например
|
||
`ADR-0001-use-postgresql.md`. Используй четырёхзначную последовательную
|
||
нумерацию: новый номер на единицу больше максимального номера в каталоге.
|
||
Номер не переиспользуется, даже если решение отклонено или заменено. Краткое
|
||
описание в имени файла пиши в `kebab-case`.
|
||
|
||
Создавай ADR для долгосрочных архитектурных решений с последствиями для
|
||
будущих изменений: выбора между значимыми вариантами, общих ограничений,
|
||
границ компонентов и решений, которые иначе пришлось бы повторно принимать.
|
||
Не создавай ADR для каждого change, деталей реализации, уже полностью заданных
|
||
спецификацией, или временных задач.
|
||
|
||
В ADR фиксируй контекст и проблему, факторы решения, рассмотренные варианты,
|
||
выбранное решение и его последствия. Используй статусы `Proposed`, `Accepted`,
|
||
`Rejected` и `Superseded`. Предложенный ADR становится действующим только после
|
||
явного принятия владельцем решения. Отклонённые и заменённые ADR сохраняй как
|
||
историю. Не меняй принятое решение задним числом: при пересмотре создай новый
|
||
ADR со ссылкой на заменяемый и обнови его статус на `Superseded`. В новом ADR
|
||
укажи заменяемый ID в `supersedes`, а в прежнем — новый ID в `superseded-by`.
|
||
|
||
Перед проектированием и реализацией агент читает применимые принятые ADR.
|
||
Изменение должно ссылаться на относящиеся к нему ADR в `design.md`. При
|
||
противоречии между запросом и принятым ADR агент явно сообщает о конфликте и
|
||
получает решение пользователя, а не обходит ADR молча. Агент может подготовить
|
||
ADR со статусом `Proposed`, но не принимает его самостоятельно.
|
||
|
||
Шаблон нового решения находится в
|
||
[`templates/adr.md`](templates/adr.md).
|
||
|
||
## Проверки
|
||
|
||
```sh
|
||
openspec schema validate use-case-driven
|
||
openspec validate domain/capability-name --type spec --strict --no-interactive
|
||
python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids openspec/specs/domain/capability-name/spec.md
|
||
```
|
||
|
||
Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`.
|
||
Можно передать несколько файлов или каталогов; проверка не изменяет их.
|
||
|
||
Стандартный `openspec schema validate` проверяет workflow, зависимости и наличие
|
||
шаблонов. `openspec validate` проверяет стандартную структуру спецификации.
|
||
Отдельная `validate_format.py --require-qualified-ids <spec-path>` проверяет
|
||
составные ID новых и изменённых Requirements; без флага валидатор также принимает
|
||
неизменённые legacy specs. Проверка охватывает один Scenario,
|
||
обычную структуру use case или формат сокращенного use case, ссылки шагов на FR,
|
||
форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков
|
||
в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
|
||
таблицу кодов и её связь с FR.
|
||
Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
|
||
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
|
||
|
||
Механизм схем и шаблонов: [официальная документация OpenSpec](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md).
|