08. Specifications (9 типов SPEC)

Часть RENAR Standard v1.0-draft · ← Оглавление

8.1 Назначение главы

Глава нормирует closed list из 9 типов спецификаций (SPEC-*) как параллельную ось требованиям. Спецификации описывают структуру системы, требования описывают поведение. SPEC не является ребёнком SR в дереве требований; SPEC и SR связаны типизированными рёбрами графа (constrained-by[], implements-spec[]).

Закрытый список 9 типов — нормативное требование v1.0. Новые типы добавляются только через formal change procedure стандарта (глава 14).

8.2 Архитектурное решение: SPEC — параллельная ось, не дети SR

8.2.1 Две оси описания системы

Требования и спецификации отвечают на разные вопросы:

ОсьАртефактыВопрос
ПоведенческаяBR / SR / TR (глава 06)Что система должна делать
СтруктурнаяSPEC-* (9 типов)Как система структурно устроена для выполнения этих требований

8.2.2 SPEC сиблинг SR, связи через граф

Один SR может опираться на несколько SPEC: SR «создать заказ» опирается на SPEC-ARCH (где живёт сервис заказов), SPEC-API (контракт endpoint), SPEC-DATA (схема таблицы), SPEC-PROC (workflow), SPEC-SEC (правила доступа), SPEC-UI (форма). Это граф зависимостей, не дерево родителей: у SR ровно один родитель в дереве требований (BR), но множество типизированных ссылок на SPEC.

Дерево требований (поведенческая ось):     Параллельная ось спецификаций:

BR                                          SPEC-ARCH    SPEC-API
 └── SR  ←──── constrained-by[] ────►       SPEC-DATA    SPEC-INT
      └── TR ─── implements-spec[] ────►    SPEC-PROC    SPEC-UI
                                            SPEC-AI      SPEC-SEC
                                            SPEC-OPS

Дерево требований:
  SR.parent              → BR              (единственный родитель)
  TR.parent              → SR              (единственный родитель)

Граф связей (типизированные рёбра):
  SR.constrained-by[]    → SPEC-*
  TR.implements-spec[]   → SPEC-*
  SPEC-*.depends-on[]    → SPEC-*          (между спецификациями)
  SPEC-*.referenced-by[] → SR / TR          (auto-derived inverse)

8.2.3 Обоснование

АргументСледствие
SPEC и SR отвечают на разные вопросыSPEC не уточняет SR на более глубоком уровне — это отдельная категория описания
Один SR опирается на 5–7 SPECДерево «SPEC как родитель SR» приводит к множественному родительству
Industry standards (arc42, C4, OpenAPI, BPMN, ERD) живут параллельно требованиямRENAR следует этой проверенной практике
AI-агент может параллелить генерацию SR и SPECБез блокировки одного типа другим

8.3 Closed list 9 типов SPEC

ТипНазначениеIndustry reference
SPEC-ARCHАрхитектура системы / подсистемы: контексты, контейнеры, компоненты, deployment view, quality attributesarc42, C4 model (Brown), ISO/IEC/IEEE 42010
SPEC-APIAPI contracts: REST / GraphQL / gRPC / async events; версионирование, error model, rate limitsOpenAPI 3.x, AsyncAPI 2.x, gRPC IDL
SPEC-DATAData model: schema, ERD, indices, миграции, retention, PII classificationISO/IEC 11179, JSON Schema
SPEC-INTIntegration: взаимодействие между подсистемами и внешними системами; протоколы, контракты, SLAEnterprise Integration Patterns (Hohpe)
SPEC-PROCProcess / workflow: бизнес-процессы, state machines, saga, choreography, orchestrationBPMN 2.0, ISO/IEC 19510
SPEC-UIUI / UX: экраны, навигация, user journeys, accessibility, i18n, baseline imagesMaterial Design / Apple HIG, WCAG 2.2
SPEC-AIAI / ML: model cards, RAG, prompt engineering, eval strategy, cost budgetISO/IEC 23894, NIST AI RMF
SPEC-SECSecurity: authn / authz, threat model, secrets management, data classificationSTRIDE, OWASP ASVS, ISO/IEC 27001
SPEC-OPSOperations: deployment, observability, SLO / SLA, runbook, disaster recoveryGoogle SRE, ITIL v4, ISO/IEC 20000

