Рефакторинг схемы

This commit is contained in:
2026-10-11 08:57:33 +03:00
parent 1be96f7d4b
commit 31d898782c
17 changed files with 718 additions and 526 deletions
+3 -39
View File
@@ -1,43 +1,7 @@
schema: function-driven schema: use-case-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-полей, кодов, файлов,
инструментов, команд и идентификаторы без перевода.
rules: 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 <spec-path>.
proposal:
- Сохраняй полные иерархические пути capabilities.
- Пиши пояснительный текст proposal по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы.
design:
- Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований.
- Пиши пояснительный текст design по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы.
tasks: tasks:
- Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в `pyproject.toml`; один change повышает версию ровно один раз.
- Пиши названия групп и формулировки задач по-русски; сохраняй команды, пути, API, коды и идентификаторы без перевода. - До версии 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 для несовместимых изменений публичного контракта. - Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта.
@@ -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` |
@@ -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/<capability-path>/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 "<spec-id>" --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 "<id>"` 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 "<spec-id>" --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 и локальный номер: <requirement-id>.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-якоря вида <a id="..."></a>. 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/<capability-path>/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 <master-spec>.
- Не создавай 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 <spec-path>. Для неизменённых 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.
@@ -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. Явно отметь коды и тексты, которые ещё не реализованы.>
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
Контракт размещай в конце Requirement, не разбивая request/response на FR:
#### CONTRACT
##### Request
Метод: `POST`; путь: `/resource`. <Тело запроса или явное отсутствие тела.>
##### Response
HTTP status: <код и условие возврата>.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
-->
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
типа FR и предмета описания. Для сокращенного Use case используй только основной
поток и ссылки на FR:
#### Scenario: Сокращенный use case: <предмет описания>
##### Основной поток
1. <Кратко опиши первый аспект> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
2. <Кратко опиши следующий аспект> по [AREA.CAP-01.FR-02](#areacap-01fr-02-правило-или-контракт).
-->
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
[API] — контракт сообщения или технического лога; [UI] — требования к UI.
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md.
Сериализуемый контракт FR [API] оформляй по
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице
добавь колонку «Формирование значения» для каждого поля. -->
@@ -1,30 +1,36 @@
# Схема function-driven # Схема use-case-driven
Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на `use-case-driven` — переносимая русскоязычная схема OpenSpec, основанная на
`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`. `spec-driven`. Она задаёт workflow `proposal → specs / design → tasks`;
Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes формат требований определён в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему; с явно указанной `schema: spec-driven` продолжают использовать свою схему.
их миграция не является частью изменения формата master spec.
## Уровни спецификации ## Уровни спецификации
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. - Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. - Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
- FR — подробные правила и контракты сообщений за пределами Scenario; - FR — подробные правила и контракты сообщений за пределами Scenario;
контракт HTTP endpoint размещается в завершающем CONTRACT. контракт HTTP endpoint размещается в завершающем CONTRACT.
В спецификацию включаются только сведения, влияющие на наблюдаемое поведение, Requirements и FR включают только сведения, влияющие на наблюдаемое поведение,
устойчивый контракт или обязательное техническое ограничение. Повторы и устойчивый контракт или обязательное техническое ограничение. Раздел «Границы»
пояснения без такого влияния удаляются. кратко фиксирует ответственность и владение capability, не повторяя Requirements.
Повторы и пояснения без такого влияния удаляются.
Для каждой capability зарегистрируй стабильный уникальный префикс в Составной префикс Requirement строится из сокращений сегментов пути capability:
[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь для однословного сегмента используй первые три буквы, для сегмента с дефисами —
capability: например, `configuration/application-settings` получает `CFG.AS`. первые буквы его частей. Приводи сокращения к верхнему регистру. Например,
ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability. `domain/capability-name` получает `DOM.CN`. Если префикс уже занят, удлиняй
В сочетании с уникальным префиксом это даёт уникальный ID в проекте. сокращения новых сегментов до уникальности; ранее назначенные префиксы не меняй.
ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`, Сохраняй префикс при переименовании capability. Валидатор проверяет уникальность
`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement. по 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 В новых и изменяемых Requirements используй составные ID. Неизменённые legacy
specs могут сохранять прежние ID до отдельного рефакторинга. specs могут сохранять прежние ID до отдельного рефакторинга.
@@ -58,7 +64,7 @@ Markdown-рендерер автоматически создаёт якоря
В Scenario «Назначение» опционально и добавляется только при наличии сведений, В Scenario «Назначение» опционально и добавляется только при наличии сведений,
которых нет в заголовке. «Контекст» в 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 ## Форматы Use case
@@ -124,12 +130,17 @@ FR, описывающий таблицу БД, оформляется по
В response-таблице также указывается источник или правило формирования каждого поля. В response-таблице также указывается источник или правило формирования каждого поля.
Другие паттерны добавляются отдельными файлами по мере появления потребности. Другие паттерны добавляются отдельными файлами по мере появления потребности.
## Шаблоны и delta specs ## Форматы master и delta specs
- `templates/main-spec.md` — постоянная спецификация capability. - `templates/main-spec.md` — краткая схема постоянной master spec: Purpose, Границы и Requirements; это не артефакт change.
- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`. - `templates/spec.md` — полный шаблон delta для change, предоставляемый `openspec instructions specs`.
- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow. - `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow.
В master spec раздел `## Границы` располагается между Purpose и Requirements.
Он описывает ответственность capability, её включённую область и явные
исключения или передачу ответственности другим capabilities и приложению.
В delta spec этот раздел не повторяется: delta меняет отдельные Requirements.
ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration, ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration,
RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный
Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и
@@ -143,9 +154,9 @@ Scenario в таких операциях не создаётся. В delta со
## Проверки ## Проверки
```sh ```sh
openspec schema validate function-driven openspec schema validate use-case-driven
openspec validate orders/snapshot-sync --type spec --strict --no-interactive openspec validate domain/capability-name --type spec --strict --no-interactive
python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md 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/`. Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`.
@@ -158,7 +169,7 @@ python3 openspec/schemas/function-driven/validate_format.py --require-qualified-
неизменённые legacy specs. Проверка охватывает один Scenario, неизменённые legacy specs. Проверка охватывает один Scenario,
обычную структуру use case или формат сокращенного use case, ссылки шагов на FR, обычную структуру use case или формат сокращенного use case, ссылки шагов на FR,
форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков
в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки, в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
таблицу кодов и её связь с FR. таблицу кодов и её связь с FR.
Семантическую завершённость функции и понятность кода оценивает автор/reviewer. Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет. Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
@@ -19,19 +19,17 @@
## Пример ## Пример
```markdown ```markdown
##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings ##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей
Таблица `settings` создаётся в схеме приложения и содержит: Таблица `example_records` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение | | Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | | `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | | `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе |
| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | | `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи |
| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | | `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи |
| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | | `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи |
| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении |
| `description` | `TEXT` | NULL | Пояснение к настройке |
Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. Индекс поддерживает выборку по `external_id` и `status`. Ограничение уникальности на `external_id` устанавливается, если внешняя система гарантирует его уникальность.
``` ```
@@ -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/<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; описывай решения реализации
без копирования требований.
Хороший 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: |
Прочитай файлы контекста, выполняй незавершённые задачи и отмечай их
выполненными по мере работы. Остановись, если столкнёшься с препятствием или
потребуется уточнение.
@@ -0,0 +1,16 @@
# Capability: <название>
## Purpose
<Бизнес-функция capability и понятный результат, не менее 50 знаков.>
## Границы
<!-- Кратко опиши ответственность capability: что входит в её область,
что остаётся за её пределами и кому это принадлежит. Не дублируй Requirements. -->
## Requirements
<!-- Полный актуальный набор Requirements capability. Оформляй Requirements
по правилам schema.yaml. Не используй заголовки операций delta:
ADDED, MODIFIED, REMOVED или RENAMED. -->
@@ -101,7 +101,7 @@ HTTP status: <код и условие возврата>.
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД; <!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
[API] — контракт сообщения или технического лога; [UI] — требования к UI. [API] — контракт сообщения или технического лога; [UI] — требования к UI.
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md. [DB] с таблицей оформляй по openspec/schemas/use-case-driven/patterns/database-table.md.
Сериализуемый контракт FR [API] оформляй по Сериализуемый контракт FR [API] оформляй по
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице openspec/schemas/use-case-driven/patterns/message-contract.md. В response-таблице
добавь колонку «Формирование значения» для каждого поля. --> добавь колонку «Формирование значения» для каждого поля. -->
@@ -9,7 +9,3 @@
- [ ] 2.1 <!-- Формулировка задачи --> - [ ] 2.1 <!-- Формулировка задачи -->
- [ ] 2.2 <!-- Формулировка задачи --> - [ ] 2.2 <!-- Формулировка задачи -->
## 3. Обновление версии
- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.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 from __future__ import annotations
@@ -27,8 +27,6 @@ HTML_ANCHOR = re.compile(r"<a\b[^>]*\bid\s*=", re.IGNORECASE)
DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение") DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение")
CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение") CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение")
RESPONSE_CONTRACT_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: def plain_text(value: str) -> str:
@@ -65,27 +63,165 @@ def parse_fr_reference(label: str) -> tuple[str | None, str] | None:
return None return None
def load_capability_codes() -> tuple[dict[str, str], list[str]]: def openspec_root_for(path: Path) -> Path:
codes: dict[str, str] = {} """Find the OpenSpec root containing a master or change spec."""
errors: list[str] = [] resolved = path.resolve()
try: for parent in (resolved, *resolved.parents):
lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines() if parent.name == "openspec":
except OSError as error: return parent
return {}, [f"не удалось прочитать реестр capability codes: {error}"] return (Path.cwd() / "openspec").resolve()
prefixes: dict[str, str] = {}
for line in lines: def load_capability_prefixes(openspec_root: Path) -> tuple[dict[str, str], list[str]]:
match = CAPABILITY_CODE_ROW.match(line) """Read the active path-to-prefix mapping from master specs."""
if not match: 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 continue
capability_path, prefix = match.groups() prefixes = {
if capability_path in codes: requirement_id.rsplit("-", 1)[0]
errors.append(f"путь capability повторяется в реестре: {capability_path}") for requirement_id in ids
if prefix in prefixes: if "." in requirement_id
errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}") }
codes[capability_path] = prefix if prefixes:
prefixes[prefix] = capability_path prefixes_by_capability.setdefault(capability_path, set()).update(prefixes)
return codes, errors
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: 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 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]]]: def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]:
"""Return generated heading fragments and fragments that target FR headings.""" """Return generated heading fragments and fragments that target FR headings."""
targets: set[str] = set() targets: set[str] = set()
@@ -258,7 +401,7 @@ def check_requirement(
requirement_id = ids[0] requirement_id = ids[0]
is_qualified = "." in requirement_id is_qualified = "." in requirement_id
if require_qualified_ids and not is_qualified: 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) level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE)
has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT" has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT"
expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"] expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"]
@@ -423,7 +566,8 @@ def validate(
path: Path, path: Path,
base: Path | None = None, base: Path | None = None,
require_qualified_ids: bool = False, 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]: ) -> list[str]:
text = path.read_text(encoding="utf-8") text = path.read_text(encoding="utf-8")
if HTML_ANCHOR.search(text): if HTML_ANCHOR.search(text):
@@ -435,23 +579,17 @@ def validate(
targets.update(base_targets) targets.update(base_targets)
fr_targets.update(base_fr_targets) fr_targets.update(base_fr_targets)
errors = [] errors = list(capability_inventory_errors or [])
if capability_codes is None: if capability_prefixes is None:
capability_codes, registry_errors = load_capability_codes() capability_prefixes, inventory_errors = load_capability_prefixes(
errors.extend(registry_errors) openspec_root_for(path)
)
errors.extend(inventory_errors)
blocks = list(requirement_blocks(text)) blocks = list(requirement_blocks(text))
ids = REQUIREMENT_ID.findall(text) ids = REQUIREMENT_ID.findall(text)
if len(ids) != len(set(ids)): if len(ids) != len(set(ids)):
errors.append("повторяющиеся ID Requirements") errors.append("повторяющиеся ID Requirements")
capability_path = spec_capability_path(path) errors.extend(check_capability_ids(path, ids, capability_prefixes, base))
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}")
if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE): if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE):
errors.append("нет Requirements") errors.append("нет Requirements")
for name, block in blocks: 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])}) paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])})
if not paths: if not paths:
parser.error("не найдены spec.md") 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 failed = False
for error in registry_errors:
print(f"ERROR {CAPABILITY_CODES_PATH}: {error}")
failed = True
for path in paths: for path in paths:
try: 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: except OSError as error:
errors = [str(error)] errors = [str(error)]
for error in errors: for error in errors:
+125
View File
@@ -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()