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//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 "" --type spec --json --no-scenarios`. Команда вернёт назначение capability и тексты требований, не загружая целые файлы спецификаций. Добавляй `--store ""` к обеим командам только для зарегистрированного отдельного хранилища и сохраняй `--type spec`: если артефакт `change` и спецификация имеют одинаковое имя, без этого параметра возникнет неоднозначность при выборе. Команда `openspec list` без `--specs` показывает активные изменения (`changes`), а не спецификации, поэтому не отражает уже описанное в проекте поведение. Используй точный путь существующей capability, не создавай похожее имя. Отфильтрованный вывод даёт только обзор. Прежде чем решать, что уже описано и что нужно изменить, прочитай каждую подходящую спецификацию целиком, включая сценарии, командой `openspec show "" --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 и локальный номер: .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-якоря вида . Markdown генерирует якоря из заголовков Requirement и FR. - Ссылайся на FR по полному ID и фрагменту ссылки, сформированному из его заголовка, например [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки). Полный ID используется и для ссылки внутри Requirement, и для ссылки на другой Requirement. - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. - Сохраняй существующие ID. При изменении FR сохраняй его номер; новые FR добавляй в конец. Порядок первого документа последовательный. - Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие сообщения/действия, если это часть контракта. Параметры сообщений являются данными, а не скрытым значением кода. - Если смысловой код спецификации отличается от текущего поведения системы, явно опиши соответствие и статус реализации в FR. Не утверждай, что новый код или текст уже возвращается приложением. Работа с OpenSpec: - Создай specs//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 `. - Не создавай 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 . Для неизменённых спецификаций со старыми 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; описывай решения реализации без копирования требований. Хороший 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 и кодами завершения, если задача затрагивает эти результаты. requires: - specs - design apply: requires: [ tasks ] tracks: tasks.md instruction: | Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их выполненными по мере работы. Остановись, если столкнёшься с препятствием или потребуется уточнение.