8.3.1 Что НЕ вошло в v1.0 (с обоснованием)

КандидатРешениеОбоснование
SPEC-EVENTНе отдельный типСобытия / очереди — раздел SPEC-API (asynchronous APIs)
SPEC-CONFIGНе отдельный типFeature flags / env vars / secrets — раздел SPEC-OPS
SPEC-PERFНе отдельный типPerformance / NFR — раздел SPEC-ARCH (quality attributes) или SPEC-OPS (SLO)
SPEC-TEST-ENVНе отдельный типТестовые окружения — раздел SPEC-OPS
SPEC-DOMAINНе отдельный типDomain model — поглощён SPEC-ARCH (decomposition) + SPEC-DATA (entities)
SPEC-MIGRATIONНе отдельный типMigration — раздел SPEC-DATA (lifecycle)
SPEC-COMPLIANCEНе отдельный типCompliance — связи между SR/SPEC и нормативами через compliance-refs[], не отдельный артефакт

Closed list policy: если в дальнейшей работе обнаружится, что какой-то из исключённых типов реально нужен — он добавляется через formal change procedure стандарта с обоснованием.

8.4 Common schema (общие frontmatter поля)

Все 9 типов SPEC делят общий набор frontmatter полей. Type-specific поля добавляются как extensions поверх (§8.5). Полная machine-readable schema — в reference/02-schemas.md.

---
# === Identity (mandatory) ===
id: SPEC-<TYPE>-NN[.N]              # immutable; TYPE ∈ {ARCH,API,DATA,INT,PROC,UI,AI,SEC,OPS}
title: "<short, descriptive>"
type: SPEC-ARCH | SPEC-API | SPEC-DATA | SPEC-INT | SPEC-PROC | SPEC-UI | SPEC-AI | SPEC-SEC | SPEC-OPS
slug: "<kebab-case>"                # auto-derived

# === Scope (mandatory) ===
level: system | subsystem | module
scope:
  system: "<system-id>"
  subsystem: "<subsystem-id>"       # null если level=system

# === Lifecycle (mandatory) ===
status: draft | review | approved | verified | obsolete
priority: must | should | could     # not all types use; mostly SPEC-SEC / SPEC-OPS

# === Source: provenance from ADAPT (mandatory) ===
source:
  adapt: ADAPT-NNN                  # link to ADAPT artifact (см. глава 07)
  adapt-section: "Forward §N"       # canonical source — секция ADAPT
  tz-section: "§N.N"                # optional, для traceability

# === Граф связей (auto-managed except mandatory ones) ===
referenced-by: []                   # auto-derived; SR/TR/SPEC ссылающиеся сюда
depends-on: []                      # mandatory если есть; SPEC-* на которые опирается этот SPEC
verified-by: []                     # auto-derived; список TC IDs верифицирующих

# === AI provenance (mandatory на RENAR-4+; см. глава 12) ===
ai-provenance:
  generated-by: "<vendor>-<model>@<date>"
  prompt-template: "<template-path>@<version>"
  context-tokens: integer
  output-tokens: integer
  generation-time-ms: integer
  generated-at: "<ISO-8601>"
  human-edits: boolean

# === Замена (mandatory если применимо) ===
replaces: "<old-id>"
replaced-by: "<new-id>"
deprecated-date: "<ISO date>"

# === Compliance (optional) ===
compliance-refs: []                 # ссылки на ISO/GDPR/AI Act/NIST AI RMF
---

8.4.1 Обязательные разделы body

Body любого SPEC обязательно содержит:

  1. Назначение — 1–3 параграфа.
  2. Scope — что входит, что не входит.
  3. Type-specific разделы — см. §8.5.
  4. Связь с требованиями — какие SR/BR ссылаются.
  5. Связь с другими SPEC — depends-on[].
  6. Verification — какие TC верифицируют этот SPEC.

8.5 Type-specific extensions

