Template
386 lines
34 KiB
YAML
386 lines
34 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, файлов,
|
||
инструментов, команд и коды без перевода.
|
||
|
||
Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение.
|
||
|
||
Разделы:
|
||
- **Why**: 1–2 предложения о проблеме или возможности. Какую проблему
|
||
решает изменение? Почему его нужно сделать сейчас?
|
||
- **What Changes**: Список изменений. Точно опиши новые возможности,
|
||
изменения и удаления. Помечай несовместимые изменения как **BREAKING**.
|
||
- **Capabilities**: Укажи, какие спецификации будут созданы или изменены:
|
||
Capability представляет отдельную бизнес-функцию или понятный результат;
|
||
сохраняй полный иерархический путь, например `domain/capability-name`.
|
||
Для новой capability сформируй короткий читаемый префикс Requirement:
|
||
для однословного сегмента используй первые три буквы, для сегмента с
|
||
дефисами — первые буквы его частей. Приводи сокращения к верхнему
|
||
регистру, разделяй сегменты кода точкой и сохраняй их порядок:
|
||
`domain/capability-name` → `DOM.CN`.
|
||
Перед назначением проверь уникальность префикса по Requirement ID в
|
||
основных спецификациях проекта. Если префикс занят, удлиняй сокращения
|
||
новых сегментов до уникальности; уже используемые префиксы не меняй.
|
||
Сохраняй префикс при переименовании capability.
|
||
- **New Capabilities**: Перечисли добавляемые capabilities. Для каждой
|
||
создай `specs/<capability-path>/spec.md`. Используй `kebab-case` для
|
||
новых сегментов пути (например, `user-auth` или `identity/user-auth`)
|
||
и следуй принятой в проекте структуре спецификаций.
|
||
- **Modified Capabilities**: Перечисли существующие capabilities, чьи
|
||
REQUIREMENTS меняются. Добавляй сюда capability только при изменении
|
||
поведения, описанного в спецификации, а не только деталей реализации.
|
||
Для каждой создай delta spec по точному существующему пути внутри
|
||
`openspec/specs/`. Оставь список пустым, если требования не меняются.
|
||
- **Impact**: Затронутые участки кода, API, зависимости и системы.
|
||
- **YouTrack**: После создания задачи укажи её ключ и URL.
|
||
|
||
ВАЖНО: раздел Capabilities задаёт связь между этапами proposal и specs.
|
||
Перед его заполнением изучи существующие спецификации: выполни
|
||
`openspec list --specs`, чтобы получить список capabilities проекта.
|
||
Для подходящих вариантов выполни `openspec show "<spec-id>" --type spec --json --no-scenarios`.
|
||
Команда вернёт назначение capability и тексты требований, не загружая
|
||
целые файлы спецификаций. Добавляй `--store "<id>"` к обеим командам
|
||
только для зарегистрированного отдельного хранилища и сохраняй
|
||
`--type spec`: если артефакт `change` и спецификация имеют одинаковое имя,
|
||
без этого параметра возникнет неоднозначность при выборе. Команда
|
||
`openspec list` без `--specs` показывает активные изменения (`changes`),
|
||
а не спецификации, поэтому не отражает уже описанное в проекте поведение.
|
||
Используй точный путь
|
||
существующей capability, не создавай похожее имя.
|
||
Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже
|
||
описано и что нужно изменить, прочитай каждую подходящую спецификацию
|
||
целиком, включая сценарии, командой `openspec show "<spec-id>" --type spec`
|
||
(с тем же правилом для `--store`). Для каждой перечисленной capability
|
||
потребуется соответствующий файл спецификации.
|
||
|
||
После подготовки содержательного первого варианта proposal создай для
|
||
каждого нового change, в том числе с `skip_specs: true`, ровно одну задачу
|
||
типа Task в YouTrack-проекте этого репозитория через подключённый YouTrack
|
||
MCP. Создай задачу до перехода к specs, design и tasks, используя причину,
|
||
scope и impact из proposal. Бери ключ проекта из `context` файла
|
||
`openspec/config.yaml`; в нём должна быть строка `YouTrack project key: <KEY>`.
|
||
Если строка отсутствует или ключ нельзя однозначно проверить через MCP,
|
||
уточни его у пользователя. Проект `Default` не используй как запасной
|
||
вариант. Перед созданием проверь схему обязательных полей проекта; не выдумывай значения.
|
||
Укажи slug change и краткую цель в задаче, затем
|
||
заполни в proposal раздел YouTrack ключом и URL задачи. Добавь work item с
|
||
фактически затраченным до этого временем на подготовку контекста change и
|
||
proposal.
|
||
|
||
При каждом последующем редактировании proposal пересмотри формулировки
|
||
заголовка и описания связанной YouTrack-задачи. Если причина, scope,
|
||
capabilities или impact изменились, обнови задачу через MCP так, чтобы они
|
||
соответствовали актуальному proposal; не создавай новую задачу. Если MCP
|
||
недоступен, сообщи об этом и уточни, как продолжить.
|
||
|
||
В каждом изменении (`change`) должна быть указана хотя бы одна новая или
|
||
изменяемая capability либо явный отказ от спецификаций: `openspec validate`
|
||
отклонит изменение без delta-спецификации, если в его `.openspec.yaml` не
|
||
задано `skip_specs: true`.
|
||
Используй `skip_specs: true` только когда поведение, описываемое
|
||
спецификациями, не меняется (например, при чистом рефакторинге, изменении
|
||
инструментов или документации). Не добавляй требование только ради
|
||
прохождения проверки.
|
||
|
||
Пиши кратко (1–2 страницы). Сосредоточься на причинах изменения, а не на
|
||
способе реализации: детали реализации относятся к design.md.
|
||
|
||
Этот документ задаёт основу: на нём строятся specs, design и tasks.
|
||
requires: []
|
||
|
||
- id: specs
|
||
generates: "specs/**/*.md"
|
||
description: Подробные спецификации изменения
|
||
template: spec.md
|
||
instruction: |
|
||
Пиши пояснительный текст спецификаций по-русски. Сохраняй обязательные
|
||
заголовки OpenSpec, идентификаторы, названия API и коды без перевода.
|
||
|
||
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
|
||
Правила ниже применяются к основным спецификациям и к полным блокам
|
||
ADDED/MODIFIED в delta-спецификациях. Это пользовательский формат без Gherkin.
|
||
|
||
Иерархия и границы:
|
||
- Capability описывает отдельную бизнес-функцию или понятный результат.
|
||
- Сохраняй полный иерархический путь, например domain/capability-name.
|
||
- Основная спецификация содержит раздел ## Границы между Purpose и
|
||
Requirements. Кратко укажи, за что отвечает capability, что входит в её
|
||
область и что находится за её пределами или относится к другой capability
|
||
либо приложению. Не дублируй Requirements и FR.
|
||
- Один Requirement описывает одну завершённую техническую функцию.
|
||
- Не дроби один процесс на Requirements для чтения, валидации и записи.
|
||
- Каждый Requirement имеет стабильный составной ID вида AREA.CAP-01 и ровно один Scenario.
|
||
- Префикс Requirement состоит из сокращений сегментов пути capability,
|
||
разделённых точками; его уникальность проверяется по ID в основных
|
||
спецификациях. Номер Requirement уникален внутри capability. Существующие
|
||
унаследованные Requirements могут сохранять прежние ID.
|
||
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
|
||
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
|
||
- В Requirements и FR включай только сведения, меняющие наблюдаемое
|
||
поведение, устойчивый контракт или обязательное техническое ограничение.
|
||
Удаляй повторы, пояснения и формулировки, которые не меняют поведение и
|
||
не снимают неоднозначность контракта. В ## Границы оставляй краткие
|
||
сведения об ответственности и владении, необходимые для понимания
|
||
области capability, даже если они сами по себе не задают поведение.
|
||
|
||
Scenario:
|
||
- Поддерживаются два формата сценария использования: полный и
|
||
сокращённый. Автор выбирает формат по ситуации, независимо от типа FR
|
||
и описываемой части системы: процесса выполнения, БД, API, UI и других.
|
||
- Полный сценарий использования содержит разделы Участники, Предусловия,
|
||
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
||
в таком порядке.
|
||
- Сокращённый сценарий использования содержит только раздел `##### Основной поток`;
|
||
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит
|
||
участников, предусловий, альтернатив и ошибок, результата или кодов
|
||
завершения и не задаёт отдельные ветвления во время выполнения.
|
||
- В обычном сценарии Назначение опционально; добавляй только если оно
|
||
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
|
||
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
|
||
- Шаг сценария выполнения может назвать действие, конечную точку API или
|
||
способ записи и сослаться на FR.
|
||
- Каждую конечную точку HTTP описывай в отдельном Requirement с полным
|
||
сценарием использования.
|
||
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
|
||
- Основной поток и альтернативы обычного сценария включают коды
|
||
завершения, если они определены для этой функции.
|
||
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
|
||
сообщений и дальнейшая логика располагаются за пределами Scenario.
|
||
- Единственная таблица Scenario — Коды завершения с колонками
|
||
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
|
||
- Код сам сообщает смысл итога; дополнительный этап или свободный текст
|
||
не должен требоваться для понимания кода. События промежуточных шагов
|
||
не являются кодами завершения. Не создавай код для каждой диагностики.
|
||
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
|
||
логику, текст или применимые правила результата.
|
||
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
|
||
содержательного текста без адресов Markdown-ссылок.
|
||
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
|
||
|
||
Функциональные требования:
|
||
- После Scenario, на уровне ####, идёт раздел Функциональные требования.
|
||
- Внутри: ##### AREA.CAP-01.FR-01: <название>, ##### AREA.CAP-01.FR-02 [DB]: <название>, ##### AREA.CAP-01.FR-03 [API]: <название> и так далее.
|
||
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN.
|
||
Номер начинается с FR-01 в каждом Requirement.
|
||
- FR содержит отдельное понятное правило или связанный контракт; не дроби
|
||
связную логику на множество атомарных FR.
|
||
- Обычный FR без метки описывает логику, правила или последовательность
|
||
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API]
|
||
или [UI]; метка не входит в ID и не меняет slug ссылки.
|
||
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
|
||
контракт сообщения или технического лога. Контракт конечной точки HTTP
|
||
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
|
||
UI; детальный паттерн будет добавлен отдельно.
|
||
- Для FR [DB] с таблицей БД следуй паттерну
|
||
`openspec/schemas/use-case-driven/patterns/database-table.md`.
|
||
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну
|
||
`openspec/schemas/use-case-driven/patterns/message-contract.md`.
|
||
- Контракт конечной точки HTTP не оформляй отдельными FR. После раздела
|
||
Функциональные требования добавляй завершающий раздел CONTRACT с
|
||
подразделами Request и Response в таком порядке. В Request указывай
|
||
один HTTP-метод и путь; для отсутствующего тела явно отмечай это.
|
||
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md.
|
||
- В таблице Response раздела CONTRACT укажи для каждого поля источник
|
||
значения или правило его формирования в последней колонке.
|
||
- В таблице ответа контракта FR [API] укажи для каждого поля источник
|
||
значения или правило его формирования в колонке «Формирование значения».
|
||
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует
|
||
якоря из заголовков Requirement и FR.
|
||
- Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его
|
||
заголовка, например
|
||
[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID
|
||
используется и для ссылки внутри Requirement, и для ссылки на другой
|
||
Requirement.
|
||
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
|
||
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
|
||
новые FR добавляй в конец. Порядок первого документа последовательный.
|
||
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
|
||
сообщения/действия, если это часть контракта. Параметры сообщений
|
||
являются данными, а не скрытым значением кода.
|
||
- Если смысловой код спецификации отличается от текущего поведения системы,
|
||
явно опиши соответствие и статус реализации в FR. Не утверждай,
|
||
что новый код или текст уже возвращается приложением.
|
||
|
||
Работа с OpenSpec:
|
||
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
|
||
- Основная спецификация следует краткой схеме templates/main-spec.md; это формат-
|
||
ориентир, а не генерируемый артефакт. Сохраняй в ней Purpose, ## Границы
|
||
и полный актуальный набор Requirements.
|
||
- Delta-спецификация использует templates/spec.md и разделы ## ADDED Requirements,
|
||
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
|
||
- Для новой capability delta-спецификация начинается с ## Purpose
|
||
(не менее 50 знаков). Для существующей capability Purpose в delta не добавляй.
|
||
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR.
|
||
Его заголовок должен совпадать с заголовком соответствующего Requirement
|
||
в основной спецификации.
|
||
- В REMOVED укажи Reason и Migration; в RENAMED — FROM и TO.
|
||
Это операции над требованиями, не сценарии технических функций.
|
||
- При копировании блоков в delta сохраняй ID Requirements, номера и
|
||
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в
|
||
неизменённый Requirement основной спецификации, проверяй delta с
|
||
`--base <master-spec>`.
|
||
- Не создавай delta для чистого форматирования, изменений инструментов
|
||
или рефакторинга. Для изменения без изменения поведения используй
|
||
`skip_specs: true`.
|
||
- Проверь schema через openspec schema validate use-case-driven.
|
||
- Проверь spec через openspec validate и отдельно через
|
||
python3 openspec/schemas/use-case-driven/validate_format.py
|
||
--require-qualified-ids <spec-path>. Для неизменённых спецификаций
|
||
со старыми ID этот флаг не нужен.
|
||
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
|
||
requires:
|
||
- proposal
|
||
|
||
- id: design
|
||
generates: design.md
|
||
description: Техническое описание решения и деталей реализации
|
||
template: design.md
|
||
instruction: |
|
||
Пиши пояснительный текст по-русски. Сохраняй обязательные заголовки
|
||
OpenSpec и технические идентификаторы, названия файлов, инструментов
|
||
и команд без перевода.
|
||
|
||
Создай документ design, объясняющий, КАК реализовать изменение.
|
||
|
||
Когда добавлять design.md (достаточно любого из условий):
|
||
- Изменение затрагивает несколько сервисов или модулей либо вводит новый
|
||
архитектурный подход.
|
||
- Добавляется внешняя зависимость или существенно меняется модель данных.
|
||
- Есть сложность, связанная с безопасностью, производительностью или
|
||
миграцией.
|
||
- До начала разработки нужно принять технические решения, чтобы устранить
|
||
неоднозначность.
|
||
|
||
Разделы:
|
||
- **Context**: Только текущее состояние и ограничения, необходимые для
|
||
объяснения подхода. Причины изменения смотри в proposal, не повторяй их
|
||
(например: «См. proposal.md — Why»).
|
||
- **Goals / Non-Goals**: Что это решение обеспечивает и что явно исключает.
|
||
Не повторяй область работ из proposal; указывай только границы решения.
|
||
- **Decisions**: Ключевые технические решения и их обоснование: почему
|
||
выбран один вариант вместо другого. Укажи рассмотренные альтернативы.
|
||
- **Risks / Trade-offs**: Известные ограничения и возможные проблемы.
|
||
Формат: [Риск] → [Меры снижения].
|
||
- **Migration Plan**: Шаги развёртывания и стратегия отката, если применимо.
|
||
- **Open Questions**: Неизвестные, которые можно безопасно выяснить позже,
|
||
не меняя спецификации, подход или состав задач. Не добавляй, если таких
|
||
вопросов нет.
|
||
|
||
Открытые вопросы предназначены для действительно отложенных решений, а не
|
||
для пропущенных решений. Если ответ может изменить спецификации, выбранный
|
||
подход или состав задач, выясни его сейчас: спроси пользователя, а не
|
||
делай предположение.
|
||
|
||
Сосредоточься на архитектуре и подходе, а не на пошаговом описании кода.
|
||
В proposal описаны причины и состав изменения, в design — способ
|
||
реализации. Ссылайся на proposal для обоснования и на specs для требований;
|
||
если раздел только повторяет их, дай ссылку вместо повтора.
|
||
|
||
Ссылайся на Requirement ID и локальные FR; описывай решения реализации
|
||
без копирования требований.
|
||
|
||
Перед проектированием прочитай применимые принятые ADR из
|
||
`openspec/context/adr/` и укажи их идентификаторы в Decisions. Если
|
||
изменение принимает долгосрочное архитектурное решение или заменяет
|
||
принятое решение, запланируй создание нового ADR по шаблону
|
||
`openspec/schemas/use-case-driven/templates/adr.md` со статусом Proposed.
|
||
Не помечай ADR принятым самостоятельно. Если запрос противоречит
|
||
действующему ADR, явно опиши конфликт и запроси решение пользователя до
|
||
выбора расходящегося подхода.
|
||
|
||
Хороший design объясняет причины технических решений.
|
||
requires:
|
||
- proposal
|
||
|
||
- id: tasks
|
||
generates: tasks.md
|
||
description: Контрольный список задач с отслеживаемым выполнением
|
||
template: tasks.md
|
||
instruction: |
|
||
Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные
|
||
идентификаторы, пути файлов, названия API, коды и команды без перевода.
|
||
|
||
Создай список задач, разбивающий работу по реализации на части.
|
||
|
||
Перед составлением задач проверь Open Questions в design.md. Если ответ на
|
||
какой-либо вопрос повлияет на результат разработки, сначала обсуди его с
|
||
пользователем; не закладывай в список задач неоговорённые предположения.
|
||
|
||
**ВАЖНО: точно следуй шаблону ниже.** Этап apply отслеживает выполнение по
|
||
формату чекбоксов. Чекбокс, содержащий только `x`, считается выполненным
|
||
независимо от регистра и пробелов; например, `- [ x]` тоже означает
|
||
выполнение. Любая другая отметка, включая `- [~]`, `- [-]` и пустой `- []`,
|
||
считается незавершённой. Строки без чекбокса вообще не отслеживаются.
|
||
|
||
Правила:
|
||
- Группируй связанные задачи под нумерованными заголовками `##`.
|
||
- Каждая задача должна быть чекбоксом формата `- [ ] X.Y <описание задачи>`.
|
||
- Разбивай задачи так, чтобы каждую можно было выполнить за одну сессию.
|
||
- Располагай задачи в порядке зависимостей: сначала то, что нужно сделать
|
||
раньше.
|
||
- Для каждой задачи укажи способ проверки выполнения: тест, команду,
|
||
наблюдаемое поведение или готовый артефакт. Добавь проверку в описание
|
||
чекбокса. Выноси проверку в отдельную задачу только для интеграционных
|
||
или системных сценариев, охватывающих несколько задач реализации.
|
||
|
||
Пример:
|
||
```
|
||
# Tasks
|
||
|
||
## 1. Подготовка
|
||
|
||
- [ ] 1.1 Создать структуру модулей и проверить наличие ожидаемых файлов
|
||
- [ ] 1.2 Добавить необходимые зависимости и проверить успешность установки
|
||
|
||
## 2. Основная реализация
|
||
|
||
- [ ] 2.1 Реализовать экспорт данных и проверить прохождение теста экспорта
|
||
- [ ] 2.2 Добавить форматирование CSV и проверить обработку кавычек и разделителей модульными тестами
|
||
```
|
||
|
||
Сверяйся со specs, чтобы определить, что нужно создать, и с design — как это
|
||
реализовать.
|
||
|
||
Связывай задачи с Requirement ID, FR и кодами завершения, если задача
|
||
затрагивает эти результаты.
|
||
|
||
YouTrack-задача из proposal сопровождает весь change и не заменяет
|
||
чекбоксы реализации в tasks.md. На всех этапах change — от подготовки
|
||
proposal до реализации — записывай в YouTrack фактически затраченное время
|
||
отдельными work items через MCP, без дублирования уже внесённого времени.
|
||
Выбирай только тип работы, поддерживаемый проектом.
|
||
|
||
Если в design предусмотрен новый или заменяющий ADR, включи в tasks
|
||
отдельную задачу на его создание в `openspec/context/adr/` со статусом
|
||
Proposed. При замене принятого решения свяжи новый и прежний ADR через
|
||
поля `supersedes` и `superseded-by`.
|
||
requires:
|
||
- specs
|
||
- design
|
||
|
||
apply:
|
||
requires: [ tasks ]
|
||
tracks: tasks.md
|
||
instruction: |
|
||
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
|
||
выполненными по мере работы. Остановись, если столкнёшься с препятствием или
|
||
потребуется уточнение. Для change с задачей YouTrack записывай фактически
|
||
затраченное во время apply время в её work items через MCP; перед
|
||
архивированием проверь, что учтено всё время работы над change. После
|
||
успешного `openspec archive`
|
||
переведи задачу в конечный статус, предусмотренный проектом YouTrack,
|
||
используя доступную схему полей и значений. Не подставляй предполагаемое
|
||
название статуса. Считай change завершённым только после успешного
|
||
архивирования и закрытия YouTrack-задачи.
|