Модуль 9.1. Стандарты SRS/IEEE/ISO
Темы: структура SRS, анти-паттерны, читаемость. Артефакт: SRS по шаблону. Практика: переработать плохую спецификацию.
SRS (Software Requirements Specification) — единый источник правды о требованиях. Хороший SRS:
- сокращает риски «разной картины мира» у бизнеса, девелоперов, QA и безопасников;
- делает требования проверяемыми и трассируемыми (кода → тестов → UAT → метрик);
- служит опорой для контрактов (OpenAPI/AsyncAPI), NFR и плана релизов.
Ориентиры стандартов:
- Исторический: IEEE 830 (устарел, но популярен как каркас).
- Актуальный: ISO/IEC/IEEE 29148 — процессы и атрибуты качества требований.
- Сопутствующее: ISO/IEC 25010 (качество ПО) — полезно для NFR.
Базовая структура SRS (совместима с IEEE 830 / ISO 29148)
Ниже — практичный каркас, который «приземляется» в Confluence/Docs-as-Code и живёт вместе с кодом.
-
Введение
- Назначение, область, не в скоупе (Out of Scope)
- Определения и глоссарий (Ubiquitous Language), список сокращений
- Ссылки (нормативные/информативные)
- Общее описание
- Персоны/ролями, сценарии высокого уровня (контекст)
- Ограничения: регуляторика, лицензии, платформа/стэк
- Допущения и зависимости
- API/UI/сообщения/интеграции, протоколы/версии, форматы
- Нефункциональные требования к интерфейсам (SLI/SLO, безопасность)
- Функциональные требования по фичам/юзкейсам
- Бизнес-правила, DMN/таблицы решений, ошибки и коды
- Производительность, надёжность, безопасность, аудит, наблюдаемость, локализация, доступность (a11y), портируемость, конфигурируемость, совместимость
- ER-модель, словари данных/справочники, ограничения (уникальность, ссылочная целостность), политики жизненного цикла данных
- Use Case + альтернативы, диаграммы состояний, happy/edge/error-потоки
- Нельзя менять протокол X, должен быть OAuth2/JWT, хранить в Postgres и т. п. (только если это жёсткое требование, а не вкус архитектора)
- RTM: REQ → AC/BDD → тесты → метрики/алерты
- Внешние интерфейсы
- Системные функции и правила
- Нефункциональные требования (NFR)
- Данные
- Состояния и сценарии
- Ограничения проектирования
- Трассируемость
- Критерии приёмки
- AC (Given/When/Then) + метод верификации (тест/инспекция/анализ/демонстрация)
- Приложения
- Глоссарий (расширенный), макеты/wireframes, OpenAPI/AsyncAPI ссылки/снэпшоты, схемы событий, чек-лист качества требований, Change Log
Обязательные атрибуты каждого требования: ID, формулировка, причина (rationale), приоритет, источник, метод проверки, статус, версия/дата.
Как писать требование (минимальная грамматика)
-
Оператор обязательности:
ДОЛЖНА/ДОЛЖЕН (shall/must) — строго, ДОЛЖНА МОЧЬ (should/may) — опционально. Избегайте «желательно/удобно/по возможности». -
Мера и факт наблюдения: число + единица + окно/условия.
«p95 < 2.5 сек в 08:00–23:00, Europe/Stockholm». - Единственный смысл в одном требовании (атомарность), без «и/или».
Шаблон карточки:
ID: REQ-PAY-001
Формулировка: Система ДОЛЖНА принимать запрос на создание платежа с суммой 0.01…100000.00 (точность 2 знака) и валютой из набора {RUB, USD, EUR}.
Rationale: финансовые ограничения и поддерживаемые валюты
Источник: Бизнес-требование BR-23
Приоритет: Must
Метод верификации: тест (API), инспекция схем
AC: см. AC-PAY-01..04
Связи: OpenAPI /v1/payments, ER платежей v2
Читаемость и модифицируемость (что делает SRS «живым»)
- Docs-as-Code: Markdown/AsciiDoc + Git, PR-ревью, диффы, релизные теги.
- Стиль-гайд терминов: таблица «запрещённых слов» → замены.
- Нумерация требований (REQ-XXX), иерархия секций 1–1.1–1.1.1, одинаковая структура по фичам.
- Малые параграфы, таблицы, диаграммы (Mermaid/PlantUML/BPMN) вместо полотна текста.
- Одинаковая лексика UI/API/событий/БД (глоссарий — источник правды).
- Видимость изменений: CHANGELOG, «Что поменялось» в начале файла, версии артефактов (OpenAPI v1.4).
Анти-паттерны SRS (плохое → хорошее)
|
Анти-паттерн |
Плохо |
Хорошо |
|---|---|---|
|
Неизмеримо |
«Сервис должен быстро отвечать» |
«p95 POST /payments < 2.5s (08–23), p99 < 5s» |
|
Двойные смыслы |
«Удобный интерфейс» |
«Поля формы доступны клавиатурой; контраст ≥ 4.5:1; ARIA для ошибок» |
|
Вода/рассуждения |
«Рекомендуется использовать Redis…» |
«REQ-CACHE-002: Кэш ДОЛЖЕН отдавать ключи ≤ 5 ms p95» (если это требование) |
|
«И/или/и т. п.» |
«может… и/или…» |
Разбить на отдельные требования |
|
Смешение уровней |
Требование описывает и UI, и БД, и протокол сразу |
Разнести: функционал, данные, интерфейс, NFR |
|
TBD без управляемости |
«TBD: решим позже» |
TBD-123 с владельцем, сроком и риском |
|
Дубликаты |
Два требования говорят одно и то же |
Сведение в одно + ссылки |
|
Не верифицируемо |
«Должно быть безопасно» |
Конкретика: «OAuth2, JWT RS256, аудит 3 года, PII маскирование» |
|
Пассива много |
«Данные должны быть проверены» |
«Сервис валидации ДОЛЖЕН отклонять … кодом 422 {code=…}» |
Список слов-«сирен»: быстро, удобно, надёжно, современно, примерно, обычно, как правило, минимально, максимально, и т. п., возможно, желательно, корректно, etc., and/or.
→ Заменять на измеримые, конкретные формулировки.
НФТ (NFR) в SRS — как формализовать
Категории (ISO 25010) и примеры метрик:
- Производительность: latency (p95/p99), throughput (RPS/jobs/s), потребление (CPU/RAM/IO).
- Надёжность/доступность: SLO (99.9%/кв.), MTTR, error budget, деградации.
- Безопасность: аутентификация (OAuth2), авторизация (ABAC/Scopes), шифрование в покое/транзите, аудит (WORM), секреты (Vault), PII-маскирование.
- Удобство: a11y (WCAG 2.1 AA), локализация, время завершения сценария.
- Наблюдаемость: логи JSON со схемой, метрики RED/USE, трассировки OTel, алерты SLO.
- Сопровождаемость: код-стайл, покрытие контракт-тестами, миграции expand/contract.
- Портируемость/совместимость: поддерживаемые платформы/браузеры/версии API.
Данные и интерфейсы в SRS (минимум, но достаточно)
Данные
- ER-схема (ключи/ограничения/индексы).
- Словарь полей: типы, диапазоны, обязательность, допустимые значения (справочники).
- Политики: хранение, ретенция, DQ-правила, источники истинны (SoT).
Интерфейсы
- API: ссылка на OpenAPI + выдержки критичных контрактов, коды ошибок, идемпотентность, пагинация, версии.
- События: имена, ключ партиционирования, версии, payload (Avro/JSON Schema).
- UI: состояния форм (loading/error/empty/async), а11y-требования.
Трассируемость и критерии приёмки
- Каждое REQ связано с AC (Given/When/Then), тест-кейсом/BDD-сценарием, и (если применимо) метрикой.
- Пример строки RTM:
|
REQ |
Описание |
AC |
Тест |
Артефакты |
|---|---|---|---|---|
|
REQ-PAY-001 |
Диапазон сумм |
AC-PAY-01..04 |
TC-01..04 |
OpenAPI /payments, ER v2 |
Шаблон SRS (артефакт — скопируйте и используйте)
# SRS — <Название системы/фичи> vX.Y (Дата) Owner: <PO> | SA: <ФИО> | Tech: <Лид> | QA: <Лид> | Security/Data: <контакты> ## 1. Введение ### 1.1 Назначение ### 1.2 Область и границы (Out of Scope) ### 1.3 Глоссарий и сокращения ### 1.4 Ссылки (стандарты, контракты, макеты) ## 2. Общее описание ### 2.1 Персоны и сценарии высокого уровня ### 2.2 Ограничения (регуляторика/платформа) ### 2.3 Допущения и зависимости ## 3. Внешние интерфейсы ### 3.1 API (OpenAPI vX.Y) — ссылка, версия, краткий обзор эндпоинтов ### 3.2 События (AsyncAPI/Avro) — имена, ключи, версии ### 3.3 UI/UX — состояния форм, a11y ### 3.4 Интеграции/протоколы ## 4. Функциональные требования > Формат: ID, формулировка (shall), rationale, метод проверки, приоритет, связи - REQ-...: - ... ## 5. Нефункциональные требования (NFR) ### 5.1 Производительность и масштабирование ### 5.2 Надежность/доступность ### 5.3 Безопасность/комплаенс/аудит ### 5.4 Наблюдаемость ### 5.5 Удобство, локализация, a11y ### 5.6 Сопровождаемость/портируемость ## 6. Данные ### 6.1 ER-модель (ссылка/встроенная диаграмма) ### 6.2 Словарь данных и справочники ### 6.3 Политики хранения/ретенции/DQ ## 7. Состояния и сценарии (Use Cases) ### 7.1 UC-диаграмма и описания ### 7.2 Альтернативные/ошибочные ветви ## 8. Ограничения проектирования (обоснованные) ## 9. Трассируемость (RTM) ## 10. Критерии приемки (AC, Given/When/Then) ## 11. Приложения (макеты, контракты, чек-листы) ## 12. Change Log (что изменилось в этой версии)
Инструменты и практики качества
- Docs-as-Code (Git, PR, code owners), автоматический линтинг (например, Vale) для стиля и «запрещённых слов».
- Шаблоны требований/AC/RTM, автоген OpenAPI/AsyncAPI-снэпшотов в SRS.
- Review-процедура: бизнес-ревью (ценность/UL), тех-ревью (выполнимость), QA-ревью (проверяемость), Security/Data-ревью.
- Версионирование: тег srs-vX.Y, CHANGELOG, ссылка на релиз.
- Gate в CI: без актуализированного SRS/RTM/контрактов PR не мержится (Definition of Done).
Риски и как их гасить
|
Риск |
Симптом |
Меры |
|---|---|---|
|
Разночтения терминов |
«оплата» vs «списание» |
Глоссарий с владельцем; проверка в ревью |
|
Неизмеримые NFR |
«быстро», «надёжно» |
SLO/метрики; таблица NFR-шаблонов |
|
Смешение дизайна и требований |
SRS превращается в ТЗ на архитектуру |
Оставить только обязательные ограничения и результаты |
|
SRS устаревает |
«код ушёл, SRS нет» |
Docs-as-Code, обязательный CHANGELOG, DoD-гейт |
|
Дубликаты/конфликты |
В разных местах разные цифры |
«Единая точка»: NFR-каталог, ссылки вместо копий |
|
Много TBD |
Неясные зоны на поздних стадиях |
Реестр TBD с датами/владельцами, эскалация на CCB |
|
Непроверяемые требования |
QA не может подтвердить |
Всегда «метод проверки» + AC/BDD |
Практика: «Переработать плохую спецификацию» (60–120 мин)
Исходник (фрагмент «плохого» SRS):
«Система должна быстро обрабатывать платежи. Пользователь видит удобную форму. Поддерживаются разные валюты. В случае проблемы система сообщает ошибку. Будет интеграция с банком. Логи пишутся. Возможно, добавим промокоды. И т. п.»
Шаги переработки:
- Распилить на разделы и идентифицировать требования (REQ-XXX).
- Заменить «сирены» на измеримые метрики и AC.
- Вынести интерфейсы (OpenAPI), ошибки — в карту ошибок.
- Добавить NFR (latency/error-rate/SLO, безопасность, логи/трейсы).
- Описать данные (валюта, точность, ER).
- Заполнить RTM и CHANGELOG.
Результат (исправленный фрагмент):
REQ-PAY-001: Сервис ДОЛЖЕН принимать POST /v1/payments с полями:
amount: decimal(18,2) ∈ [0.01; 100000.00], currency ∈ {RUB, USD, EUR}, orderId: UUID.
Метод проверки: контракт-тест, валидация диапазона (TC-01..04). Источник: BR-23.
REQ-PAY-002 (NFR): p95 латентности POST /v1/payments < 2.5s (08:00–23:00, Europe/Stockholm), p99 < 5s; error-rate 5xx < 0.5%.
Метод проверки: нагрузочный тест + SLI в проде.
REQ-PAY-003: Идемпотентность через заголовок Idempotency-Key (1..128 ASCII); повтор с тем же ключом возвращает тот же paymentId.
Метод: BDD-сценарий «Повтор запроса» + запрос в БД (уникальность ключа).
REQ-PAY-004: При недоступности PSP сервис ДОЛЖЕН возвращать 202 Accepted и ставить задачу в очередь, SLA обработки ≤ 5 минут p95.
Метод: контракт-тест + метрики queue_lag_seconds.
REQ-SEC-001: Аутентификация OAuth2, scope payments:write; авторизация по tenant; аудит записи: WORM, хранение ≥ 3 года.
Метод: инспекция конфигураций, e2e-тест роли.
Интерфейсы: OpenAPI v1.4 (ссылка), карта ошибок:
AMOUNT_BELOW_MIN → 422, CURRENCY_NOT_SUPPORTED → 422, PSP_TIMEOUT → 202.
Данные: ER «Платежи» v2, поле currency CHAR(3) (ISO 4217), amount DECIMAL(18,2).
RTM: REQ-PAY-001→AC-PAY-01..04→TC-01..04→/v1/payments.
Change Log: v1.4 — добавлен promoCode (опционально), non-breaking.
Критерии зачёта практики:
- Все расплывчатые слова заменены на измеримые формулировки.
- Есть AC/метод верификации для каждого REQ.
- Интерфейсы/данные/NFR вынесены и связаны ссылками.
- Заполнены RTM и CHANGELOG.
Вопрос–Ответ
В: Нужен ли SRS в Agile, если есть user stories?
О: Да, но «тонкий». SRS — каркас, где закреплены общие правила, NFR, данные, контракты и трассируемость. User stories → инкременты внутри этих рамок.
В: Сколько «страниц» должен занимать SRS?
О: Ровно настолько, чтобы закрыть неопределённость. Микросервис — 10–20 стр., сложная доменная область — больше. Главное — структурность и актуальность.
В: Можно ли описывать архитектуру в SRS?
О: Только обязательные ограничения (регуляторные/контрактные). Детали реализации — в ADR/арх-доках.
В: Как поддерживать SRS актуальным?
О: Docs-as-Code + PR-процесс, CHANGELOG, связь с DoD: без обновлённого SRS/RTM фича не «Done».
В: Что делать с неизбежными TBD?
О: Нумеровать (TBD-ID), назначать владельца и срок. Список TBD — часть плана рисков; на CCB — регулярный статус.
В: Наши разработчики «не читают документы».
О: Сделайте SRS удобным: короткие секции, таблицы, диаграммы, ссылки на контракты, живые AC/BDD. И главное — держите его в репозитории рядом с кодом.
Шпаргалка
- Требование = shall + мера + контекст + проверка.
- Уберите «быстро/удобно/и т. п.» → замените на SLO, WCAG, конкретику.
- Данные/интерфейсы/NFR — отдельными разделами, без дублирования.
- Трассируемость REQ→AC→тесты→метрики обязательна.
- SRS живёт в Git, меняется через PR и оставляет CHANGELOG.
- Каждый релиз — тег SRS и ссылки на версии контрактов.
