Template
270 lines
25 KiB
YAML
270 lines
25 KiB
YAML
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/<capability-path>/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 "<spec-id>" --type spec --json --no-scenarios`:
|
||
обзор назначения и требований без загрузки целых спецификаций.
|
||
3. До решения о покрытии и изменениях прочитай каждую подходящую spec целиком,
|
||
включая сценарии: `openspec show "<spec-id>" --type spec`.
|
||
Добавляй `--store "<id>"` к этим командам только для зарегистрированного
|
||
отдельного хранилища. Сохраняй `--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 и другие), кроме обязательного полного HTTP-сценария.
|
||
- Полный сценарий содержит разделы Участники, Предусловия,
|
||
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
||
в таком порядке.
|
||
- Сокращённый сценарий содержит только `##### Основной поток`, без других
|
||
разделов и ветвлений выполнения; каждый шаг кратко описывает аспект и ссылается на 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 идёт `#### Функциональные требования` с заголовками
|
||
`##### <requirement-id>.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-якоря <a id="..."></a>; используй Markdown-якоря заголовков.
|
||
- Ссылки на FR внутри и между Requirements содержат полный ID и slug заголовка,
|
||
например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
|
||
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
|
||
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
|
||
новые FR добавляй в конец. Порядок первого документа последовательный.
|
||
- Для кодов укажи в FR тексты и поведение, включая отсутствие сообщения/действия,
|
||
если это часть контракта. Параметры сообщений — данные, не скрытый смысл кода.
|
||
- При отличии смыслового кода от текущего поведения явно опиши в FR соответствие
|
||
и статус реализации; не выдавай новый код или текст за уже возвращаемый приложением.
|
||
|
||
Работа с OpenSpec:
|
||
- Создай specs/<capability-path>/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 <master-spec>`.
|
||
- Без изменения поведения (чистое форматирование, инструменты, рефакторинг)
|
||
используй `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 <spec-path>`.
|
||
Для неизменённых 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.
|
||
Остановись, если столкнёшься с препятствием или потребуется уточнение.
|