diff --git a/openspec/config.yaml b/openspec/config.yaml index 95d1b50..3632647 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,43 +1,7 @@ -schema: function-driven - -context: | - Актуальные спецификации проекта находятся в openspec/specs/. - Старые документы spec/specs/ устарели и не подтверждают текущее поведение. - Capability имеет отдельную бизнес-функцию или понятный результат и живёт - в иерархии доменов, например orders/snapshot-sync. - Requirement описывает одну завершённую техническую функцию. - Формат требований определяется локальной схемой function-driven. - Включай только сведения, влияющие на наблюдаемое поведение, устойчивый - контракт или обязательное техническое ограничение; не добавляй повторы и - пояснительный текст без такого влияния. - Пиши по-русски весь пояснительный текст каждого изменения OpenSpec: - в proposal.md, design.md, specs/**/*.md и tasks.md. Сохраняй обязательные - заголовки и синтаксис OpenSpec, имена API, SQL-полей, кодов, файлов, - инструментов, команд и идентификаторы без перевода. +schema: use-case-driven rules: - specs: - - Пиши пояснительный текст спецификаций по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. - - Каждый Requirement содержит ровно один Use case. Автор выбирает полный или сокращенный формат независимо от типа FR и предмета описания. - - Обычный FR без метки описывает логику, правила или последовательность шагов; специальные типы помечай в заголовке FR как [DB], [API] или [UI]. - - FR [DB] с таблицей БД оформляй по openspec/schemas/function-driven/patterns/database-table.md. - - Каждый HTTP endpoint описывай отдельным Requirement с полным Use case; сложные шаги выноси в FR и связывай со сценарием. - - Контракт endpoint помещай после FR в завершающий CONTRACT с подразделами Request и Response; не создавай для request/response отдельные FR. - - Таблицы тела запроса и ответа в CONTRACT оформляй по openspec/schemas/function-driven/patterns/message-contract.md; для каждого поля Response указывай источник или правило формирования значения. - - Сериализуемые контракты сообщений и технических логов описывай в FR [API] по openspec/schemas/function-driven/patterns/message-contract.md; один FR описывает одно направление. - - Детали находятся в локально нумерованных FR за пределами Scenario; шаги ссылаются на FR. - - Коды завершения сами передают смысл результата и связаны с FR о текстах и дальнейшем поведении. - - Для master spec используй templates/main-spec.md выбранной схемы; для delta используй templates/spec.md. - - Проверяй формат командой python3 openspec/schemas/function-driven/validate_format.py . - proposal: - - Сохраняй полные иерархические пути capabilities. - - Пиши пояснительный текст proposal по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. - design: - - Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований. - - Пиши пояснительный текст design по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. tasks: - - Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. - - Пиши названия групп и формулировки задач по-русски; сохраняй команды, пути, API, коды и идентификаторы без перевода. - - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в pyproject.toml. Выполняй её после реализации и проверок; один change повышает версию ровно один раз. - - До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и любых изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. + - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в `pyproject.toml`; один change повышает версию ровно один раз. + - До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. - Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта. diff --git a/openspec/schemas/function-driven/capability-codes.md b/openspec/schemas/function-driven/capability-codes.md deleted file mode 100644 index 14c0c2f..0000000 --- a/openspec/schemas/function-driven/capability-codes.md +++ /dev/null @@ -1,19 +0,0 @@ -# Коды capabilities - -Каждому пути capability соответствует один стабильный короткий префикс. Полные -префиксы должны быть уникальны в проекте; при переименовании capability код не -переиспользуется для другой capability. - -| Путь capability | Префикс Requirement | -| --- | --- | -| `configuration/application-settings` | `CFG.AS` | -| `configuration/application-config-file` | `CFG.ACF` | -| `health/aggregation` | `HL.AG` | -| `api/http/control-api` | `API.HTTP.CA` | -| `runtime/application-lifecycle` | `RT.AL` | -| `runtime/application-identity` | `RT.AI` | -| `runtime/worker` | `RT.WK` | -| `workflow/orchestration` | `WF.OR` | -| `observability/business-tracing` | `OBS.BT` | -| `observability/technical-logging` | `OBS.TL` | - diff --git a/openspec/schemas/function-driven/schema.yaml b/openspec/schemas/function-driven/schema.yaml deleted file mode 100644 index b5c88d5..0000000 --- a/openspec/schemas/function-driven/schema.yaml +++ /dev/null @@ -1,281 +0,0 @@ -name: function-driven -version: 1 -description: Иерархические capabilities, завершённые технические функции и краткие use cases с локальными FR -artifacts: - - id: proposal - generates: proposal.md - description: Initial proposal document outlining the change - template: proposal.md - instruction: | - Пиши весь пояснительный текст артефакта изменения по-русски. Сохраняй - обязательные заголовки OpenSpec и технические идентификаторы, названия - API, файлов, инструментов, команд и коды без перевода. - - Create the proposal document that establishes WHY this change is needed. - - Sections: - - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now? - - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**. - - **Capabilities**: Identify which specs will be created or modified: - - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs//spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization. - - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes. - - **Impact**: Affected code, APIs, dependencies, or systems. - - IMPORTANT: The Capabilities section is critical. It creates the contract between - proposal and specs phases. Research existing specs before filling this in: - run `openspec list --specs` for the project's capability inventory, then - `openspec show "" --type spec --json --no-scenarios` for any that - look related - that returns a capability's purpose and requirement texts - without pulling whole spec files into context. Append `--store ""` to - both commands only for a registered standalone store, and keep `--type - spec`: a change and a spec sharing a name is otherwise an ambiguous-item - error. `openspec list` without `--specs` lists in-flight changes, not - specs - it never shows what the project already covers. Reuse an existing - capability's exact path instead of introducing a near-duplicate name. - The filtered read is only an overview. Before deciding what is already - covered or what should change, read each relevant spec in full, including - scenarios, with `openspec show "" --type spec` (same `--store` rule). - Each capability listed here will need a corresponding spec file. - - Every change must either declare at least one capability (new or - modified) or explicitly opt out of specs: `openspec validate` rejects a - change with zero deltas unless the change's `.openspec.yaml` sets - `skip_specs: true`. Use `skip_specs: true` only when no spec-level - behavior changes (pure refactor, tooling, docs) - specs describe - behavior, so if behavior does not change, no spec should change either. - Do not invent a requirement just to satisfy validation. - - Keep it concise (1-2 pages). Focus on the "why" not the "how" - - implementation details belong in design.md. - - This is the foundation - specs, design, and tasks all build on this. - requires: [] - - - id: specs - generates: "specs/**/*.md" - description: Detailed specifications for the change - template: spec.md - instruction: | - Пиши весь пояснительный текст спецификаций по-русски. Сохраняй - обязательные заголовки OpenSpec, идентификаторы, названия API и коды - без перевода. - - Создай спецификации наблюдаемого поведения и устойчивых контрактов. - Правила ниже применяются к master specs и к полным блокам ADDED/MODIFIED - в delta specs. Это пользовательский формат без Gherkin. - - Иерархия и границы: - - Capability имеет отдельную бизнес-функцию или понятный результат. - - Сохраняй полный иерархический путь, например orders/snapshot-sync. - - Один Requirement описывает одну завершённую техническую функцию. - - Не дроби один процесс на Requirements для чтения, валидации и записи. - - Каждый Requirement имеет стабильный ID вида CFG.AS-01 и ровно один Scenario. - - Префикс Requirement уникален для пути capability и регистрируется в - capability-codes.md: configuration/application-settings получает CFG.AS. - Номер Requirement уникален внутри capability, что делает полный ID - уникальным в проекте. Существующие, ещё не рефакторенные Requirements - могут сохранять старый ID. - - Заголовки OpenSpec: ### Requirement: и #### Scenario:. - - Описание Requirement содержит SHALL/MUST и наблюдаемый результат. - - Включай только сведения, меняющие наблюдаемое поведение, устойчивый - контракт или обязательное техническое ограничение. Удаляй повторы, - пояснения и формулировки, которые не меняют поведение и не снимают - неоднозначность контракта. - - Scenario: - - Поддерживаются два формата Use case: полный и сокращенный. Автор - выбирает формат по ситуации, независимо от типа FR и того, что - описывается: runtime-процесс, БД, API, UI или другая часть системы. - - Полный Use case содержит разделы Участники, Предусловия, - Основной поток, Альтернативы и ошибки, Результат, Коды завершения — - в таком порядке. - - Сокращенный Use case содержит только раздел `##### Основной поток`; - каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит - участников, предусловий, альтернатив и ошибок, результата или кодов - завершения и не задаёт отдельные runtime-развилки. - - В обычном сценарии Назначение опционально; добавляй только если оно - сообщает сведения, которых нет в заголовке. Контекст отсутствует. - - Основной поток — нумерованные короткие шаги «Что делаем — как делаем». - - Шаг runtime-сценария может назвать действие, endpoint или способ записи - и сослаться на FR. - - Каждый HTTP endpoint описывай в отдельном Requirement с полным Use case. - Сложные правила шага выноси в FR и связывай со сценарием ссылками. - - Основной поток и альтернативы обычного сценария включают коды - завершения, если они определены для этой функции. - - Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты - сообщений и дальнейшая логика располагаются за пределами Scenario. - - Единственная таблица Scenario — Коды завершения с колонками - Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE. - - Код сам сообщает смысл итога; дополнительный stage или свободный текст - не должен требоваться для понимания кода. События промежуточных шагов - не являются кодами завершения. Не создавай код для каждой диагностики. - - Каждая запись кода ссылается на локальные FR, определяющие дальнейшую - логику, текст или применимые правила результата. - - Каждый шаг, альтернатива и абзац сценария — не более 240 знаков - содержательного текста без адресов Markdown-ссылок. - - Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT. - - Функциональные требования: - - После Scenario, на уровне ####, идёт раздел Функциональные требования. - - Внутри: ##### CFG.AS-01.FR-01: <название>, ##### CFG.AS-01.FR-02 [DB]: <название>, ##### CFG.AS-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 endpoint - размещается в отдельном разделе CONTRACT. [UI] описывает требования к - UI; детальный паттерн будет добавлен отдельно. - - Для FR [DB] с таблицей БД следуй паттерну - `openspec/schemas/function-driven/patterns/database-table.md`. - - Для сериализуемого контракта сообщения в FR [API] следуй паттерну - `openspec/schemas/function-driven/patterns/message-contract.md`. - - Контракт HTTP endpoint не оформляй отдельными FR. После раздела - Функциональные требования добавляй завершающий раздел CONTRACT с - подразделами Request и Response в таком порядке. В Request указывай - один HTTP-метод и путь; для отсутствующего тела явно отмечай это. - Таблицы тела запроса и ответа оформляй по паттерну message-contract.md. - - В таблице Response раздела CONTRACT укажи для каждого поля источник - значения или правило его формирования в последней колонке. - - В таблице response-контракта FR [API] укажи для каждого поля источник - значения или правило его формирования в колонке «Формирование значения». - - Не добавляй HTML-якоря вида . Markdown генерирует - якоря из заголовков Requirement и FR. - - Ссылайся на FR по полному ID и slug его заголовка, например - [CFG.AS-01.FR-01](#cfgas-01fr-01-правило-обработки). Полный ID - используется и для ссылки внутри Requirement, и для ссылки на другой - Requirement. - - Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки. - - Сохраняй существующие ID. При изменении FR сохраняй его номер; - новые FR добавляй в конец. Порядок первого документа последовательный. - - Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие - сообщения/действия, если это часть контракта. Параметры сообщений - являются данными, а не скрытым значением кода. - - Если смысловой код спецификации отличается от действующего runtime, - явно опиши соответствие и статус реализации в FR. Не утверждай, - что новый код или текст уже возвращается приложением. - - Работа с OpenSpec: - - Создай specs//spec.md для каждой capability из proposal. - - Master spec использует шаблон templates/main-spec.md этой схемы. - - Delta spec использует templates/spec.md и разделы ## ADDED Requirements, - ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements. - - Для новой capability delta начинается с ## Purpose (50+ знаков). - Для существующей capability Purpose в delta не добавляй. - - MODIFIED содержит полный Requirement: ID, один Scenario и все FR. - Его заголовок должен совпадать с заголовком master spec. - - REMOVED содержит Reason и Migration; RENAMED использует FROM/TO. - Это операции над требованиями, не сценарии технических функций. - - При копировании блоков в delta сохраняй ID Requirements, номера и - заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в - неизменённый Requirement master spec, проверяй delta с --base . - - Не создавай delta для чистого форматирования, tooling или рефакторинга. - Для change без изменения поведения используй skip_specs: true. - - Проверь schema через openspec schema validate function-driven. - - Проверь spec через openspec validate и отдельно через - python3 openspec/schemas/function-driven/validate_format.py - --require-qualified-ids . Для неизменённых legacy specs - этот флаг не нужен. - Стандартный валидатор OpenSpec не проверяет все правила этого формата. - requires: - - proposal - - - id: design - generates: design.md - description: Technical design document with implementation details - template: design.md - instruction: | - Пиши весь пояснительный текст design по-русски. Сохраняй обязательные - заголовки OpenSpec и технические идентификаторы, названия файлов, - инструментов и команд без перевода. - - Create the design document that explains HOW to implement the change. - - When to include design.md (create only if any apply): - - Cross-cutting change (multiple services/modules) or new architectural pattern - - New external dependency or significant data model changes - - Security, performance, or migration complexity - - Ambiguity that benefits from technical decisions before coding - - Sections: - - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why"). - - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries. - - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision. - - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation - - **Migration Plan**: Steps to deploy, rollback strategy (if applicable) - - **Open Questions**: Unknowns that can safely be answered later without - changing the specs, the approach, or the task breakdown. Omit if none. - - Open questions are for genuinely deferrable unknowns, not decisions you - skipped. If a question would change the specs, the chosen approach, or - the task breakdown, resolve it now - ask the user instead of guessing. - - Focus on architecture and approach, not line-by-line implementation. - The proposal covers why and what; design covers how. Reference the - proposal for motivation and, once written, the specs for requirements - - if a section would only restate them, point to them instead. - - Good design docs explain the "why" behind technical decisions. - requires: - - proposal - - - id: tasks - generates: tasks.md - description: Implementation checklist with trackable tasks - template: tasks.md - instruction: | - Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные - идентификаторы, пути файлов, названия API, коды и команды без перевода. - - Create the task list that breaks down the implementation work. - - Before writing tasks, check design.md for Open Questions. If any of them - would change what gets built, resolve them with the user first - do not - bake an unstated assumption into the task list. - - **IMPORTANT: Follow the template below exactly.** The apply phase parses - checkbox format to track progress. A box holding only `x` counts as done, - upper or lower case and with any spacing, so `- [ x]` is done too. Every - other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as - unfinished. A line with no checkbox is not tracked at all. - - Guidelines: - - Group related tasks under ## numbered headings - - Each task MUST be a checkbox: `- [ ] X.Y Task description` - - Tasks should be small enough to complete in one session - - Order tasks by dependency (what must be done first?) - - Each task MUST state how to verify completion (a test, command, - observable behavior, or delivered artifact). Put the verification in - that task's checkbox description. Use a separate verification task only - when it checks broader integration or system behavior that spans - multiple implementation tasks. - - Example: - ``` - # Tasks - - ## 1. Setup - - - [ ] 1.1 Create new module structure and verify expected files are present - - [ ] 1.2 Add dependencies to package.json and verify package installation succeeds - - ## 2. Core Implementation - - - [ ] 2.1 Implement data export function and verify the export test passes - - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters - ``` - - Reference specs for what needs to be built, design for how to build it. - requires: - - specs - - design - -apply: - requires: [ tasks ] - tracks: tasks.md - instruction: | - Read context files, work through pending tasks, mark complete as you go. - Pause if you hit blockers or need clarification. diff --git a/openspec/schemas/function-driven/templates/main-spec.md b/openspec/schemas/function-driven/templates/main-spec.md deleted file mode 100644 index 7dd2f81..0000000 --- a/openspec/schemas/function-driven/templates/main-spec.md +++ /dev/null @@ -1,106 +0,0 @@ -# Capability: <название> - -## Purpose - -<Бизнес-функция capability и понятный результат, не менее 50 знаков.> - - - -## Границы - -- <область ответственности capability>. - -## Requirements - -### Requirement: <название завершённой технической функции> - -**ID:** `AREA.CAP-01` - -Система SHALL <наблюдаемый результат завершённой функции>. - -#### Scenario: <название завершённого процесса> - -##### Участники - -- <участники процесса>. - -##### Предусловия - -- <условия начала процесса>. - -##### Основной поток - -1. <Что делаем — как делаем> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-или-устойчивый-контракт). -2. Завершаем с `FUNCTION_COMPLETED` — фиксируем результат по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение). - -##### Альтернативы и ошибки - -- <условие ошибки> — завершаем с `FUNCTION_FAILED` по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение). - -##### Результат - -<Наблюдаемое состояние после завершения>. - -##### Коды завершения - -| Код | Смысл | Связанные FR | -| --- | --- | --- | -| `FUNCTION_COMPLETED` | <самодостаточный смысл успешного завершения> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) | -| `FUNCTION_FAILED` | <самодостаточный смысл ошибки> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) | - -#### Функциональные требования - -##### AREA.CAP-01.FR-01: Правило обработки - -<Обычный FR описывает логику, правило или последовательность шагов. Для -специального формата добавь метку после ID: [DB], [API] или [UI]. Структуру -таблицы БД и контракт сообщения оформи по соответствующему паттерну. Контракт -HTTP endpoint располагай в завершающем разделе CONTRACT.> - -##### AREA.CAP-01.FR-02: Коды завершения, тексты и дальнейшее поведение - -| Код | Текст сообщения | Дальнейшее поведение | -| --- | --- | --- | -| `FUNCTION_COMPLETED` | <текст или явное отсутствие сообщения> | <следующие действия> | -| `FUNCTION_FAILED` | <текст ошибки> | <обработка ошибки, повтор, действие оператора> | - -<При необходимости — параметры сообщений, связанные требования и соответствие -действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.> - - - - - - diff --git a/openspec/schemas/function-driven/README.md b/openspec/schemas/use-case-driven/README.md similarity index 75% rename from openspec/schemas/function-driven/README.md rename to openspec/schemas/use-case-driven/README.md index f33b9fd..207cd1c 100644 --- a/openspec/schemas/function-driven/README.md +++ b/openspec/schemas/use-case-driven/README.md @@ -1,30 +1,36 @@ -# Схема function-driven +# Схема use-case-driven -Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на -`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`. -Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes -с явно указанной `schema: spec-driven` продолжают использовать свою схему; -их миграция не является частью изменения формата master spec. +`use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на +`spec-driven`. Она задаёт workflow `proposal → specs / design → tasks`; +формат требований определён в `schema.yaml` и шаблонах. Существующие changes +с явно указанной `schema: spec-driven` продолжают использовать свою схему. ## Уровни спецификации - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. +- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности. - Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. - Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. - FR — подробные правила и контракты сообщений за пределами Scenario; контракт HTTP endpoint размещается в завершающем CONTRACT. -В спецификацию включаются только сведения, влияющие на наблюдаемое поведение, -устойчивый контракт или обязательное техническое ограничение. Повторы и -пояснения без такого влияния удаляются. +Requirements и FR включают только сведения, влияющие на наблюдаемое поведение, +устойчивый контракт или обязательное техническое ограничение. Раздел «Границы» +кратко фиксирует ответственность и владение capability, не повторяя Requirements. +Повторы и пояснения без такого влияния удаляются. -Для каждой capability зарегистрируй стабильный уникальный префикс в -[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь -capability: например, `configuration/application-settings` получает `CFG.AS`. -ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability. -В сочетании с уникальным префиксом это даёт уникальный ID в проекте. -ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`, -`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. +Составной префикс Requirement строится из сокращений сегментов пути capability: +для однословного сегмента используй первые три буквы, для сегмента с дефисами — +первые буквы его частей. Приводи сокращения к верхнему регистру. Например, +`domain/capability-name` получает `DOM.CN`. Если префикс уже занят, удлиняй +сокращения новых сегментов до уникальности; ранее назначенные префиксы не меняй. +Сохраняй префикс при переименовании capability. Валидатор проверяет уникальность +по ID в master specs и активных changes; отдельный реестр кодов не ведётся. + +ID Requirement имеет вид `AREA.CAP-01`; его номер уникален внутри capability. +Полный ID уникален в проекте благодаря уникальному префиксу и номеру. +ID FR включает ID Requirement и локальный номер: `AREA.CAP-01.FR-01`, +`AREA.CAP-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. В новых и изменяемых Requirements используй составные ID. Неизменённые legacy specs могут сохранять прежние ID до отдельного рефакторинга. @@ -58,7 +64,7 @@ Markdown-рендерер автоматически создаёт якоря В Scenario «Назначение» опционально и добавляется только при наличии сведений, которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток — нумерованные короткие шаги «Что делаем — как делаем», например: -«Получаем клиентов — вызываем GET /cp/users по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)». +«Получаем данные — вызываем GET /api/resources по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)». ## Форматы Use case @@ -124,12 +130,17 @@ FR, описывающий таблицу БД, оформляется по В response-таблице также указывается источник или правило формирования каждого поля. Другие паттерны добавляются отдельными файлами по мере появления потребности. -## Шаблоны и delta specs +## Форматы master и delta specs -- `templates/main-spec.md` — постоянная спецификация capability. -- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`. +- `templates/main-spec.md` — краткая схема постоянной master spec: Purpose, Границы и Requirements; это не артефакт change. +- `templates/spec.md` — полный шаблон delta для change, предоставляемый `openspec instructions specs`. - `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow. +В master spec раздел `## Границы` располагается между Purpose и Requirements. +Он описывает ответственность capability, её включённую область и явные +исключения или передачу ответственности другим capabilities и приложению. +В delta spec этот раздел не повторяется: delta меняет отдельные Requirements. + ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration, RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и @@ -143,9 +154,9 @@ Scenario в таких операциях не создаётся. В delta со ## Проверки ```sh -openspec schema validate function-driven -openspec validate orders/snapshot-sync --type spec --strict --no-interactive -python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md +openspec schema validate use-case-driven +openspec validate domain/capability-name --type spec --strict --no-interactive +python3 openspec/schemas/use-case-driven/validate_format.py --require-qualified-ids openspec/specs/domain/capability-name/spec.md ``` Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`. @@ -158,7 +169,7 @@ python3 openspec/schemas/function-driven/validate_format.py --require-qualified- неизменённые legacy specs. Проверка охватывает один Scenario, обычную структуру use case или формат сокращенного use case, ссылки шагов на FR, форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков -в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, +в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, таблицу кодов и её связь с FR. Семантическую завершённость функции и понятность кода оценивает автор/reviewer. Схема требует от автора запускать обе проверки; автоматического hook в CLI нет. diff --git a/openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc b/openspec/schemas/use-case-driven/__pycache__/validate_format.cpython-312.pyc similarity index 100% rename from openspec/schemas/function-driven/__pycache__/validate_format.cpython-312.pyc rename to openspec/schemas/use-case-driven/__pycache__/validate_format.cpython-312.pyc diff --git a/openspec/schemas/function-driven/patterns/database-table.md b/openspec/schemas/use-case-driven/patterns/database-table.md similarity index 68% rename from openspec/schemas/function-driven/patterns/database-table.md rename to openspec/schemas/use-case-driven/patterns/database-table.md index cb0d5a9..9f78462 100644 --- a/openspec/schemas/function-driven/patterns/database-table.md +++ b/openspec/schemas/use-case-driven/patterns/database-table.md @@ -19,19 +19,17 @@ ## Пример ```markdown -##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings +##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей -Таблица `settings` создаётся в схеме приложения и содержит: +Таблица `example_records` создаётся в схеме приложения и содержит: | Поле | Тип | Ограничения и значение по умолчанию | Назначение | | --- | --- | --- | --- | | `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | -| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | -| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | -| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | -| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | -| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении | -| `description` | `TEXT` | NULL | Пояснение к настройке | +| `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе | +| `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи | +| `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи | +| `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи | -Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. +Индекс поддерживает выборку по `external_id` и `status`. Ограничение уникальности на `external_id` устанавливается, если внешняя система гарантирует его уникальность. ``` diff --git a/openspec/schemas/function-driven/patterns/message-contract.md b/openspec/schemas/use-case-driven/patterns/message-contract.md similarity index 100% rename from openspec/schemas/function-driven/patterns/message-contract.md rename to openspec/schemas/use-case-driven/patterns/message-contract.md diff --git a/openspec/schemas/use-case-driven/schema.yaml b/openspec/schemas/use-case-driven/schema.yaml new file mode 100644 index 0000000..59cb16b --- /dev/null +++ b/openspec/schemas/use-case-driven/schema.yaml @@ -0,0 +1,337 @@ +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: | + Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их + выполненными по мере работы. Остановись, если столкнёшься с препятствием или + потребуется уточнение. diff --git a/openspec/schemas/function-driven/templates/design.md b/openspec/schemas/use-case-driven/templates/design.md similarity index 100% rename from openspec/schemas/function-driven/templates/design.md rename to openspec/schemas/use-case-driven/templates/design.md diff --git a/openspec/schemas/use-case-driven/templates/main-spec.md b/openspec/schemas/use-case-driven/templates/main-spec.md new file mode 100644 index 0000000..45dd7b0 --- /dev/null +++ b/openspec/schemas/use-case-driven/templates/main-spec.md @@ -0,0 +1,16 @@ +# Capability: <название> + +## Purpose + +<Бизнес-функция capability и понятный результат, не менее 50 знаков.> + +## Границы + + + +## Requirements + + diff --git a/openspec/schemas/function-driven/templates/proposal.md b/openspec/schemas/use-case-driven/templates/proposal.md similarity index 100% rename from openspec/schemas/function-driven/templates/proposal.md rename to openspec/schemas/use-case-driven/templates/proposal.md diff --git a/openspec/schemas/function-driven/templates/spec.md b/openspec/schemas/use-case-driven/templates/spec.md similarity index 98% rename from openspec/schemas/function-driven/templates/spec.md rename to openspec/schemas/use-case-driven/templates/spec.md index 29d1784..9ffe135 100644 --- a/openspec/schemas/function-driven/templates/spec.md +++ b/openspec/schemas/use-case-driven/templates/spec.md @@ -101,7 +101,7 @@ HTTP status: <код и условие возврата>. diff --git a/openspec/schemas/function-driven/templates/tasks.md b/openspec/schemas/use-case-driven/templates/tasks.md similarity index 55% rename from openspec/schemas/function-driven/templates/tasks.md rename to openspec/schemas/use-case-driven/templates/tasks.md index 427379c..b9353ca 100644 --- a/openspec/schemas/function-driven/templates/tasks.md +++ b/openspec/schemas/use-case-driven/templates/tasks.md @@ -9,7 +9,3 @@ - [ ] 2.1 - [ ] 2.2 - -## 3. Обновление версии - -- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.py`. diff --git a/openspec/schemas/function-driven/validate_format.py b/openspec/schemas/use-case-driven/validate_format.py similarity index 74% rename from openspec/schemas/function-driven/validate_format.py rename to openspec/schemas/use-case-driven/validate_format.py index 04115da..ed2bde4 100644 --- a/openspec/schemas/function-driven/validate_format.py +++ b/openspec/schemas/use-case-driven/validate_format.py @@ -1,4 +1,4 @@ -"""Read-only checks of function-driven Markdown conventions; no dependencies.""" +"""Read-only checks of use-case-driven Markdown conventions; no dependencies.""" from __future__ import annotations @@ -27,8 +27,6 @@ HTML_ANCHOR = re.compile(r"]*\bid\s*=", re.IGNORECASE) DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение") CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение") RESPONSE_CONTRACT_COLUMNS = (*CONTRACT_COLUMNS, "Формирование значения") -CAPABILITY_CODES_PATH = Path(__file__).with_name("capability-codes.md") -CAPABILITY_CODE_ROW = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|$") def plain_text(value: str) -> str: @@ -65,27 +63,165 @@ def parse_fr_reference(label: str) -> tuple[str | None, str] | None: return None -def load_capability_codes() -> tuple[dict[str, str], list[str]]: - codes: dict[str, str] = {} - errors: list[str] = [] - try: - lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines() - except OSError as error: - return {}, [f"не удалось прочитать реестр capability codes: {error}"] +def openspec_root_for(path: Path) -> Path: + """Find the OpenSpec root containing a master or change spec.""" + resolved = path.resolve() + for parent in (resolved, *resolved.parents): + if parent.name == "openspec": + return parent + return (Path.cwd() / "openspec").resolve() - prefixes: dict[str, str] = {} - for line in lines: - match = CAPABILITY_CODE_ROW.match(line) - if not match: + +def load_capability_prefixes(openspec_root: Path) -> tuple[dict[str, str], list[str]]: + """Read the active path-to-prefix mapping from master specs.""" + specs_root = openspec_root / "specs" + spec_paths = set(specs_root.rglob("spec.md")) + prefixes_by_capability: dict[str, set[str]] = {} + errors: list[str] = [] + for spec_path in sorted(spec_paths): + capability_path = spec_path.parent.relative_to(specs_root).as_posix() + try: + ids = REQUIREMENT_ID.findall(spec_path.read_text(encoding="utf-8")) + except OSError as error: + errors.append(f"не удалось прочитать спецификацию {spec_path}: {error}") continue - capability_path, prefix = match.groups() - if capability_path in codes: - errors.append(f"путь capability повторяется в реестре: {capability_path}") - if prefix in prefixes: - errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}") - codes[capability_path] = prefix - prefixes[prefix] = capability_path - return codes, errors + prefixes = { + requirement_id.rsplit("-", 1)[0] + for requirement_id in ids + if "." in requirement_id + } + if prefixes: + prefixes_by_capability.setdefault(capability_path, set()).update(prefixes) + + prefix_owners: dict[str, set[str]] = {} + mappings: dict[str, str] = {} + for capability_path, prefixes in prefixes_by_capability.items(): + if len(prefixes) != 1: + errors.append( + f"capability {capability_path} использует несколько префиксов: " + f"{', '.join(sorted(prefixes))}" + ) + continue + prefix = next(iter(prefixes)) + mappings[capability_path] = prefix + prefix_owners.setdefault(prefix, set()).add(capability_path) + + for prefix, owners in prefix_owners.items(): + if len(owners) > 1: + errors.append( + f"префикс {prefix} используется несколькими capabilities: " + f"{', '.join(sorted(owners))}" + ) + return mappings, errors + + +def load_active_change_prefixes( + openspec_root: Path, + exclude_path: Path, +) -> dict[str, set[str]]: + """Read prefixes declared by other in-flight changes.""" + changes_root = openspec_root / "changes" + excluded = exclude_path.resolve() + prefixes_by_capability: dict[str, set[str]] = {} + if not changes_root.is_dir(): + return prefixes_by_capability + + for change_dir in changes_root.iterdir(): + if not change_dir.is_dir() or change_dir.name == "archive": + continue + for spec_path in change_dir.rglob("spec.md"): + if spec_path.resolve() == excluded: + continue + capability_path = spec_capability_path(spec_path) + if not capability_path: + continue + try: + ids = REQUIREMENT_ID.findall(spec_path.read_text(encoding="utf-8")) + except OSError: + continue + prefixes = { + requirement_id.rsplit("-", 1)[0] + for requirement_id in ids + if "." in requirement_id + } + if prefixes: + prefixes_by_capability.setdefault(capability_path, set()).update(prefixes) + return prefixes_by_capability + + +def check_capability_ids( + path: Path, + requirement_ids: list[str], + known_prefixes: dict[str, str], + base: Path | None = None, +) -> list[str]: + """Check that a spec uses one stable, project-unique capability prefix.""" + prefixes = { + requirement_id.rsplit("-", 1)[0] + for requirement_id in requirement_ids + if "." in requirement_id + } + if not prefixes: + return [] + + capability_path = spec_capability_path(path) + if not capability_path: + return ["по пути файла не удалось определить capability для составного Requirement ID"] + + errors: list[str] = [] + if len(prefixes) > 1: + errors.append( + f"capability {capability_path} использует несколько префиксов: " + f"{', '.join(sorted(prefixes))}" + ) + + base_capability_path = spec_capability_path(base) if base else None + owners_by_prefix: dict[str, set[str]] = {} + for known_path, known_prefix in known_prefixes.items(): + owners_by_prefix.setdefault(known_prefix, set()).add(known_path) + + expected_prefix = known_prefixes.get(capability_path) + if expected_prefix is None and base_capability_path: + expected_prefix = known_prefixes.get(base_capability_path) + active_change_prefixes: dict[str, set[str]] = {} + if is_change_spec(path): + active_change_prefixes = load_active_change_prefixes( + openspec_root_for(path), path + ) + + for prefix in prefixes: + if expected_prefix and prefix != expected_prefix: + errors.append( + f"ID использует префикс {prefix}, но для capability {capability_path} " + f"уже назначен {expected_prefix}" + ) + owners = owners_by_prefix.get(prefix, set()) + if owners and capability_path not in owners and base_capability_path not in owners: + errors.append( + f"префикс {prefix} уже используется capability " + f"{', '.join(sorted(owners))}" + ) + for active_path, active_prefixes in active_change_prefixes.items(): + if active_path == capability_path and len(active_prefixes) > 1: + errors.append( + f"активные changes для capability {capability_path} используют " + f"несколько префиксов: {', '.join(sorted(active_prefixes))}" + ) + if active_path == capability_path and prefix not in active_prefixes: + errors.append( + f"change для capability {capability_path} использует другой префикс: " + f"{', '.join(sorted(active_prefixes))}" + ) + elif ( + prefix in active_prefixes + and active_path != capability_path + and active_path != base_capability_path + ): + errors.append( + f"префикс {prefix} уже используется активным change " + f"для capability {active_path}" + ) + return errors def spec_capability_path(path: Path) -> str | None: @@ -97,6 +233,13 @@ def spec_capability_path(path: Path) -> str | None: return "/".join(capability_parts) if capability_parts else None +def is_change_spec(path: Path) -> bool: + parts = path.parts + changes_indexes = [index for index, part in enumerate(parts) if part == "changes"] + specs_indexes = [index for index, part in enumerate(parts) if part == "specs"] + return bool(changes_indexes and specs_indexes and specs_indexes[-1] > changes_indexes[-1]) + + def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]: """Return generated heading fragments and fragments that target FR headings.""" targets: set[str] = set() @@ -258,7 +401,7 @@ def check_requirement( requirement_id = ids[0] is_qualified = "." in requirement_id if require_qualified_ids and not is_qualified: - errors.append("новый или изменённый Requirement должен иметь составной ID capability, например CFG.AS-01") + errors.append("новый или изменённый Requirement должен иметь составной ID capability, например AREA.CAP-01") level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE) has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT" expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"] @@ -423,7 +566,8 @@ def validate( path: Path, base: Path | None = None, require_qualified_ids: bool = False, - capability_codes: dict[str, str] | None = None, + capability_prefixes: dict[str, str] | None = None, + capability_inventory_errors: list[str] | None = None, ) -> list[str]: text = path.read_text(encoding="utf-8") if HTML_ANCHOR.search(text): @@ -435,23 +579,17 @@ def validate( targets.update(base_targets) fr_targets.update(base_fr_targets) - errors = [] - if capability_codes is None: - capability_codes, registry_errors = load_capability_codes() - errors.extend(registry_errors) + errors = list(capability_inventory_errors or []) + if capability_prefixes is None: + capability_prefixes, inventory_errors = load_capability_prefixes( + openspec_root_for(path) + ) + errors.extend(inventory_errors) blocks = list(requirement_blocks(text)) ids = REQUIREMENT_ID.findall(text) if len(ids) != len(set(ids)): errors.append("повторяющиеся ID Requirements") - capability_path = spec_capability_path(path) - for requirement_id in ids: - if "." not in requirement_id: - continue - prefix = capability_codes.get(capability_path or "") - if not prefix: - errors.append(f"для capability {capability_path or '<не определена>'} нет префикса в capability-codes.md") - elif not re.fullmatch(rf"{re.escape(prefix)}-\d{{2,}}", requirement_id): - errors.append(f"ID {requirement_id} не соответствует префиксу {prefix} для {capability_path}") + errors.extend(check_capability_ids(path, ids, capability_prefixes, base)) if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE): errors.append("нет Requirements") for name, block in blocks: @@ -472,14 +610,27 @@ def main() -> int: paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])}) if not paths: parser.error("не найдены spec.md") - capability_codes, registry_errors = load_capability_codes() + prefix_cache: dict[Path, tuple[dict[str, str], list[str]]] = {} + reported_roots: set[Path] = set() failed = False - for error in registry_errors: - print(f"ERROR {CAPABILITY_CODES_PATH}: {error}") - failed = True for path in paths: try: - errors = validate(path, args.base, args.require_qualified_ids, capability_codes) + openspec_root = openspec_root_for(path) + if openspec_root not in prefix_cache: + prefix_cache[openspec_root] = load_capability_prefixes(openspec_root) + capability_prefixes, inventory_errors = prefix_cache[openspec_root] + reported_inventory_errors = ( + inventory_errors if openspec_root not in reported_roots else [] + ) + errors = validate( + path, + args.base, + args.require_qualified_ids, + capability_prefixes, + reported_inventory_errors, + ) + if reported_inventory_errors: + reported_roots.add(openspec_root) except OSError as error: errors = [str(error)] for error in errors: diff --git a/tests/__pycache__/test_validate_format.cpython-312.pyc b/tests/__pycache__/test_validate_format.cpython-312.pyc new file mode 100644 index 0000000..a45e575 Binary files /dev/null and b/tests/__pycache__/test_validate_format.cpython-312.pyc differ diff --git a/tests/test_validate_format.py b/tests/test_validate_format.py new file mode 100644 index 0000000..ff0d0e3 --- /dev/null +++ b/tests/test_validate_format.py @@ -0,0 +1,125 @@ +import sys +import tempfile +import unittest +from pathlib import Path + + +SCHEMA_DIR = Path(__file__).resolve().parents[1] / "openspec" / "schemas" / "use-case-driven" +sys.path.insert(0, str(SCHEMA_DIR)) + +import validate_format # noqa: E402 + + +class CapabilityPrefixTests(unittest.TestCase): + def setUp(self) -> None: + self.temp_dir = tempfile.TemporaryDirectory() + self.openspec_root = Path(self.temp_dir.name) / "openspec" + (self.openspec_root / "specs").mkdir(parents=True) + + def tearDown(self) -> None: + self.temp_dir.cleanup() + + def write_spec(self, path: Path, *requirement_ids: str) -> Path: + path.parent.mkdir(parents=True, exist_ok=True) + body = "\n".join(f"**ID:** `{requirement_id}`" for requirement_id in requirement_ids) + path.write_text(body, encoding="utf-8") + return path + + def test_loads_unique_prefixes_from_master_specs(self) -> None: + self.write_spec( + self.openspec_root / "specs/domain/capability-name/spec.md", + "DOM.CN-01", + "DOM.CN-02", + ) + self.write_spec( + self.openspec_root / "specs/inventory/items/spec.md", + "INV.IT-01", + ) + + prefixes, errors = validate_format.load_capability_prefixes(self.openspec_root) + + self.assertEqual( + prefixes, + {"domain/capability-name": "DOM.CN", "inventory/items": "INV.IT"}, + ) + self.assertEqual(errors, []) + + def test_reports_mixed_and_reused_master_prefixes(self) -> None: + self.write_spec( + self.openspec_root / "specs/domain/first/spec.md", + "DOM.FI-01", + "ALT.X-02", + ) + self.write_spec( + self.openspec_root / "specs/inventory/first/spec.md", + "INV.IT-01", + ) + self.write_spec( + self.openspec_root / "specs/inventory/second/spec.md", + "INV.IT-01", + ) + + _, errors = validate_format.load_capability_prefixes(self.openspec_root) + + self.assertTrue(any("использует несколько префиксов" in error for error in errors)) + self.assertTrue(any("используется несколькими capabilities" in error for error in errors)) + + def test_rejects_changing_a_capability_prefix(self) -> None: + self.write_spec( + self.openspec_root / "specs/domain/capability-name/spec.md", + "DOM.CN-01", + ) + change_spec = self.write_spec( + self.openspec_root / "changes/current/specs/domain/capability-name/spec.md", + "ALT.CN-01", + ) + prefixes, _ = validate_format.load_capability_prefixes(self.openspec_root) + + errors = validate_format.check_capability_ids(change_spec, ["ALT.CN-01"], prefixes) + + self.assertTrue(any("уже назначен DOM.CN" in error for error in errors)) + + def test_rejects_a_prefix_owned_by_another_master_capability(self) -> None: + self.write_spec( + self.openspec_root / "specs/domain/first/spec.md", + "DOM.FI-01", + ) + candidate = self.openspec_root / "changes/new/specs/domain/second/spec.md" + prefixes, _ = validate_format.load_capability_prefixes(self.openspec_root) + + errors = validate_format.check_capability_ids(candidate, ["DOM.FI-01"], prefixes) + + self.assertTrue(any("уже используется capability" in error for error in errors)) + + def test_rejects_prefix_conflicts_with_another_active_change(self) -> None: + self.write_spec( + self.openspec_root / "changes/other/specs/finance/reporting/spec.md", + "FIN.REP-01", + ) + candidate = self.openspec_root / "changes/current/specs/domain/capability-name/spec.md" + + errors = validate_format.check_capability_ids(candidate, ["FIN.REP-01"], {}) + + self.assertTrue(any("уже используется активным change" in error for error in errors)) + + def test_rename_preserves_the_master_prefix(self) -> None: + old_spec = self.write_spec( + self.openspec_root / "specs/domain/old-name/spec.md", + "DOM.ON-01", + ) + renamed_spec = self.openspec_root / "changes/current/specs/domain/new-name/spec.md" + prefixes, _ = validate_format.load_capability_prefixes(self.openspec_root) + + valid_errors = validate_format.check_capability_ids( + renamed_spec, ["DOM.ON-01"], prefixes, old_spec + ) + changed_errors = validate_format.check_capability_ids( + renamed_spec, ["DOM.NN-01"], prefixes, old_spec + ) + + self.assertEqual(valid_errors, []) + self.assertTrue(any("уже назначен DOM.ON" in error for error in changed_errors)) + + +if __name__ == "__main__": + unittest.main()