Template
Обновил git процесс
This commit is contained in:
@@ -5,12 +5,20 @@
|
||||
формат требований определён в `schema.yaml` и шаблонах. Существующие changes
|
||||
с явно указанной `schema: spec-driven` продолжают использовать свою схему.
|
||||
|
||||
## Git-процесс проекта
|
||||
|
||||
Схема задаёт порядок и формат OpenSpec-артефактов. Правила веток, двух
|
||||
последовательных PR, ручного слияния и явной команды продолжения находятся
|
||||
в [шаблоне проектных инструкций](../../../examples/project-bootstrap/AGENTS.md).
|
||||
При подключении схемы включите правила из этого шаблона в проектный
|
||||
`AGENTS.md` и согласуйте имя целевой ветки с настройками репозитория.
|
||||
|
||||
## Уровни спецификации
|
||||
|
||||
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
|
||||
- Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности.
|
||||
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
|
||||
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
||||
- Scenario — один из двух форматов Use case: полный или сокращённый. Формат определяется сложностью сценария, независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
||||
- FR — подробные правила и контракты сообщений за пределами Scenario;
|
||||
контракт HTTP endpoint размещается в завершающем CONTRACT.
|
||||
|
||||
@@ -68,8 +76,11 @@ Markdown-рендерер автоматически создаёт якоря
|
||||
|
||||
## Форматы Use case
|
||||
|
||||
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания.
|
||||
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
|
||||
- Полный Use case используй для крупных многошаговых сценариев с большим количеством последовательных действий.
|
||||
- Сокращённый Use case используй для простых коротких требований. Рассматривай их как кандидаты на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
|
||||
- Выбирай формат по сложности: не используй полный Use case для простых требований, а сокращённый — для объёмных многошаговых сценариев. Правило действует и для HTTP endpoint.
|
||||
|
||||
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращённый Use case содержит только Основной поток; каждый шаг ссылается на FR.
|
||||
|
||||
```text
|
||||
#### Scenario: Сокращенный use case: описание функции
|
||||
@@ -106,8 +117,8 @@ FR задаёт тексты, дальнейшие действия и связ
|
||||
|
||||
## HTTP-контракт в Requirement
|
||||
|
||||
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный
|
||||
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце
|
||||
Каждый endpoint оформляется отдельным Requirement. Формат Use case выбирается
|
||||
по сложности сценария; сложные правила шагов выносятся в FR. После всех FR, в конце
|
||||
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
|
||||
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
|
||||
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
|
||||
|
||||
@@ -7,8 +7,8 @@ CONTRACT. Для асинхронного сообщения или технич
|
||||
|
||||
## HTTP endpoint
|
||||
|
||||
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
|
||||
правила обработки указываются в FR, а контракт помещается в самом конце
|
||||
Каждый endpoint описывается отдельным Requirement; формат Use case выбирается
|
||||
по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце
|
||||
Requirement:
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -94,8 +94,13 @@ artifacts:
|
||||
пояснения, не влияющие на поведение и не снимающие неоднозначность контракта.
|
||||
|
||||
Scenario:
|
||||
- Автор выбирает полный или сокращённый сценарий независимо от типа FR
|
||||
и части системы (процесс, БД, API, UI и другие), кроме обязательного полного HTTP-сценария.
|
||||
- Выбирай формат по сложности сценария, независимо от типа FR и части системы
|
||||
(процесс, БД, API, UI и другие).
|
||||
- Полный Use case используй для крупных многошаговых сценариев с большим
|
||||
количеством последовательных действий, а не для простых коротких требований.
|
||||
- Сокращённый Use case используй для простых коротких требований, а не для
|
||||
объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты
|
||||
на выделение в отдельные Requirements для переиспользования в сценариях других Requirements.
|
||||
- Полный сценарий содержит разделы Участники, Предусловия,
|
||||
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
|
||||
в таком порядке.
|
||||
@@ -105,7 +110,8 @@ artifacts:
|
||||
которых нет в заголовке. Контекст отсутствует.
|
||||
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
|
||||
- В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR.
|
||||
- Каждую конечную точку HTTP описывай отдельным Requirement с полным сценарием.
|
||||
- Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария
|
||||
выбирай по его сложности.
|
||||
Сложные правила шагов выноси в FR со ссылками из сценария.
|
||||
- Основной поток и альтернативы обычного сценария включают коды
|
||||
завершения, если они определены для этой функции.
|
||||
|
||||
@@ -20,6 +20,12 @@
|
||||
|
||||
Система SHALL <наблюдаемый результат завершённой функции>.
|
||||
|
||||
<!-- Выбирай формат по сложности сценария, независимо от типа FR и части системы.
|
||||
Полный Use case используй для крупных многошаговых сценариев; сокращённый —
|
||||
для простых коротких требований. Такие требования — кандидаты на выделение
|
||||
в отдельные Requirements для переиспользования в сценариях других Requirements.
|
||||
Не используй полный формат для простых требований, а сокращённый — для объёмных. -->
|
||||
|
||||
#### Scenario: <название завершённого процесса>
|
||||
|
||||
##### Участники
|
||||
@@ -69,7 +75,7 @@ HTTP endpoint располагай в завершающем разделе CONT
|
||||
<При необходимости — параметры сообщений, связанные требования и соответствие
|
||||
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
|
||||
|
||||
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
|
||||
<!-- HTTP endpoint описывай в отдельном Requirement; формат Use case выбирай по сложности.
|
||||
Контракт размещай в конце Requirement, не разбивая request/response на FR:
|
||||
|
||||
#### CONTRACT
|
||||
@@ -87,9 +93,7 @@ HTTP status: <код и условие возврата>.
|
||||
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
|
||||
-->
|
||||
|
||||
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
|
||||
типа FR и предмета описания. Для сокращенного Use case используй только основной
|
||||
поток и ссылки на FR:
|
||||
<!-- Для сокращённого Use case замени полный Scenario следующим блоком:
|
||||
|
||||
#### Scenario: Сокращенный use case: <предмет описания>
|
||||
|
||||
|
||||
@@ -417,8 +417,6 @@ def check_requirement(
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user