# Схема 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 ``. Ссылки используй на 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 `. Если смысловые коды или сообщения ещё не выдаются приложением, это явно фиксируется в 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 ` проверяет составные 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).