21 KiB
Схема use-case-driven
use-case-driven — переносимая русскоязычная схема OpenSpec, основанная на
spec-driven. Она задаёт workflow proposal → specs / design → tasks;
формат требований определён в schema.yaml и шаблонах. Существующие changes
с явно указанной schema: spec-driven продолжают использовать свою схему.
Уровни спецификации
- 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 входит в заголовок и подпись ссылки.
### 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».
Форматы Use case
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания. Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
#### 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: таблица содержит поля,
типы, ограничения/default и назначение. Паттерн не требует писать SQL DDL.
Контракт сообщения или технического лога в FR оформляется по
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>.
Учёт 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. Форматирование спецификации само по себе не реализует этот контракт в приложении.
Архитектурные решения (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.
Проверки
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.