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

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
+177
View File
@@ -0,0 +1,177 @@
# Схема use-case-driven
`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.
Повторы и пояснения без такого влияния удаляются.
Составной префикс 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 до отдельного рефакторинга.
## Формат Requirement
Markdown-рендерер автоматически создаёт якоря из заголовков Requirement и FR.
Не добавляй HTML `<a id="..."></a>`. Ссылки используй на slug заголовка; при
переименовании заголовка обновляй все ссылки на него. Семантический ID Requirement
остаётся в строке `**ID:**`; полный ID FR входит в заголовок и подпись ссылки.
```text
### Requirement: Завершённая техническая функция
**ID:** AREA.CAP-01
Система SHALL ...
#### Scenario: Завершённый процесс
##### Участники
##### Предусловия
##### Основной поток
##### Альтернативы и ошибки
##### Результат
##### Коды завершения
#### Функциональные требования
##### AREA.CAP-01.FR-01: Правило обработки
##### AREA.CAP-01.FR-02 [DB]: Структура таблицы
##### AREA.CAP-01.FR-03 [API]: Контракт сообщения
##### AREA.CAP-01.FR-04 [UI]: Требования к интерфейсу
```
В Scenario «Назначение» опционально и добавляется только при наличии сведений,
которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток —
нумерованные короткие шаги «Что делаем — как делаем», например:
«Получаем данные — вызываем GET /api/resources по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)».
## Форматы Use case
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания.
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
```text
#### Scenario: Сокращенный use case: описание функции
##### Основной поток
1. Описываем первый аспект по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
2. Уточняем второй аспект по [AREA.CAP-01.FR-02](#areacap-01fr-02-дополнительное-правило).
```
Сокращенный Use case не содержит участников, предусловий, альтернатив и ошибок,
результата и кодов завершения.
Шаг, альтернатива или абзац Scenario содержит не более 240 знаков текста
без URL Markdown-ссылок. Сценарий не содержит Gherkin, блоков кода, таблиц
полей и подробных алгоритмов. Технические детали, тексты сообщений и логика находятся в FR; контракт HTTP
endpoint — в завершающем CONTRACT. Единственная таблица
Scenario — `Код | Смысл | Связанные FR`.
Ссылки ведут на автоматически сгенерированные slugs заголовков FR, например
`[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-контракт-api-структура-бд-форма-ui)`.
Полный ID используется внутри Requirement и при ссылке на другую capability.
Адрес фрагмента соответствует заголовку FR назначения. Каждый код ссылается
хотя бы на один FR, в котором он описан. Смысл кода понятен без `stage` или текста исключения.
FR задаёт тексты, дальнейшие действия и связи с другими требованиями.
Одинаковая обработка нескольких диагностических причин допускает один код.
Промежуточные события trace не включаются в коды завершения.
## Форматы FR
Обычный FR не имеет метки типа и описывает логику, правила или последовательность шагов. Специальный формат указывается после ID в заголовке: `[DB]`, `[API]` или `[UI]`. Метка не входит в ID FR и не меняет ссылки на него.
- [DB] описывает структуру базы данных по паттерну таблицы БД.
- FR [API] описывает контракт асинхронного сообщения или сериализуемой записи, включая технический лог. HTTP endpoint описывается в CONTRACT.
- [UI] зарезервирован для требований к интерфейсу; детальный паттерн будет добавлен отдельно.
## HTTP-контракт в Requirement
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
отдельные FR для частей HTTP-контракта.
Таблица тела Request содержит пять колонок по
patterns/message-contract.md. Таблица Response содержит те же колонки и
последнюю колонку «Формирование значения», описывающую источник или правило
формирования каждого поля. Для отсутствующего тела запроса укажи это явно и не
добавляй пустую таблицу.
## Паттерны FR
FR, описывающий таблицу БД, оформляется по
[`patterns/database-table.md`](patterns/database-table.md): таблица содержит поля,
типы, ограничения/default и назначение. Паттерн не требует писать SQL DDL.
Контракт сообщения или технического лога в FR оформляется по
[`patterns/message-contract.md`](patterns/message-contract.md): таблица задаёт направление,
поля, wire-типы, обязательность и ограничения. Один FR описывает одно направление.
В response-таблице также указывается источник или правило формирования каждого поля.
Другие паттерны добавляются отдельными файлами по мере появления потребности.
## Форматы master и delta 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 и
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
ссылок на неизменённые требования при проверке передай `--base <master-spec>`.
Если смысловые коды или сообщения ещё не выдаются приложением, это явно
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
Форматирование спецификации само по себе не реализует этот контракт в приложении.
## Проверки
```sh
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/`.
Можно передать несколько файлов или каталогов; проверка не изменяет их.
Стандартный `openspec schema validate` проверяет workflow, зависимости и наличие
шаблонов. `openspec validate` проверяет стандартную структуру спецификации.
Отдельная `validate_format.py --require-qualified-ids <spec-path>` проверяет
составные ID новых и изменённых Requirements; без флага валидатор также принимает
неизменённые legacy specs. Проверка охватывает один Scenario,
обычную структуру use case или формат сокращенного use case, ссылки шагов на FR,
форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков
в Scenario, префиксы из ID master specs, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
таблицу кодов и её связь с FR.
Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
Механизм схем и шаблонов: [официальная документация OpenSpec](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md).
@@ -0,0 +1,35 @@
# Паттерн FR: таблица базы данных
Применяй паттерн, когда FR описывает структуру таблицы БД, а не SQL-команду её создания.
## Формат
Используй заголовок вида `<requirement-id>.FR-NN [DB]: Таблица хранения <имя>` и назови таблицу и схему приложения перед таблицей полей.
Таблицу полей оформляй с колонками в этом порядке:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `field_name` | `TYPE` | NULL или NOT NULL; при наличии DEFAULT укажи значение | Короткое назначение поля |
Одна строка описывает одно поле. Указывай точный тип, nullability, default и ограничения, которые влияют на хранение или чтение данных. Называй назначение каждого поля. Не используй `—` или пустые ячейки вместо явного `NULL`, `NOT NULL` или отсутствия default.
После таблицы перечисляй только ограничения таблицы, которых нет в строках: первичный и внешние ключи, уникальность, индексы, порядок выборки и владение данными. Не дублируй значения по умолчанию или назначение полей. Пиши DDL только если конкретный контракт невозможно выразить этой таблицей.
## Пример
```markdown
##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей
Таблица `example_records` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
| `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе |
| `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи |
| `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи |
| `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи |
Индекс поддерживает выборку по `external_id` и `status`. Ограничение уникальности на `external_id` устанавливается, если внешняя система гарантирует его уникальность.
```
@@ -0,0 +1,57 @@
# Паттерн сериализуемого контракта
Используй паттерн для полей сериализуемых request/response-контрактов.
Для HTTP endpoint таблицы находятся в разделах Request и Response блока
CONTRACT. Для асинхронного сообщения или технического лога контракт остаётся
в типизированном FR [API].
## HTTP endpoint
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
правила обработки указываются в FR, а контракт помещается в самом конце
Requirement:
```markdown
#### CONTRACT
##### Request
Метод: `POST`; путь: `/resource`. Для endpoint без тела явно укажи отсутствие тела.
##### Response
HTTP status: `200` при успешном выполнении.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | Обязательное | Формат и допустимые значения | Короткое назначение поля | Источник или правило вычисления значения |
```
Тело запроса при наличии описывай таблицей с пятью колонками:
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | Обязательное или опциональное | Формат, допустимые значения, nullable/default или явное отсутствие дополнительных ограничений и значений по умолчанию | Короткое назначение поля |
Для response используй эти же колонки и добавь последней «Формирование
значения», чтобы для каждого поля указать источник значения или правило его
вычисления.
Одна строка описывает одно поле. Указывай JSON-тип, а не тип языка реализации.
Для вложенных полей используй путь из имён полей; для массивов указывай тип
элемента. Обязательность задаёт наличие поля, а ограничения — nullability,
формат, допустимые значения и default. Условие присутствия опционального поля
укажи в ограничениях. Если дополнительных ограничений или значения по
умолчанию нет, укажи это явно. Не оставляй ячейки пустыми и не используй тире.
Не создавай отдельные FR для HTTP request/response-контрактов. Не добавляй
таблицу для отсутствующего тела запроса.
## Сообщение или технический лог в FR [API]
Заголовок FR: `<requirement-id>.FR-NN [API]: Контракт сообщения <имя>` либо
Контракт запроса / Контракт ответа. Сразу после заголовка укажи
`Тип контракта: request` для отправляемых данных или
`Тип контракта: response` для возвращаемых данных. Для отправляемого сообщения
используй request. Один FR описывает одно направление и содержит одну таблицу
по формату выше.
@@ -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,21 @@
# Design
## Context
<!-- Текущее состояние и ограничения. Мотивация описана в proposal.md — не повторяй её. -->
## Goals / Non-Goals
**Goals:**
<!-- Цели этого design -->
**Non-Goals:**
<!-- Что явно не входит в scope -->
## Decisions
<!-- Ключевые технические решения, причины и рассмотренные альтернативы -->
## Risks / Trade-offs
<!-- Известные риски и компромиссы -->
@@ -0,0 +1,16 @@
# Capability: <название>
## Purpose
<Бизнес-функция capability и понятный результат, не менее 50 знаков.>
## Границы
<!-- Кратко опиши ответственность capability: что входит в её область,
что остаётся за её пределами и кому это принадлежит. Не дублируй Requirements. -->
## Requirements
<!-- Полный актуальный набор Requirements capability. Оформляй Requirements
по правилам schema.yaml. Не используй заголовки операций delta:
ADDED, MODIFIED, REMOVED или RENAMED. -->
@@ -0,0 +1,29 @@
# Proposal
## Why
<!-- Объясни мотивацию change: какую проблему он решает и почему нужен сейчас. -->
## What Changes
<!-- Опиши изменения: новые возможности, доработки и удаления. -->
## Capabilities
### New Capabilities
<!-- Добавляемые capabilities. Новые сегменты пути пиши в kebab-case и
согласуй с существующей структурой спецификаций. Для каждой создай
specs/<capability-path>/spec.md. -->
- `<capability-path>`: <brief description of what this capability covers>
### Modified Capabilities
<!-- Существующие capabilities, требования которых меняются. Указывай их только
при изменении поведения на уровне спецификации; для каждой создай delta
spec по точному пути openspec/specs/. Если требования не меняются, оставь
раздел пустым и установи skip_specs: true в .openspec.yaml. Не создавай
требование только ради прохождения проверки. -->
- `<existing-capability-path>`: <what requirement is changing>
## Impact
<!-- Затронутые код, API, зависимости и системы -->
@@ -0,0 +1,107 @@
# Spec Delta
## Purpose
<!-- Только для новой capability: 1–2 предложения, не менее 50 знаков.
Для существующей capability удали этот раздел. -->
<!-- Включай только сведения, меняющие поведение, контракт или обязательное
ограничение. Удаляй повторы и пояснения без такого влияния. -->
## ADDED Requirements
<!-- Для изменения существующего Requirement используй MODIFIED Requirements
и полный блок из master spec: ID, единственный Scenario и все FR.
Сохраняй заголовок, ID, номера FR и заголовки FR, на которые ссылаются по slug. -->
### 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/use-case-driven/patterns/database-table.md.
Сериализуемый контракт FR [API] оформляй по
openspec/schemas/use-case-driven/patterns/message-contract.md. В response-таблице
добавь колонку «Формирование значения» для каждого поля. -->
@@ -0,0 +1,11 @@
# Tasks
## 1. <!-- Название группы задач -->
- [ ] 1.1 <!-- Формулировка задачи -->
- [ ] 1.2 <!-- Формулировка задачи -->
## 2. <!-- Название группы задач -->
- [ ] 2.1 <!-- Формулировка задачи -->
- [ ] 2.2 <!-- Формулировка задачи -->
@@ -0,0 +1,645 @@
"""Read-only checks of use-case-driven Markdown conventions; no dependencies."""
from __future__ import annotations
import argparse
import re
import unicodedata
from pathlib import Path
from urllib.parse import unquote
SECTIONS = (
"Участники", "Предусловия", "Основной поток", "Альтернативы и ошибки",
"Результат", "Коды завершения",
)
CODE = re.compile(r"\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b")
LINK = re.compile(r"\[([^\]]+)\]\(#([^)]+)\)")
HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
LEGACY_REQUIREMENT_ID_PATTERN = r"[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+"
QUALIFIED_REQUIREMENT_ID_PATTERN = r"[A-Z][A-Z0-9]*(?:\.[A-Z][A-Z0-9]*)+-\d{2,}"
REQUIREMENT_ID_PATTERN = rf"(?:{QUALIFIED_REQUIREMENT_ID_PATTERN}|{LEGACY_REQUIREMENT_ID_PATTERN})"
REQUIREMENT_ID = re.compile(rf"^\*\*ID:\*\* `({REQUIREMENT_ID_PATTERN})`$", re.MULTILINE)
FR_ID_PATTERN = rf"(?:{QUALIFIED_REQUIREMENT_ID_PATTERN}\.)?FR-\d{{2,}}"
FR_ID = re.compile(rf"^(?:(?P<requirement>{QUALIFIED_REQUIREMENT_ID_PATTERN})\.)?(?P<number>FR-\d{{2,}})$")
FR_HEADING = re.compile(rf"^##### ({FR_ID_PATTERN})(?: \[(DB|API|UI)\])?: (.+)$", re.MULTILINE)
HTML_ANCHOR = re.compile(r"<a\b[^>]*\bid\s*=", re.IGNORECASE)
DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение")
CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение")
RESPONSE_CONTRACT_COLUMNS = (*CONTRACT_COLUMNS, "Формирование значения")
def plain_text(value: str) -> str:
value = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", value)
return re.sub(r"^[\d.\-\s]+|[`*_]", "", value).strip()
def heading_slug(title: str) -> str:
"""Build the heading fragment used by GitHub-style Markdown renderers."""
title = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", title)
title = re.sub(r"[`*_~]", "", title).lower()
slug: list[str] = []
for char in title:
category = unicodedata.category(char)[0]
if char.isspace():
if slug and slug[-1] != "-":
slug.append("-")
elif char in {"-", "_"} or category in {"L", "M", "N"}:
slug.append(char)
return "".join(slug).strip("-")
def parse_fr_reference(label: str) -> tuple[str | None, str] | None:
"""Return an optional requirement ID and the local FR number from a link label."""
label = label.strip()
match = FR_ID.fullmatch(label)
if match:
return match.group("requirement"), match.group("number")
match = re.fullmatch(
rf"({LEGACY_REQUIREMENT_ID_PATTERN})\s*/\s*(FR-\d{{2,}})", label
)
if match:
return match.group(1), match.group(2)
return None
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()
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
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:
parts = path.parts
indexes = [index for index, part in enumerate(parts) if part == "specs"]
if not indexes:
return None
capability_parts = parts[indexes[-1] + 1:-1]
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()
fr_targets: dict[str, tuple[str, str]] = {}
duplicates: dict[str, int] = {}
requirement_id = ""
for line in text.splitlines():
if line.startswith("### Requirement:"):
requirement_id = ""
id_match = REQUIREMENT_ID.match(line)
if id_match:
requirement_id = id_match.group(1)
match = HEADING.match(line)
if not match:
continue
slug = heading_slug(match.group(2))
if not slug:
continue
duplicate_index = duplicates.get(slug, 0)
duplicates[slug] = duplicate_index + 1
target = slug if duplicate_index == 0 else f"{slug}-{duplicate_index}"
targets.add(target)
fr_match = FR_HEADING.match(line)
if fr_match and requirement_id:
fr_id = FR_ID.fullmatch(fr_match.group(1))
if fr_id:
fr_targets[target] = (requirement_id, fr_id.group("number"))
return targets, fr_targets
def requirement_blocks(text: str):
heading = re.compile(r"^## .*|^### Requirement: (.+)$", re.MULTILINE)
headings = list(heading.finditer(text))
operation = ""
for index, match in enumerate(headings):
if not match.group(1):
operation = match.group().removeprefix("## ")
continue
if operation in {"REMOVED Requirements", "RENAMED Requirements"}:
continue
end = headings[index + 1].start() if index + 1 < len(headings) else len(text)
yield match.group(1), text[match.end():end]
def check_database_table_pattern(content: str) -> list[str]:
errors: list[str] = []
tables: list[list[str]] = []
current: list[str] = []
for line in content.splitlines():
if line.strip().startswith("|"):
current.append(line.strip())
elif current:
tables.append(current)
current = []
if current:
tables.append(current)
if len(tables) != 1:
return ["паттерн таблицы БД требует ровно одну Markdown-таблицу"]
rows = [[cell.strip() for cell in row.strip("|").split("|")] for row in tables[0]]
if len(rows) < 3 or tuple(rows[0]) != DB_TABLE_COLUMNS:
return ["таблица БД должна иметь заголовки Поле, Тип, Ограничения и значение по умолчанию, Назначение"]
if len(rows[1]) != len(DB_TABLE_COLUMNS) or any(not re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]):
errors.append("в таблице БД некорректная строка разделителя")
field_names: set[str] = set()
for row in rows[2:]:
if len(row) != len(DB_TABLE_COLUMNS) or any(not cell for cell in row):
errors.append("каждая строка таблицы БД должна содержать четыре непустые ячейки")
continue
field_name = row[0].strip("`")
if field_name in field_names:
errors.append(f"поле `{field_name}` повторяется в таблице БД")
field_names.add(field_name)
return errors
def check_message_contract_pattern(content: str, direction: str | None = None) -> list[str]:
errors: list[str] = []
contract_type_match = re.search(r"(?m)^Тип контракта: (request|response)$", content)
if direction is None and not contract_type_match:
errors.append("контракт должен явно указывать Тип контракта: request или response")
selected_direction = direction or (contract_type_match.group(1) if contract_type_match else "")
columns = (
RESPONSE_CONTRACT_COLUMNS
if selected_direction == "response"
else CONTRACT_COLUMNS
)
tables: list[list[str]] = []
current: list[str] = []
for line in content.splitlines():
if line.strip().startswith("|"):
current.append(line.strip())
elif current:
tables.append(current)
current = []
if current:
tables.append(current)
if len(tables) != 1:
return errors + ["паттерн контракта требует ровно одну Markdown-таблицу"]
rows = [[cell.strip() for cell in row.strip("|").split("|")] for row in tables[0]]
if len(rows) < 3 or tuple(rows[0]) != columns:
required_columns = ", ".join(columns)
return errors + [f"таблица контракта должна содержать колонки: {required_columns}"]
if len(rows[1]) != len(columns) or any(not re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]):
errors.append("в таблице контракта некорректная строка разделителя")
field_names: set[str] = set()
for row in rows[2:]:
if len(row) != len(columns) or any(not cell for cell in row):
errors.append("каждая строка таблицы контракта должна содержать нужное число непустых ячеек")
continue
field_name = row[0].strip(chr(96))
if field_name in field_names:
errors.append(f"поле контракта {field_name} повторяется")
field_names.add(field_name)
if row[2] not in {"Обязательное", "Опциональное"}:
errors.append(f"поле контракта {field_name} должно явно задавать обязательность")
return errors
def check_http_endpoint_contract(content: str) -> list[str]:
errors: list[str] = []
headings = re.findall(r"^##### (.+)$", content, re.MULTILINE)
if headings != ["Request", "Response"]:
return ["CONTRACT должен содержать только подразделы Request и Response в этом порядке"]
request, response = re.split(r"^##### (?:Request|Response)\s*$", content, maxsplit=2, flags=re.MULTILINE)[1:]
if len(re.findall(r"(?m)^Метод: \x60?(?:GET|POST|PUT|PATCH|DELETE)\x60?; путь: \x60?/\S+", request)) != 1:
errors.append("в Request укажи один HTTP-метод и путь endpoint")
request_tables = sum(line.strip().startswith("|") for line in request.splitlines())
if request_tables:
errors.extend(check_message_contract_pattern(request, "request"))
elif not re.search(r"Тело запроса(?: и query-параметры)? отсутств(?:ует|уют)", request):
errors.append("в Request укажи таблицу тела запроса или явно отметь его отсутствие")
if not re.search(r"(?m)^HTTP status:", response):
errors.append("в Response укажи HTTP status")
errors.extend(check_message_contract_pattern(response, "response"))
return errors
def check_requirement(
name: str,
block: str,
targets: set[str],
fr_targets: dict[str, tuple[str, str]],
require_qualified_ids: bool = False,
) -> list[str]:
errors: list[str] = []
ids = REQUIREMENT_ID.findall(block)
if len(ids) != 1:
return [f"{name}: нужен один стабильный **ID:** с префиксом capability и номером Requirement"]
requirement_id = ids[0]
is_qualified = "." in requirement_id
if require_qualified_ids and not is_qualified:
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 ["Функциональные требования"]
if (
len(level_four) != len(expected_level_four) + 1
or not level_four[0].startswith("Scenario: ")
or level_four[1:] != expected_level_four
):
return [f"{name}: нужны один Scenario, Функциональные требования и опциональный завершающий CONTRACT"]
scenario_heading = level_four[0].removeprefix("Scenario: ")
is_short_use_case = scenario_heading.startswith("Сокращенный use case:")
scenario, details = block.split("#### Функциональные требования", 1)
scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1]
if has_contract:
if is_short_use_case:
errors.append("Requirement с HTTP CONTRACT должен использовать полный Use case")
details, contract_content = details.split("#### CONTRACT", 1)
errors.extend(check_http_endpoint_contract(contract_content))
sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE)
narrative = ""
outcomes = ""
short_use_case_flow_lines: list[str] = []
if is_short_use_case:
if sections != ["Основной поток"]:
errors.append("сокращенный use case должен содержать только Основной поток")
before_flow, separator, flow = scenario.partition("##### Основной поток")
if not separator or before_flow.strip():
errors.append("сокращенный use case содержит только раздел Основной поток")
short_use_case_flow_lines = [line.strip() for line in flow.splitlines() if line.strip()]
if any(not re.match(r"^\d+\. .+", line) for line in short_use_case_flow_lines):
errors.append("основной поток сокращенного use case содержит только нумерованные шаги")
if any(len(plain_text(line)) > 240 for line in short_use_case_flow_lines):
errors.append("шаг сокращенного use case длиннее 240 знаков; детали должны быть в FR")
else:
required = [section for section in sections if section != "Назначение"]
if required != list(SECTIONS) or sections.count("Назначение") > 1:
errors.append("разделы Scenario не соответствуют шаблону")
if "Назначение" in sections and sections[0] != "Назначение":
errors.append("опциональное Назначение должно предшествовать Участники")
for section in sections:
content = re.split(r"^##### ", scenario.split(f"##### {section}\n", 1)[1], maxsplit=1, flags=re.MULTILINE)[0]
if not content.strip():
errors.append(f"пустой раздел Scenario: {section}")
narrative, separator, outcomes = scenario.partition("##### Коды завершения")
if not separator:
errors.append("нет списка кодов завершения")
if re.search(r"^\s*\|", narrative, re.MULTILINE):
errors.append("техническая таблица должна находиться в FR")
for paragraph in re.split(r"\n\s*\n", narrative):
lines = [line for line in paragraph.splitlines() if line.strip() and not line.startswith("#")]
chunks = lines if all(re.match(r"^(?:\d+\.|-) ", line) for line in lines) else [" ".join(lines)]
if any(len(plain_text(chunk)) > 240 for chunk in chunks):
errors.append("абзац или шаг Scenario длиннее 240 знаков; перенеси детали в FR")
if re.search(r"(?im)^\s*(?:[-*]\s*)?(?:\*\*)?(?:GIVEN|WHEN|THEN|AND|BUT)\b", scenario):
errors.append("Scenario содержит Gherkin")
if "```" in scenario or "~~~" in scenario:
errors.append("блок кода должен находиться в FR")
flow = scenario.partition("##### Основной поток")[2]
if not is_short_use_case:
flow = flow.partition("##### Альтернативы и ошибки")[0]
steps = [int(number) for number in re.findall(r"^(\d+)\. ", flow, re.MULTILINE)]
if not steps or steps != list(range(1, len(steps) + 1)):
errors.append("основной поток должен содержать последовательные нумерованные шаги")
raw_definitions = list(FR_HEADING.finditer(details))
if len(raw_definitions) != len(re.findall(r"^##### ", details, re.MULTILINE)):
errors.append("подразделы Функциональных требований должны иметь заголовки с ID вида <requirement-id>.FR-NN")
definitions: list[tuple[re.Match[str], re.Match[str]]] = []
for match in raw_definitions:
fr_id_match = FR_ID.fullmatch(match.group(1))
if not fr_id_match:
errors.append(f"некорректный ID FR в заголовке: {match.group(1)}")
continue
definitions.append((match, fr_id_match))
numbers = [int(fr_id_match.group("number").removeprefix("FR-")) for _, fr_id_match in definitions]
if not numbers or numbers[0] != 1 or numbers != sorted(set(numbers)):
errors.append("FR должны начинаться с FR-01 и иметь уникальные возрастающие номера")
fr_contents: dict[str, str] = {}
for index, (match, fr_id_match) in enumerate(definitions):
fr_id = fr_id_match.group("number")
expected_fr_id = f"{requirement_id}.{fr_id}" if is_qualified else fr_id
if match.group(1) != expected_fr_id:
errors.append(f"заголовок FR должен использовать полный ID {expected_fr_id}")
target = heading_slug(match.group(0).removeprefix("##### "))
if fr_targets.get(target) != (requirement_id, fr_id):
errors.append(f"заголовок {match.group(1)} не создаёт ожидаемый Markdown-якорь")
next_definition = definitions[index + 1][0] if index + 1 < len(definitions) else None
end = next_definition.start() if next_definition else len(details)
fr_contents[fr_id] = details[match.end():end]
format_type = match.group(2)
title = match.group(3)
if format_type == "DB" or title.lower().startswith("таблица хранения "):
errors.extend(check_database_table_pattern(fr_contents[fr_id]))
if format_type == "API" and re.match(r"контракт (?:сообщения|запроса|ответа)\b", title, re.IGNORECASE):
errors.extend(check_message_contract_pattern(fr_contents[fr_id]))
if has_contract and format_type == "API":
errors.append("HTTP request/response-контракт описывается в CONTRACT, не в FR [API]")
for label, raw_target in LINK.findall(block):
target = unquote(raw_target)
if target not in targets:
errors.append(f"ссылка {label} ведёт на отсутствующий Markdown-заголовок #{target}")
continue
linked_fr = parse_fr_reference(label)
if "FR-" in label and not linked_fr:
errors.append(f"ссылка {label} должна содержать полный ID FR")
if linked_fr:
target_fr = fr_targets.get(target)
linked_requirement, linked_number = linked_fr
if target_fr is None or target_fr[1] != linked_number:
errors.append(f"ссылка {label} должна вести на заголовок соответствующего FR")
if linked_requirement and target_fr and target_fr[0] != linked_requirement:
errors.append(f"ссылка {label} ведёт на FR другого Requirement")
if target_fr and "." in target_fr[0] and label != f"{target_fr[0]}.{target_fr[1]}":
errors.append(f"ссылка {label} должна использовать полный ID {target_fr[0]}.{target_fr[1]}")
if is_short_use_case:
for step in short_use_case_flow_lines:
has_local_fr = False
for label, raw_target in LINK.findall(step):
linked_fr = parse_fr_reference(label)
target_fr = fr_targets.get(unquote(raw_target))
expected_label = f"{requirement_id}.FR-{linked_fr[1].removeprefix('FR-')}" if linked_fr and is_qualified else (linked_fr[1] if linked_fr else "")
if linked_fr and target_fr == (requirement_id, linked_fr[1]) and label == expected_label:
has_local_fr = True
break
if not has_local_fr:
errors.append("каждый шаг сокращенного use case должен ссылаться на локальный FR")
else:
rows = [line for line in outcomes.splitlines() if line.startswith("|")]
if not rows or rows[0] != "| Код | Смысл | Связанные FR |":
errors.append("таблица завершения должна иметь колонки Код, Смысл, Связанные FR")
codes = []
for row in rows[2:]:
cells = [cell.strip() for cell in row.strip("|").split("|")]
if len(cells) != 3 or not re.fullmatch(r"`[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+`", cells[0]):
errors.append("некорректная строка таблицы кодов завершения")
continue
code = cells[0].strip("`")
codes.append(code)
references = [
fr_targets[target][1]
for _, raw_target in LINK.findall(cells[2])
if (target := unquote(raw_target)) in fr_targets
and fr_targets[target][0] == requirement_id
]
if not cells[1] or not references or not any(code in fr_contents[fr_id] for fr_id in references if fr_id in fr_contents):
errors.append(f"{code}: нужны смысл и ссылка на локальный FR, описывающий этот код")
if not codes or len(codes) != len(set(codes)):
errors.append("список кодов завершения пуст или содержит дубликаты")
if set(CODE.findall(narrative)) != set(codes):
errors.append("коды в потоке/альтернативах должны совпадать со списком завершения")
return [f"{requirement_id}: {error}" for error in errors]
def validate(
path: Path,
base: Path | None = None,
require_qualified_ids: bool = False,
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):
return ["HTML-якоря запрещены; используйте автоматически сгенерированные Markdown-якоря заголовков"]
targets, fr_targets = heading_targets(text)
if base:
base_targets, base_fr_targets = heading_targets(base.read_text(encoding="utf-8"))
targets.update(base_targets)
fr_targets.update(base_fr_targets)
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")
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:
errors.extend(check_requirement(name, block, targets, fr_targets, require_qualified_ids))
return errors
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("paths", nargs="*", type=Path, default=[Path("openspec/specs")])
parser.add_argument("--base", type=Path, help="master spec referenced from a delta")
parser.add_argument(
"--require-qualified-ids",
action="store_true",
help="требовать составные ID у Requirements в новых или изменённых specs",
)
args = parser.parse_args()
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")
prefix_cache: dict[Path, tuple[dict[str, str], list[str]]] = {}
reported_roots: set[Path] = set()
failed = False
for path in paths:
try:
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:
print(f"ERROR {path}: {error}")
if not errors:
print(f"OK {path}")
failed |= bool(errors)
return int(failed)
if __name__ == "__main__":
raise SystemExit(main())