Files
alex d46993a092
PLBA package CI / Python tests (push) Successful in 23s
PLBA package CI / Package version increment (push) Skipped
PLBA2-4. Доработка регистрации http эндпоинтов
2026-10-11 10:44:59 +03:00

352 lines
31 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, файлов,
инструментов, команд и коды без перевода.
Создай документ предложения, объясняющий, ПОЧЕМУ требуется это изменение.
Разделы:
- **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, зависимости и системы.
ВАЖНО: раздел 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
потребуется соответствующий файл спецификации.
В каждом изменении (`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 и кодами завершения, если задача
затрагивает эти результаты.
Если в design предусмотрен новый или заменяющий ADR, включи в tasks
отдельную задачу на его создание в `openspec/context/adr/` со статусом
Proposed. При замене принятого решения свяжи новый и прежний ADR через
поля `supersedes` и `superseded-by`.
requires:
- specs
- design
apply:
requires: [ tasks ]
tracks: tasks.md
instruction: |
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
выполненными по мере работы. Остановись, если столкнёшься с препятствием или
потребуется уточнение.