Краткое описание type-specific полей и обязательных body-разделов. Полная machine-readable extension schema — в reference/02-schemas.md. Industry references детально — в указанных стандартах.

8.5.1 SPEC-ARCH

Type-specific frontmatter: arch-style, deployment-model, tech-stack, quality-attributes.

Mandatory body: системный контекст (C4 L1), контейнеры (C4 L2), компоненты (C4 L3) для критических контейнеров, quality attributes (latency / throughput / availability), ADR-журнал.

Spec-specific TC (глава 09): architecture conformance tests (zoning), quality attribute baseline tests.

8.5.2 SPEC-API

Type-specific frontmatter: api-style (rest / graphql / grpc / async-events), api-version, versioning-strategy, authentication, rate-limits, contract-file (location of machine-readable contract).

Mandatory body: endpoints / operations с payload / response / errors, versioning rules (breaking vs non-breaking), error model, authn/authz reference на SPEC-SEC, rate limits, 2–3 example запросов на endpoint.

Spec-specific TC: contract tests, authentication negative, rate limit tests.

8.5.3 SPEC-DATA

Type-specific frontmatter: data-style (relational / document / graph / columnar), storage-engine, schema-version, pii-classification[], retention-policies[], migration-strategy.

Mandatory body: domain entities, ERD (text / Mermaid / link), поля сущностей (type / constraints / indices / defaults), связи (FK / cardinality / cascade), PII / sensitive data classification + encryption at-rest + retention, migration approach, index strategy.

Spec-specific TC: migration tests, constraint tests (FK / NOT NULL / unique), PII handling tests, data retention tests.

8.5.4 SPEC-INT

Type-specific frontmatter: integration-pattern (request-response / event-driven / message-queue / webhook / file-transfer), direction, counterparty, sla, idempotency.

Mandatory body: интегрируемые системы, контракт обмена, failure modes + retry strategy, идемпотентность + dedup, security между системами, observability (correlation IDs).

Spec-specific TC: contract tests с моком counterparty, failure injection, idempotency, INT-TC end-to-end.

Замечание: SPEC-INT заменяет существующий INT-SR (§8.7 migration).

8.5.5 SPEC-PROC

Type-specific frontmatter: process-style (bpmn / state-machine / saga / choreography / orchestration), state-count, participants[], sla end-to-end и по шагам, compensation (defined / not-applicable / manual).

Mandatory body: process diagram (BPMN-flavor / Mermaid / link), состояния и переходы (для state machine), participants и их роли, happy path, альтернативные сценарии и исключения, timeouts и compensation (для saga), SLA.

Spec-specific TC: happy path E2E, alternative paths, compensation tests (для saga), SLA tests.

8.5.6 SPEC-UI

Type-specific frontmatter: ui-platform, target-users[] (с ссылками на persona разделы ADAPT), design-system, accessibility-level (WCAG-A / AA / AAA), i18n, mockup-links[], baseline-images[] для VLM-judge тестов.

Mandatory body: общая структура интерфейса, ключевые экраны, user journeys без технических деталей, сквозные элементы (права доступа / уведомления / error / empty states), тон и стиль, accessibility, i18n.

Spec-specific TC: VLM-judge с baseline (judge ≠ production изоляция), accessibility (axe-core / Pa11y), i18n (string overflow / RTL), user journey E2E.

Замечание: SPEC-UI заменяет существующий UIC (§8.7 migration).

8.5.7 SPEC-AI

Type-specific frontmatter: ai-pattern (rag / fine-tuning / prompt-engineering / tool-use / multi-agent), production-model (vendor / model / version), judge-model (обязан отличаться от production), context-strategy, eval-strategy (metric / threshold / baseline-dataset), cost-budget.

Mandatory body: архитектура AI-компонент (pipeline / orchestration / fallback), model card (capabilities / limits / known failure modes), context strategy, eval strategy с изоляцией judge ≠ production, cost management, hallucination mitigation, adversarial considerations.

Spec-specific TC: eval против baseline (judge isolated), adversarial (prompt injection как negative TC), cost regression, hallucination tests.

