name: use-case-driven version: 1 description: >- Иерархические спецификации поведения: один Requirement описывает завершённую функцию через сценарий использования без Gherkin, а связанные FR фиксируют подробные правила, устойчивые контракты и обязательные ограничения системы. artifacts: - id: proposal generates: proposal.md description: Начальный документ предложения, описывающий изменение template: proposal.md instruction: | Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические идентификаторы, названия API, файлов, инструментов, команды и коды не переводи. Объясни, ПОЧЕМУ требуется изменение. Объём — 1–2 страницы; детали реализации относятся к design.md. Разделы: - **Why**: 1–2 предложения о проблеме или возможности и причинах изменения сейчас. - **What Changes**: Точный список новых возможностей, изменений и удалений; несовместимые изменения помечай **BREAKING**. - **Capabilities**: Создаваемые или изменяемые спецификации отдельных бизнес-функций или понятных результатов. Сохраняй полный иерархический путь, например `domain/capability-name`. Короткий читаемый префикс Requirement для новой capability: первые три буквы однословного сегмента или первые буквы частей сегмента с дефисами; верхний регистр, точки и порядок сегментов (`domain/capability-name` → `DOM.CN`). Проверь уникальность префикса по Requirement ID основных спецификаций; при совпадении удлиняй сокращения новых сегментов до уникальности. Существующие префиксы не меняй, включая переименование capability. - **New Capabilities**: Перечисли новые capabilities; для каждой создай `specs//spec.md`; новые сегменты пиши в `kebab-case`, следуя структуре проекта. - **Modified Capabilities**: Укажи существующие capabilities только при изменении описанного поведения, а не деталей реализации. Создай delta spec по точному существующему пути внутри `openspec/specs/`; если требования не меняются, оставь список пустым. - **Impact**: Затронутые код, API, зависимости и системы. - **Project Context**: Создаваемые или обновляемые постоянные документы, включая решение о необходимости ADR. Отсутствие изменений укажи явно. Перед заполнением Capabilities изучи существующие specs: 1. `openspec list --specs` — список capabilities; без `--specs` выводятся changes. 2. Для подходящих вариантов — `openspec show "" --type spec --json --no-scenarios`: обзор назначения и требований без загрузки целых спецификаций. 3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком, включая сценарии: `openspec show "" --type spec`. Добавляй `--store ""` к этим командам только для зарегистрированного отдельного хранилища. Сохраняй `--type spec`, чтобы избежать неоднозначности при одинаковых именах change и spec. Используй точный путь существующей capability, не создавай похожее имя. Каждой перечисленной capability соответствует файл спецификации. Change должен содержать новую/изменяемую capability либо `skip_specs: true` в `.openspec.yaml`: иначе `openspec validate` отклонит отсутствие delta. `skip_specs: true` допустим только без изменения описанного поведения (чистый рефакторинг, инструменты, документация). Не добавляй требования ради проверки. Для Project Context прочитай существующий `openspec/context/index.md` и относящиеся к change документы из него. Не копируй функциональные требования Specs в Context. Отсутствующий индекс включай в scope только при введении постоянных документов контекста или принятии проектом этой навигационной модели. requires: [] - id: specs generates: "specs/**/*.md" description: Подробные спецификации изменения template: spec.md instruction: | Пиши пояснения по-русски; обязательные заголовки OpenSpec, идентификаторы, названия API и коды не переводи. Описывай наблюдаемое поведение и устойчивые контракты в формате без Gherkin. Правила применяются к основным specs и полным блокам ADDED/MODIFIED в delta. Иерархия и границы: - Capability — отдельная бизнес-функция или понятный результат; сохраняй полный иерархический путь, например domain/capability-name. - Основная спецификация содержит раздел ## Границы между Purpose и Requirements: кратко укажи ответственность, область, исключения и владельцев соседних обязанностей — другие capabilities или приложения. Не дублируй Requirements и FR; сведения об ответственности допустимы без задания поведения. - Requirement — одна завершённая техническая функция, стабильный ID вида AREA.CAP-01 и ровно один Scenario. Не дроби процесс на чтение, валидацию и запись. - Префикс — сокращения сегментов пути capability через точки; проверяй уникальность по ID основных specs. Номер уникален внутри capability; унаследованные Requirements могут сохранять прежние ID. - Заголовки OpenSpec: ### Requirement: и #### Scenario:. - Описание Requirement содержит SHALL/MUST и наблюдаемый результат. - В Requirements и FR оставляй только наблюдаемое поведение, устойчивые контракты и обязательные технические ограничения. Удаляй повторы и пояснения, не влияющие на поведение и не снимающие неоднозначность контракта. Scenario: - Выбирай формат по сложности сценария, независимо от типа FR и части системы (процесс, БД, API, UI и другие). - Полный Use case используй для крупных многошаговых сценариев с большим количеством последовательных действий, а не для простых коротких требований. - Сокращённый Use case используй для простых коротких требований, а не для объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты на выделение в отдельные Requirements для переиспользования в сценариях других Requirements. - Полный сценарий содержит разделы Участники, Предусловия, Основной поток, Альтернативы и ошибки, Результат, Коды завершения — в таком порядке. - Сокращённый сценарий содержит только `##### Основной поток`, без других разделов и ветвлений выполнения; каждый шаг кратко описывает аспект и ссылается на FR. - В обычном сценарии Назначение опционально: добавляй только сведения, которых нет в заголовке. Контекст отсутствует. - Основной поток — нумерованные короткие шаги «Что делаем — как делаем». - В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR. - Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария выбирай по его сложности. Сложные правила шагов выноси в FR со ссылками из сценария. - Основной поток и альтернативы обычного сценария включают коды завершения, если они определены для этой функции. - Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты сообщений и дальнейшая логика располагаются за пределами Scenario. - Единственная таблица Scenario — Коды завершения с колонками Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE. - Код сам сообщает смысл итога без дополнительного этапа или свободного текста. Промежуточные события не являются кодами завершения; не создавай код для каждой диагностики. - Каждый код ссылается на локальные FR с дальнейшей логикой, текстом или правилами результата. - Каждый шаг, альтернатива и абзац сценария — не более 240 знаков содержательного текста без адресов Markdown-ссылок. - Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT. Функциональные требования: - После Scenario идёт `#### Функциональные требования` с заголовками `##### .FR-NN [метка]: <название>`; метка опциональна. Локальная нумерация начинается с FR-01 в каждом Requirement. - FR — отдельное понятное правило или связанный контракт; не дроби связную логику на множество атомарных FR. - FR без метки — логика, правила или последовательность шагов. Метки [DB], [API], [UI] ставь сразу после ID; они не входят в ID и не меняют slug. - [DB] — структура БД; для таблицы следуй `openspec/schemas/use-case-driven/patterns/database-table.md`. - [API] — контракт сообщения или технического лога; сериализуемое сообщение оформляй по `openspec/schemas/use-case-driven/patterns/message-contract.md`. - [UI] — требования к UI; детальный паттерн будет добавлен отдельно. - HTTP-контракт размещай после Функциональных требований в завершающем CONTRACT, не в отдельных FR. Подразделы — Request, затем Response. В Request указывай один HTTP-метод и путь, явно отмечай отсутствие тела. Таблицы тела запроса и ответа оформляй по message-contract.md. - В response-таблицах для каждого поля укажи источник или правило формирования: в последней колонке CONTRACT и в «Формирование значения» для FR [API]. - Не добавляй HTML-якоря ; используй Markdown-якоря заголовков. - Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка, например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. - Сохраняй существующие ID. При изменении FR сохраняй его номер; новые FR добавляй в конец. Порядок первого документа последовательный. - Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия, если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода. - При отличии смыслового кода от текущего поведения явно опиши в FR соответствие и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением. Работа с OpenSpec: - Создай specs//spec.md для каждой capability из proposal. - Основная spec: Purpose, ## Границы и полный актуальный набор Requirements. Ориентир формата — templates/main-spec.md, не генерируемый артефакт. - Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements. - Для новой capability начинай delta с ## Purpose (не менее 50 знаков); для существующей Purpose не добавляй. - MODIFIED содержит полный Requirement: ID, один Scenario и все FR; заголовок совпадает с соответствующим Requirement основной spec. - В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO. Это операции над требованиями, не сценарии технических функций. - В delta сохраняй ID Requirements, номера и заголовки FR со slug-ссылками. Для ссылок на неизменённый Requirement основной spec проверяй delta с `--base `. - Без изменения поведения (чистое форматирование, инструменты, рефакторинг) используй `skip_specs: true`, не создавай delta. - Проверки: `openspec schema validate use-case-driven`; для spec — `openspec validate` и `python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids `. Для неизменённых specs со старыми ID флаг не нужен. OpenSpec не проверяет все правила формата. requires: - proposal - id: design generates: design.md description: Техническое описание решения и деталей реализации template: design.md instruction: | Пиши пояснения по-русски; обязательные заголовки OpenSpec, технические идентификаторы, названия файлов, инструментов и команды не переводи. Design объясняет, КАК реализовать изменение: архитектуру и подход, не пошаговый код. Добавляй design.md при любом из условий: - Несколько сервисов/модулей или новый архитектурный подход. - Внешняя зависимость или существенное изменение модели данных. - Сложности безопасности, производительности или миграции. - Технические решения для устранения неоднозначности до разработки. Разделы: - **Context**: Только текущее состояние и ограничения для объяснения подхода. - **Goals / Non-Goals**: Что решение обеспечивает и исключает; границы решения без повтора scope proposal. - **Decisions**: Ключевые технические решения, их обоснование и рассмотренные альтернативы. - **Risks / Trade-offs**: Ограничения и проблемы в формате [Риск] → [Меры снижения]. - **Migration Plan**: Развёртывание и откат, если применимо. - **Open Questions**: Только безопасно отложенные вопросы, не влияющие на specs, подход или состав задач. При отсутствии вопросов раздел не добавляй. Влияющие вопросы выясни с пользователем сейчас, не подменяй ответ предположением. Вместо повтора причин и состава изменения ссылайся на proposal, вместо копирования требований — на specs, используя Requirement ID и локальные FR. Сверь Project Context proposal с design: нужны ли новые/обновлённые постоянные документы и индекс? В Context ссылайся на требования Specs без дублирования. Перед проектированием прочитай применимые принятые ADR в `openspec/context/adr/` и укажи ID в Decisions. Для долгосрочного архитектурного решения или замены принятого запланируй новый ADR по `openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed; самостоятельно не принимай его. Конфликт с действующим ADR явно опиши и получи решение пользователя до выбора расходящегося подхода. requires: - proposal - id: tasks generates: tasks.md description: Контрольный список задач с отслеживаемым выполнением template: tasks.md instruction: | Пиши группы и задачи по-русски; обязательные идентификаторы, пути файлов, названия API, коды и команды не переводи. Разбей реализацию на задачи по specs (что создать) и design (как реализовать). Проверь Open Questions в design.md: влияющие на результат вопросы сначала обсуди с пользователем; не закладывай неоговорённые предположения. Следуй шаблону: apply отслеживает только чекбоксы. Только `x` внутри скобок означает выполнение независимо от регистра и пробелов; любая другая отметка, включая пустые скобки, считается незавершённой. Строки без чекбокса не отслеживаются. Правила: - Группируй связанные задачи под нумерованными заголовками `##`. - Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`. - Каждая задача выполнима за одну сессию; порядок соответствует зависимостям. - В описание каждого чекбокса включай проверку: тест, команду, наблюдаемое поведение или готовый артефакт. Отдельная задача проверки допустима только для интеграционных/системных сценариев, охватывающих несколько задач реализации. Пример: ``` - [ ] 1.1 Реализовать экспорт данных и проверить прохождение теста экспорта ``` Связывай задачи с Requirement ID, FR и кодами завершения, если они затронуты. Для нового или заменяющего ADR из design добавь отдельную задачу создания в `openspec/context/adr/` со статусом Proposed. При замене принятого решения свяжи новый и прежний ADR полями `supersedes` и `superseded-by`. Если proposal/design предусматривает создание/обновление постоянных документов контекста, добавь отдельные проверяемые задачи. Обнови `openspec/context/index.md` при изменении состава документов; отсутствующий индекс создавай только при введении постоянных документов контекста или принятии проектом этой навигационной модели. requires: - specs - design apply: requires: [ tasks ] tracks: tasks.md instruction: | Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их выполненными по мере работы, включая задачи по обновлению проектного контекста и его индекса. Если индекс существует или его создание входит в tasks.md, проверь, что он соответствует фактическому набору документов. Убедись, что требования Specs не продублированы в Context. Остановись, если столкнёшься с препятствием или потребуется уточнение.