Template
Рефакторинг схемы
This commit is contained in:
+3
-39
@@ -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 <spec-path>.
|
||||
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 для несовместимых изменений публичного контракта.
|
||||
|
||||
@@ -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-таблице
|
||||
добавь колонку «Формирование значения» для каждого поля. -->
|
||||
+35
-24
@@ -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 нет.
|
||||
+7
-9
@@ -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` устанавливается, если внешняя система гарантирует его уникальность.
|
||||
```
|
||||
@@ -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. -->
|
||||
+2
-2
@@ -101,7 +101,7 @@ HTTP status: <код и условие возврата>.
|
||||
|
||||
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
|
||||
[API] — контракт сообщения или технического лога; [UI] — требования к UI.
|
||||
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md.
|
||||
[DB] с таблицей оформляй по openspec/schemas/use-case-driven/patterns/database-table.md.
|
||||
Сериализуемый контракт FR [API] оформляй по
|
||||
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице
|
||||
openspec/schemas/use-case-driven/patterns/message-contract.md. В response-таблице
|
||||
добавь колонку «Формирование значения» для каждого поля. -->
|
||||
-4
@@ -9,7 +9,3 @@
|
||||
|
||||
- [ ] 2.1 <!-- Формулировка задачи -->
|
||||
- [ ] 2.2 <!-- Формулировка задачи -->
|
||||
|
||||
## 3. Обновление версии
|
||||
|
||||
- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.py`.
|
||||
+193
-42
@@ -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"<a\b[^>]*\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:
|
||||
Reference in New Issue
Block a user