Замечание: SPEC-AI заменяет существующий AIC. Изоляция judge ≠ production model — обязательное требование стандарта для всех eval-TC.

8.5.8 SPEC-SEC

Type-specific frontmatter: security-domains[], auth-model (authn / authz strategies), data-classification[] (PII-high / PCI / internal), threat-model-method (STRIDE / PASTA / OCTAVE), compliance[], incident-response reference в SPEC-OPS.

Mandatory body: auth model (authn flow / authz rules), data classification с защитой, threat model (STRIDE-таблица с mitigation на каждую угрозу), secrets management, audit (что логируется / retention / доступ), encryption (at-rest / in-transit / key management), compliance mapping (ссылки на конкретные пункты).

Spec-specific TC: authn (pos + neg), authz (RBAC matrix), threat-test (каждая STRIDE-угроза → минимум 1 negative TC), audit log, secrets leakage.

8.5.9 SPEC-OPS

Type-specific frontmatter: deployment-style, environments[] (dev / staging / prod с purpose и scale), slo, observability (logs / metrics / traces / alerting), runbook-link, disaster-recovery (rto / rpo / backup-strategy).

Mandatory body: environments, deployment process (CI/CD pipeline / gating / rollout strategy), SLO (availability / latency / error budget), observability, alerting (критические алерты / escalation), runbook, capacity planning, disaster recovery.

Spec-specific TC: deployment tests (smoke), SLO regression (load testing), failover (DR drills), observability (alerts срабатывают когда ожидается).

8.6 Связь с требованиями и задачами

8.6.1 SR.constrained-by[]

SR в frontmatter получает поле constrained-by[] — типизированные ссылки на SPEC. Это граф, не дерево родителей. Родитель SR в дереве требований — единственный (BR).

# Frontmatter SR (пример)
id: SR-05
parent:
  id: BR-02
constrained-by:
  - SPEC-UI-01
  - SPEC-API-02
  - SPEC-DATA-03
  - SPEC-PROC-01
  - SPEC-SEC-01
verified-by:
  - TC-12
  - TC-13
source:
  adapt: ADAPT-001
  adapt-section: "Forward §3"

8.6.2 TR.implements-spec[]

TR (задача) ссылается на SR (родитель в дереве) + одна или более SPEC через implements-spec[]:

id: TR-42
title: "Реализовать endpoint POST /orders"
parent:
  id: SR-05
implements-spec:
  - SPEC-API-02
  - SPEC-DATA-03
verified-by:
  - TC-14

8.6.3 SPEC.depends-on[]

SPEC может опираться на другой SPEC:

id: SPEC-API-02
title: "REST API заказов"
type: SPEC-API
depends-on:
  - SPEC-DATA-03         # стабильная схема данных
  - SPEC-SEC-01          # auth model для endpoints

При изменении upstream SPEC (например SPEC-DATA-03) все downstream (SPEC-API-02 и через него связанные SR) обязаны быть пересмотрены: либо verified остаётся в силе, либо downstream артефакт получает obsolete-pending статус до пересмотра.

8.6.4 Auto-derived обратные рёбра

SPEC.referenced-by[] пересчитывается substrate-хуком после каждого изменения SR / TR / SPEC. Orphan SPEC (без referenced-by[] и без активного status) — предупреждение в отчёте качества.

8.7 Migration UIC / AIC / INT-SR / TS → SPEC-*

8.7.1 Mapping таблица

Старый типНовый типТип миграции
UIC-NNSPEC-UI-NNПереименование ID + перенос в specs/ui/
AIC-NNSPEC-AI-NNПереименование ID + перенос в specs/ai/
INT-SR-NNSPEC-INT-NNПереименование ID + перенос в specs/int/
TS-NNSPEC-<TYPE>-NN (распределение)Manual review каждого TS; AI-агент классифицирует body, архитектор approve через one-click

8.7.2 Атомарная миграция

Миграция — одна atomic change unit (V2) на уровне проекта. Параллельное существование старых типов (UIC / AIC / INT-SR / TS) и SPEC-* как SoT запрещено.

