Files

276 lines
25 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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 и другие).
- Полный 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 идёт `#### Функциональные требования` с заголовками
`##### <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.
Остановись, если столкнёшься с препятствием или потребуется уточнение.