Template
init commit
This commit is contained in:
@@ -0,0 +1,166 @@
|
||||
# Схема function-driven
|
||||
|
||||
Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на
|
||||
`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`.
|
||||
Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes
|
||||
с явно указанной `schema: spec-driven` продолжают использовать свою схему;
|
||||
их миграция не является частью изменения формата master spec.
|
||||
|
||||
## Уровни спецификации
|
||||
|
||||
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
|
||||
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
|
||||
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
|
||||
- FR — подробные правила и контракты сообщений за пределами Scenario;
|
||||
контракт HTTP endpoint размещается в завершающем CONTRACT.
|
||||
|
||||
В спецификацию включаются только сведения, влияющие на наблюдаемое поведение,
|
||||
устойчивый контракт или обязательное техническое ограничение. Повторы и
|
||||
пояснения без такого влияния удаляются.
|
||||
|
||||
Для каждой 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.
|
||||
В новых и изменяемых 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 /cp/users по [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-таблице также указывается источник или правило формирования каждого поля.
|
||||
Другие паттерны добавляются отдельными файлами по мере появления потребности.
|
||||
|
||||
## Шаблоны и delta specs
|
||||
|
||||
- `templates/main-spec.md` — постоянная спецификация capability.
|
||||
- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`.
|
||||
- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow.
|
||||
|
||||
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 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
|
||||
```
|
||||
|
||||
Без аргументов `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 из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
|
||||
таблицу кодов и её связь с FR.
|
||||
Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
|
||||
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
|
||||
|
||||
Механизм схем и шаблонов: [официальная документация OpenSpec](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md).
|
||||
Reference in New Issue
Block a user