Процедура (substrate-agnostic):

  1. Подготовка: AI-агент классифицирует каждый существующий TS-NN в один из 9 типов SPEC.
  2. Архитектор approve классификации.
  3. Atomic change: переименование IDs (UIC→SPEC-UI; AIC→SPEC-AI; INT-SR→SPEC-INT; TS→SPEC-*), перенос файлов в specs/<type>/, обновление всех ссылок в BR / SR / TR / TC frontmatter (parent: UIC-NN → constrained-by: [SPEC-UI-NN]).
  4. Регенерация auto-derived файлов (REQUIREMENTS.md, SPECS.md, обратные рёбра).
  5. CI-проверка: отсутствие orphan ссылок и старых IDs.

8.7.3 ID immutability

После миграции SPEC IDs immutable (см. V1, §11.3.1). Переименование SPEC-API-02 → SPEC-API-08 запрещено. Замена — через deprecated + новый ID с replaces[].

8.8 Quality Gates SPEC

SPEC имеет dedicated state machine (глава 10 §10.3):

StateУсловие перехода
draftСоздан; обязательные поля frontmatter заполняются
reviewГотов к ревью; обязательные body-разделы (§8.4.1) и type-specific (§8.5) присутствуют
approvedАрхитектор подтвердил; depends-on[] консистенция проверена
verifiedВсе обязательные spec-specific TC (глава 09 §9.7) зелёные
obsoleteЗаменён или больше не актуален; replaced-by обязателен

Связь с QG-0 / QG-2 SENAR:

  • QG-0 (есть goal/AC у задачи) расширяется: для задач реализующих SPEC обязательны implements-spec[] в TR frontmatter.
  • QG-2 (есть evidence у done) расширяется: для задач реализующих SPEC обязательны TC соответствующего spec-specific вида (глава 09 §9.7).

8.9 Storage layout

8.9.1 На уровне системы

[system].req/
  br/
  sr/
  specs/
    arch/   SPEC-ARCH-NN-*.md
    int/    SPEC-INT-NN-*.md
    proc/   SPEC-PROC-NN-*.md
    sec/    SPEC-SEC-NN-*.md
    ops/    SPEC-OPS-NN-*.md
  adapt/
  tz/
  SPECS.md                # auto-generated index

8.9.2 На уровне подсистемы

[subsystem].req/
  br/                     # если своя бизнес-сторона
  sr/
  specs/
    arch/   SPEC-ARCH-NN-*.md      # архитектура подсистемы
    api/    SPEC-API-NN-*.md
    data/   SPEC-DATA-NN-*.md
    ui/     SPEC-UI-NN-*.md
    ai/     SPEC-AI-NN-*.md
    int/    SPEC-INT-NN-*.md
    proc/   SPEC-PROC-NN-*.md
    sec/    SPEC-SEC-NN-*.md
    ops/    SPEC-OPS-NN-*.md
  adapt/
  SPECS.md

Substrate-нативная реализация storage — substrate-specific (см. guide/03, guide/04).

8.9.3 SPECS.md — auto-generated index

SPECS.md — auto-generated реестр всех SPEC: ID, тип, заголовок, статус, ссылка на верифицируемое требование, ссылка на файл. Помечается linguist-generated=true. Триггеры перегенерации — каждое изменение SPEC frontmatter или каждый approve / verify gate.

8.10 Связь с другими главами

ГлаваСвязь
05 Methodology positioningSPEC как параллельная ось — следствие SoT inversion
06 Requirements hierarchySR.constrained-by[], TR.implements-spec[]
07 ADAPTSPEC ссылается на ADAPT через source.adapt
09 Test casesSpec-specific TC types (таблица обязательных видов TC для каждого типа SPEC)
10 Lifecycle и QGSPEC state machine + QG расширения для SPEC
11 Substrate versioningSPEC IDs immutable (V1); migration атомарно (V2)
12 Maturity modelRENAR-3+: все 9 типов SPEC где применимо
reference/02 — schemasПолная machine-readable schema для каждого type-specific extension
research/16 — knowledge graphconstrained-by[], implements-spec[], depends-on[] как edge types в графе