Схема 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: например, 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 входит в заголовок и подпись ссылки.
### 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».
Форматы Use case
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания. Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
#### 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: таблица содержит поля,
типы, ограничения/default и назначение. Паттерн не требует писать SQL DDL.
Контракт сообщения или технического лога в FR оформляется по
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. Форматирование спецификации само по себе не реализует этот контракт в приложении.
Проверки
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.