Модуль 1.5. Структура требований и трассируемость
Темы: бизнес/пользовательские/системные, функциональные/нефункциональные, метрики, traceability (RTM). Артефакты: спецификация требований (SRS), RTM. Практика: собрать RTM к SRS.
Хороший системный аналитик (SA) не «собирает хотелки», а конструирует систему требований: однозначных, проверяемых, связных с задачами, тестами и мониторингом. В этом модуле вы научитесь:
- раскладывать требования по типам (business / stakeholder / user / system; FR / NFR / constraints);
- формулировать метрики (от бизнес-KPI до SLO/SLI);
- строить и поддерживать RTM (Requirements Traceability Matrix) так, чтобы ни одна строка из SRS не «потерялась» по пути в код, тесты и алерты.
Каркас: как SA превращает «зачем» в «что» и «как проверим»
- Зачем (Vision/BRD): цели и бизнес-KPI.
- Кому/когда (UR): пользовательские требования и сценарии.
- Что делает система (SR): функциональные (FR) + нефункциональные (NFR) + ограничения (Constraints).
- Как проверим (AC/BDD + SLI/алерты): критерии приёмки и метрики наблюдаемости.
- Как связать (RTM): цель → требование → модели/контракты → задачи → тесты → мониторинг.
Типы требований: иерархия и примеры
По точке зрения
-
Business Requirements (BR): бизнес-цели и ожидаемая ценность.
Пример: «Увеличить конверсию оплаты на 2 п.п. за квартал». -
Stakeholder Requirements: «болит» у ролей (операции, комплаенс, поддержка).
Пример: «Финконтроль должен видеть аудит возвратов 5 лет». -
User Requirements (UR): поведение с точки зрения акторов.
Пример: «Покупатель может запросить возврат до 30 дней». - System Requirements (SR): инженерно описание «как будет работать». Делятся на FR/NFR/Constraints.
По содержанию
-
FR (функциональные): что делает система.
Пример: POST /refunds создаёт возврат; идемпотентность по Idempotency-Key. -
NFR (нефункциональные): качество/ограничения.
Пример: p95 POST /refunds < 2s; RTO ≤ 30m, RPO ≤ 5m. -
Constraints (ограничения): регуляторика/технологические рамки.
Пример: «Разделение PII; хранение логов 1 год; OAuth2+MTLS».
Атрибуты требования (минимум)
REQ-ID, Title, Type (BR/UR/FR/NFR/Constraint), Source, Priority (MoSCoW/WSJF), Status (Draft/Review/Approved/Deprecated), Version, SpecLink, Model/Contract, AC/BDD, DataImpact, Risk, Owner.
Правильные формулировки: как писать требования
- Однозначность: избегайте «быстро/удобно/надёжно». Всегда — цифры/пороги/примеры.
- Проверяемость: каждое требование имеет AC/BDD или способ измерения.
- Атомарность: одна мысль — один REQ-ID.
- Прослеживаемость: у каждого REQ есть ссылки на модели/контракты/тесты/метрики.
- Глоссарий: первые упоминания терминов ссылаются на определения.
Шаблон формулировки FR (EARS-стиль):
Когда [условие], система должна [действие] с [объекты] и должна вернуть [результат/ошибку].
Пример: «Когда payment.status=CAPTURED и amount ≤ capturedAmount, система должна создать возврат через POST /refunds и вернуть 201 Created; при повторе с тем же Idempotency-Key должна вернуть 200 с тем же refundId.»
Шаблон формулировки NFR:
Метрика/порог + объект измерения + окно измерения + как мерим.
Пример: «p95 latency для POST /refunds < 2 000 мс в течение 7 дней (Prometheus: refunds_latency_ms_p95).»
Метрики: от бизнес-целей до SLO/SLI
Связка KPI ↔ SLO ↔ SLI
- KPI (бизнес): конверсия, выручка, NPS, CAC/LTV.
- SLO (целевой уровень сервиса): обещание платформы (latency, availability, RTO/RPO…).
- SLI (индикатор): как именно мерим (конкретная метрика/запрос/алерт).
Пример «протяжки» цели:
Цель: +2 п.п. конверсии оплаты.
Гипотеза SA: p95 оплаты < 3с ↓ отвал платежей.
SLO: p95 POST /payments < 3с, error-rate < 0.5%/неделя.
SLI: payments_latency_p95, payments_error_rate, алерт при >0.5% 5 минут.
Категории NFR (с примерами)
- Performance: latency/throughput, time-to-first-byte, т.д.
- Reliability/Availability: 99.9%/month, RTO/RPO.
- Security/Compliance: OAuth2/JWT, MTLS, PII-masking, аудит, хранение логов.
- Observability: логи/метрики/трейсинг, алерты/дешборды, X-Correlation-Id.
- Scalability: linear scale при росте RPS до X; лимиты/квоты.
- Compatibility: поддержка N/N-1 версий контрактов X месяцев.
- Localization/Accessibility: языки, форматы дат/валют, WCAG.
SRS: каркас и взаимосвязь разделов
Рекомендуемая структура SRS (коротко):
- Область/термины.
- Сценарии (Use Cases) + BPMN/Sequence.
- Правила (DMN), исключения.
- Данные (ER, домены/справочники, миграции).
- Интеграции (OpenAPI/AsyncAPI, ошибки/лимиты/идемпотентность/безопасность).
- NFR (перформанс/надёжность/безопасность/наблюдаемость/совместимость).
- AC/BDD (критерии приёмки).
- Трассируемость: ссылка на RTM.
- Версии/изменения (SemVer + changelog, ADR).
Правило: в SRS текст + диаграммы + контракты + NFR всегда согласованы и версионируются синхронно.
RTM (Requirements Traceability Matrix): зачем и как
Что такое RTM
Матрица, которая увязывает цели → требования → артефакты → разработку → тесты → мониторинг. Без RTM вы не докажете, что реализовали ровно то, что обещали, и что это наблюдаемо в проде.
Модель трассируемости (рекомендуемая)
Goal → BR/Stakeholder → UR → FR/NFR (SRS) → Models (BPMN/DMN/ER/Sequence) → Contracts (OpenAPI/AsyncAPI/Schemas) → Jira (Epic/Feature/Story/Task) → Tests (AC/BDD/контрактные/нагрузочные) → Monitor (SLI/алерты/дашборды) → Release (tag, релиз-заметки)
Поля RTM-строки (минимум)
Goal, REQ-ID, Type, Short, Model/Contract, Jira, AC/BDD, Test Suite, Monitor/SLI, Release Tag, Owner, Status, Version.
Где хранить RTM
- Confluence (Page Properties Report) — удобно для чтения.
- Git (CSV/Markdown/Excel) — канон, живёт рядом с SRS/контрактами.
- Jira — как отчёт (dashboards), но не как место хранения канона.
Триггеры обновления RTM
- Новое/изменённое требование в SRS (PR) → строка RTM.
- Новые тесты/смена контракта/версия — bump версии и RTM.
- Перед релизом — проверка покрытия RTM (gate: < 90% — не пускаем).
Практические примеры
Фича «Возврат платежа» — фрагменты SRS и RTM
FR-REF-001: Создать возврат через POST /refunds (идемпотентно по Idempotency-Key).
NFR-PERF-004: p95 POST /refunds < 2 000 мс (неделя).
NFR-SEC-005: Маскирование PAN/PII в логах; аудит каждого изменения.
Фрагмент RTM (таблица):
|
Goal |
REQ-ID |
Тип |
Кратко |
Модель/Контракт |
Jira |
AC/BDD |
Мониторинг/SLI |
|---|---|---|---|---|---|---|---|
|
↑ конверсия возвратов |
FR-REF-001 |
FR |
Создать возврат (идемп) |
BPMN REF-001; openapi#/refunds v2.1 |
REF-101 |
refund.feature:Create, Idempotent |
refund_latency_p95<2s; refund_error_rate<0.5% |
|
соблюдение безопасности |
NFR-SEC-005 |
NFR |
Маскировка PII |
SRS §Security |
SEC-042 |
sec.feature:LogMasking |
алерт log_pii_exposed=0 |
|
стабильность и скорость |
NFR-PERF-004 |
NFR |
p95 < 2s |
SRS §NFR; SLIs в Grafana |
PERF-017 |
perf.feature:p95 |
refund_latency_p95 |
Фича «Смена адреса»
- UR-ADR-002: пользователь может изменить адрес до статуса Shipped.
- FR-ADR-003: PATCH /orders/{id}/delivery-address разрешён при status ∈ {Created,Paid,Packed}, иначе 409.
- NFR-SEC-010: маскирование PII; аудит изменений.
- RTM связывает: DMN «разрешающие статусы» → OpenAPI PATCH → BDD негатив «после Shipped → 409» → алерт на аномальные частоты отказов.
Встроенная «гигиена» требований и RTM
Состояния требований
Draft → Review → Approved → Deprecated (обязательно версия/дата/владелец).
Правило: в спринт/поток попадают только Approved; исключения — через CR и feature flag.
Идентификаторы и версии
- FR-PAY-001, NFR-OBS-004, C-REG-007 (Constraint), UR-CHK-003.
- SemVer в заголовках SRS/контрактов; RTM хранит ссылки вида openapi v2.4.0.
Проверки качества (чек-лист)
- Каждое требование имеет тип, AC/BDD или SLI.
- Нет двусмысленностей (запрет «быстро/надёжно» без чисел).
- У FR указаны ошибки/исключения/таймауты/повторы.
- У NFR есть окно измерения и способ замера.
- RTM покрывает ≥ 90% Approved-требований.
- Версии SRS/OpenAPI/ER указаны и согласованы.
Риски и анти-паттерны
-
«Каталог хотелок»: смешение BR/UR/FR/NFR в одну кашу.
→ Разведите по типам, введите атрибуты и шаблоны. -
SRS без NFR/наблюдаемости: в проде «медленно/падает».
→ Для входа (DoR) NFR и SLI/алерты обязательны. -
Нет RTM или он устарел: непонятно, что реализовано и протестировано.
→ Gate на релиз: покрытие RTM; обновление RTM — часть PR-шаблона. -
Дубли/конфликты требований: одинаковые REQ под разными ID.
→ Единый реестр ID; линк-чекер/ревью. -
PNG-диаграммы без исходников: нельзя обновить.
→ Храните Mermaid/PlantUML/drawio в Git; картинки — только рендер. -
Breaking без MAJOR: ломаем клиентов.
→ SemVer + openapi-diff в CI.
Вопрос–Ответ
Q: Чем FR отличается от UR?
A: UR описывает «что хочет пользователь»; FR — «что должна делать система», уже с ошибками/исключениями и конкретными интерфейсами.
Q: Куда класть ограничения регуляторики?
A: В Constraints раздел SRS и в RTM как отдельные строки с ссылкой на документ/норму и AC (например, «PII-masking в логах»).
Q: Как трассировать к бизнес-метрике, если причинно-следственная связь неочевидна?
A: Через гипотезу и промежуточные SLO (например, «p95 оплаты»). В RTM укажите ссылку на гипотезу и метрику проверки.
Q: Нужно ли трассировать «крошечные» правки?
A: Если правка меняет поведение/интеграции/данные/NFR — да. Орфографию/пробелы — нет.
Q: Один NFR может покрывать всю систему?
A: Да (крест-сечение). Трассируйте его к нескольким Story/сервисам и к централизованным SLI/алертам.
Практика: «Собрать RTM к SRS» (2–4 часа)
Вход: ваш мини-SRS из предыдущего модуля (или выберите тему «Возврат платежа» / «Смена адреса»).
Задача: составить RTM на 12–20 строк, покрывающий ≥ 90% требований SRS.
Шаги
- Завести реестр требований: присвоить REQ-ID, тип, версию, владельца.
- Связать с артефактами: для каждого FR/NFR указать модели (BPMN/DMN/ER/Sequence), контракты (OpenAPI/AsyncAPI).
- Связать с Jira: EPIC/Feature/Story/Task, статус.
- Добавить проверку: для FR — AC/BDD; для NFR — SLI/алерты/нагрузочные тесты.
- Собрать RTM-таблицу: CSV/Markdown (см. шаблон ниже).
- Проверить покрытие: нет «висячих» требований без задач/тестов/метрик.
- Зафиксировать версии: SRS vX.Y.Z; OpenAPI vA.B.C; пометить Release Tag.
Шаблон RTM (CSV/Markdown)
Goal,REQ-ID,Type,Short,Model/Contract,Jira,AC/BDD,Monitor/SLI,Release,Owner,Status,Version G1,FR-REF-001,FR,Create refund (idempotent),/bpmn/refund;/api#/refunds v2.1,REF-101,refund.feature:Create,refund_latency_p95,error_rate<0.5%,2025.08,SA,Approved,0.3.0 G1,NFR-PERF-004,NFR,p95<2s for POST /refunds,/srs#nfr,PERF-017,perf.feature:p95,p95_metric,2025.08,SA,Approved,0.3.0 ...
Критерии зачёта
- RTM покрывает ≥ 90% требований SRS; у каждого REQ есть хотя бы одна ссылка на модель/контракт и на тест/SLI.
- Указаны версии артефактов и релизный тег.
- Нет «孤» (孤—孤) строк без связей; нет дубликатов REQ-ID.
Готовые шаблоны (скопируйте в свой репозиторий)
Шаблон SRS (Markdown, укороченный)
# SRS: <Фича/Подсистема> Owner: <ФИО> | Version: 0.3.0 | Status: Review | Links: Jira EPIC-123, OpenAPI 2.1.0 ## 1. Область и термины ## 2. Сценарии (Use Cases) + BPMN/Sequence ## 3. Правила (DMN) и исключения ## 4. Данные (ER, домены, справочники) ## 5. Интеграции (OpenAPI/AsyncAPI; ошибки/лимиты/идемпотентность/безопасность) ## 6. NFR (perf/rel/sec/obs/compat); SLO/SLI ## 7. AC/BDD ## 8. Трассируемость (RTM ссылка) ## 9. Версии/изменения (changelog, ADR)
Шаблон строки требования (EARS + измеримость)
REQ-ID: <FR/NFR/C/UR>-<ДОМЕН>-NNN Title: <краткая формулировка> Type: FR/NFR/Constraint/UR Description: Когда <условие>, система должна <поведение/результат>. Исключения: <...>. Ошибки: <коды/типы>. AC/BDD: <Given/When/Then или ссылка> NFR/SLI (если применимо): <метрика, порог, окно измерения, как мерим> Models/Contracts: <ссылки> DataImpact: <ER-сущности/домены> Dependencies: <внешние API/команды> Risk: <низ/ср/высок> | Priority: <MoSCoW/WSJF> | Owner | Status | Version
Шпаргалка (распечатайте)
- Каждое требование — измеримо и проверяемо.
- FR ≠ UR: FR — «как работает система», с ошибками и исключениями.
- NFR с SLO/SLI: без способа измерения — не требование.
- RTM ≥ 90%: иначе фича не готова в релиз.
- Docs-as-code: версии, changelog, PR-ревью, линтеры.
- Единый глоссарий: термины не плавают.
- Breaking → MAJOR: синхронизация версий SRS/OpenAPI/ER.
