Как делать репозиторий требований

1. Назначение и границы

Репозиторий хранит согласованное описание ожидаемого поведения продукта, историю его изменения и способы проверки. Он должен помогать аналитику обнаруживать пробелы, разработчику реализовывать поведение, тестировщику принимать результат, а сопровождающему понимать последствия изменений.

Два уровня детализации:

1. Верхнеуровневые требования (HLR): потребность, пользователь, ожидаемый результат, границы и критерии приёмки возможности.
2. Спецификации (REQ): конкретные наблюдаемые обязательства, условия, ограничения, контракты и исключения.

Вопросы, решения, сценарии, данные, макеты и линтеры сопровождают эти уровни. Архитектура — проектное решение, обоснованное HLR/REQ. Оно хранится в architecture/; обязательные технические ограничения оформляются обычными REQ второго уровня. Порядок описания архитектуры: ARCHITECTURE.md.

2. Признаки хорошего требования

Пример слабой формулировки: «Система быстро направляет жалобы в правильные ведомства».

Разделение на проверяемые обязательства:

• по утверждённым категории и территории выбирается маршрут из конкретной версии справочника;
• при отсутствии маршрута жалоба попадает в очередь ручной маршрутизации;
• выбранные ведомства и версия правила сохраняются в истории;
• изменение маршрута не пересчитывает срок рассмотрения;
• время постановки в очередь имеет отдельный измеримый предел при заданной нагрузке.

Пояснение причины хранится рядом, но отдельно от обязательства. Примеры дополняют общее правило: один успешный пример не задаёт всю область допустимого поведения.

Для NFR используйте: метрика + порог + условия + способ измерения. Например: p95 времени подтверждения приёма ≤ 2 с при 100 запросах/с, заданных размерах тела и составе стенда, измерение 30 минут после прогрева. Отдельно фиксируются начало/конец измерения, доля ошибок и исключения из выборки.

3. Что должно быть в верхнем уровне

Для каждой возможности: ID; проблема и цель; пользователи; контекст; наблюдаемый результат; входит/не входит; основные потоки; принципиальные гарантии; критерии успеха; приоритет; зависимости; источник; ответственный; статус; связанные вопросы и спецификации.

Верхний уровень должен содержать и сквозные гарантии: изоляцию жалоб, неизменность исходного обращения, предсказуемость сроков, аудит, полноту ответа, конфиденциальность аналитики. Эти гарантии могут детализироваться в нескольких областях.

Не превращайте HLR в перечень экранов или компонентов. Например, «заявитель получает итоговый ответ и видит статус» лучше отражает потребность, чем «создать страницу answer.html».

4. Полный чек-лист содержания спецификаций

Проверяется применимость каждой строки. Для существенной неприменимой области сохраняется короткое обоснование. Объём документа зависит от сложности и риска изменения.

5. Структура репозитория

Назначение каждой папки и значимого артефакта описано в справочнике структуры.

README.md                    # вход для команды и быстрый запуск
AGENTS.md                    # правила работы людей и агентов
docs/
  overview.md                # цели, контекст, границы, роли
  requirements.md            # прежний адрес → requirements/README.md
  requirements/
    README.md                # карта верхнеуровневых требований
    <area>/*.md              # канонические HLR области
    <area>/assets/           # изображения и приложения области
    shared/assets/           # общие материалы
  glossary.md
  models.md                  # состояния, права, таблицы решений
  questions.md               # канонический реестр открытых вопросов
  decisions.md               # принятые решения и источники
  assumptions.md             # допущения и подтверждение
  applicability.md           # применимость областей чек-листа
openspec/
  config.yaml
  specs/<area>/spec.md        # канонические REQ
  changes/<change>/           # proposal, design, tasks, delta specs
architecture/
  catalog.md                 # элементы, связи, ответственность, владельцы
  technology-stack.md        # стек архитектора, версии и входящие ограничения
  context.md                 # граница и внешние участники
  structure.md               # состав и ответственность
  data.md                    # границы доступа к данным
  runtime.md                 # выбранные взаимодействия
  deployment.md              # среды, узлы, экземпляры
  quality.md                 # механизмы и проверки
  README.md                  # маршрут чтения и вопросы представлений
  concepts.md                # описание сквозных механизмов
contracts/*.schema.json
acceptance/
  scenarios/*.json            # GIVEN/WHEN + именованные проверки
  datasets/*.json             # случаи, входы, ожидаемые результаты
  strategy.md                # стратегия и ограничения приёмки
  evidence/README.md          # формат результатов; сами результаты — CI artifacts
ux/                          # экранные контракты и макеты при применимости
impact/
  stretch-matrix.md           # каноническая матрица протяжки
  reviews/*.md                # результаты применения к изменению
profile/
  profile.json
  schemas/                   # метаданные автоматизируемых REQ, CHECK, данных
scripts/
  reqtool.py
  architecture_profile.py    # выбранные каталоговые ограничения
  markdown_records.py        # контрольные поля Markdown
  doclinks.py                # локальные ссылки
  tests/
generated/                   # необязательные отчёты покрытия и прослеживаемости
templates/                   # авторские шаблоны разделов
.gitlab-ci.yml
requirements-tools.txt

Каталоги — логические места хранения, а не требование создать отдельный файл для каждого абзаца. Большие области делятся на файлы по предметному смыслу. Контракты имеют одного владельца; в другом репозитории указываются точная версия и ссылка на источник.

5.1. Пакеты верхнеуровневых требований

Основная точка входа — docs/requirements/README.md. Это карта областей и ссылки на HLR; нормативный текст, статус и приоритет определяются в одном месте, внутри документа требования. Пакет одной предметной области может содержать несколько HLR и несколько Markdown-файлов. При росте области README становится оглавлением. Названия каталогов задают навигацию, а не дополнительные уровни требований; HLR → REQ остаются двумя уровнями.

В стартовом шаблоне feature1 и feature2 — заготовки областей с HLR в статусе draft. Переименуйте каталоги и заголовки по предметному смыслу, заполните потребность/границы/приёмку и замените заготовочные ID до согласования. После принятия требования его ID сохраняется при переносах. В заполненном репозитории области включают приём жалобы, предварительную обработку, взаимодействие с ведомствами, доставку ответа, аналитику и сквозные гарантии.

docs/requirements/
  README.md                    # карта требований
  <area>/
    README.md                  # одно или несколько HLR, либо оглавление
    <subtopic>.md              # по мере роста области
    assets/
      README.md                # назначение и роль материалов
      images/                  # схемы, иллюстрации, макеты
      attachments/             # формы и исходные документы
  cross-cutting/               # сквозные гарантии при применимости
  shared/assets/               # общие материалы без дублирования

Материал одной области хранится рядом с ней; общий материал имеет одно место хранения. Изображение вставляется по относительной ссылке с содержательной подписью; при наличии сохраняется редактируемый исходник. Приложение сопровождается назначением, источником/версией, связанными HLR и ролью: иллюстрация, источник или нормативная часть. Для нормативного материала укажите обязательные разделы/элементы и отразите существенные обязательства в тексте. Объёмный внешний файл должен иметь ссылку на фиксированную версию. Описание ведётся в обычном Markdown, без отдельного JSON-реестра.

Глоссарий и предметные модели не копируются в пакеты: документы ссылаются на их канонические определения. Сценарии и тестовые данные остаются в acceptance/. Архивы изменений остаются в openspec/changes/archive/, а не внутри действующего каталога HLR.

docs/requirements.md сохраняет прежний адрес и ссылается на новое оглавление. Загрузчик поддерживает прежний файл для существующих репозиториев, но определения HLR нельзя дублировать между ним и каталогом.

6. Источники истины и статусы

Текст HLR и REQ — каноническое обязательство. Метаданные рядом задают ID, статус, ответственного, родителей, происхождение, способ проверки и обязательные аспекты покрытия. Контракт и таблица состояний нормативны только когда спецификация явно ссылается на них.

Markdown — исходный формат авторских документов. JSON сохранён для машинных входов, контрактов и выбранных метаданных автоматических проверок. Файлы в generated/ производны и вручную не редактируются.

Статусы требований: draft, agreed, retired. Согласование действительно только при наличии принятого командой процесса ревью; изменение поля само по себе не является согласованием заказчика. Статусы реализации, проверки и развёртывания хранятся отдельно.

Различайте целевую согласованную спецификацию и наблюдаемое состояние продукта. Версия спецификации не доказывает наличие функции на стенде. Результаты приёмки содержат версии продукта, спецификации, тестов, контрактов и данных.

ID никогда не переиспользуется для другого смысла. Переименование заголовка не меняет ID. Изменение самого ID выполняется как явное изменение со всеми ссылками. Исторические ID допустимы в архиве; уникальность проверяется в действующем снимке.

7. Покрытие многие-ко-многим

Подход к сценариям приёмки

Сценарии конкретизируют требования примерами в духе Specification by Example: одни и те же примеры используются при уточнении требований, обсуждении реализации и приёмке. Методическая основа указана в разделе «Источники и происхождение рекомендаций».

Описывайте исходную ситуацию, действие или событие и наблюдаемый результат (Given–When–Then). Если правило проверяется на нескольких сочетаниях данных, сохраняйте общий сценарий и отдельные случаи с входами и ожидаемыми результатами. Ожидаемый результат должен иметь основание в требованиях и согласованных решениях.

Различайте описание приёмки, метаданные связей и исполняемую проверку. Описание отвечает, какое поведение принимается; метаданные связывают его с REQ, аспектами и данными; код проверки получает фактический результат от системы и сравнивает его с ожидаемым. Наличие сценария и успешный lint не подтверждают поведение продукта.

По умолчанию пишите сценарии в Markdown. JSON используйте для машинных данных и сценариев, которые читает конкретная программа: например, для регулярного расчёта покрытия или исполнения параметризованных проверок. Формат выбирается по потребителю, частоте проверки и цене ошибки. Введённый здесь JSON-профиль — собственное соглашение репозитория; Specification by Example не предписывает его поля или формат хранения.

JSON-сценарии текущего профиля читает reqtool для проверки структуры, связей и объявленного покрытия. Reqtool не исполняет проверки продукта. Исполняемым сценарий становится после подключения к коду проверки системы; результаты фиксируются отдельно для конкретной версии продукта. Markdown-сценарии можно проверять агентским ревью, но текущий reqtool не включает их в автоматическую матрицу покрытия.

Сценарий — связный пользовательский или интеграционный поток. Один сценарий принимает несколько правил; одно правило проверяется несколькими сценариями. Одна проверка также может относиться к нескольким правилам, если её наблюдение подтверждает каждое обязательство.

Связь хранится у конкретной проверки: scenario → check → requirement/aspect. Условия и тестовые случаи показывают, в какой области эта проверка применима. Упоминание требования в предусловии не засчитывается как его проверка.

Аспект — часть обязательства для планирования покрытия: например, для доступа allowed, denied, unchanged_on_denial. Если аспект вводит самостоятельное новое обязательство, его надо включить в нормативный текст или выделить новым REQ.

Критические правила проверяются в успехе, отказе и существенных крайних условиях. Категории сценариев: нормальный поток, альтернативы, границы, некорректные данные, права, повторы, конкуренция, недоступность, восстановление, совместимость, миграция. Применимость и выбор сочетаний объясняются в стратегии приёмки.

Генерируемая матрица показывает объявленное плановое покрытие. Отдельно учитываются реализованные проверки и результаты их исполнения. Даже успешная проверка не доказывает достаточности выбранных сценариев — это предмет ревью.

8. Тестовые данные и оракулы

Каждый набор имеет ID, назначение, версию и случаи с отдельными ID. Случай содержит вход, ожидаемый результат и признак соответствия схеме входа. Для отрицательного случая можно задать valid: false: корректность нарушения схемы тоже проверяется.

Ожидаемый результат выводится из спецификации и согласованных решений. Сохранённый ответ текущей реализации без независимого обоснования не становится эталоном.

Данные синтетические; для случайных данных фиксируется seed; подготовка и очистка воспроизводимы. Состав стенда, часы, справочники, очереди и заглушки фиксируются. Для нагрузочных наборов задаются распределение, размер и допустимые отклонения.

В параметризованных сценариях case_ids ограничивает применимость отдельной проверки. Пустое или несуществующее множество случаев — ошибка. Покрытие связывается с конкретным случаем, а не с именем большого файла.

9. Матрица протяжки изменений

Это правило «изменил X → пересмотри Y». Матрица протяжки задаёт зависимости для анализа влияния изменений. Она отличается от матрицы покрытия и прослеживаемости.

Общие правила: изменение HLR затрагивает детализацию; изменение контракта — потребителей; изменение термина — места его применения; новое требование — проверку и данные; новая область — обзор и навигацию.

Предметные правила: изменение маршрутизации влияет на права, сбор ответов, сроки и аналитические знаменатели. Изменение момента публикации влияет на доступ заявителя, уведомления, статус и показатель отвеченных жалоб.

Канонический источник — impact/stretch-matrix.md; читаемая таблица — impact/stretch-matrix.md. Для каждого затронутого target автор изменения фиксирует updated, checked или not_applicable, объяснение и доказательства. Принудительная правка каждого связанного файла не требуется. Непроверенная позиция остаётся открытой.

Инструмент составляет чек-лист по указанным ID/путям, расширяет связи HLR→REQ и REQ→проверки/данные. Он не делает семантический анализ Git diff и не гарантирует полноты ручного списка. Автор и ревьюер сверяют его с фактическим diff. Новая обнаруженная зависимость добавляется в том же MR.

10. Вопросы, решения, допущения

Вопрос: ID, формулировка, варианты, последствия, ответственный, статус, срок/условие решения, блокируемые требования, блокируемые этапы и ссылка на решение. Разделяйте блокировку реализации конкретного правила и блокировку промышленного запуска.

Решение: ID, выбранный вариант, альтернативы, обоснование, затронутые требования и источник. Реестр фиксирует контекст; обязательства после решения обновляются в спецификации.

Допущение: ID, основание, область действия, последствия ошибки, ответственный, статус и способ подтверждения. Предположение агента не становится молча согласованным требованием.

Рабочее решение при открытом вопросе

Если быстрый ответ недоступен, можно принять рабочий вариант и продолжить реализацию в определённой области. Запишите его в docs/decisions.md со статусом working: выбранный вариант, ответственный, связанный вопрос, затронутые REQ, причины выбора при неполных данных, риски и срок/событие пересмотра. Это принятое к реализации решение, а не неподтверждённое предположение или статус proposed.

В docs/questions.md сохраните статус open и добавьте «Рабочее решение: DEC-ID». Поле «Решение» остаётся пустым до окончательного ответа. Здесь укажите, что ещё требуется выяснить; содержание выбранного варианта не копируйте из реестра решений. REQ описывают действующее поведение и ссылаются на рабочий DEC как источник; проверки соответствуют этому поведению.

Явно пересмотрите блокировки в области рабочего варианта: перечисленные в «Блокирует» REQ по-прежнему отклоняются --ready. Вопрос может разрешать реализацию и сохранять «Этапы: release», чтобы окончательный ответ был получен до выпуска. Для вопроса, который не блокирует выпуск, это также фиксируется явно; наличие рабочего решения само по себе не меняет ни одну блокировку.

После получения ответа подтвердите решение как accepted или замените его новым DEC с сохранением истории. Вопрос становится resolved со ссылкой в поле «Решение»; актуальное поле «Рабочее решение» очищается, история остаётся в тексте. Пересмотрите связанные REQ, проверки и реализацию по матрице влияния. Переход working → accepted сам по себе не является основанием удалить историю или автоматически закрыть вопрос.

11. Работа с OpenSpec

OpenSpec организует спецификации и изменения. Основные файлы сохраняют штатные заголовки ## Purpose, ## Requirements, ### Requirement:, #### Scenario: и нормативные маркеры MUST/SHALL. Метаданные в блоках requirement и подробные JSON-сценарии — дополнительный профиль команды, а не встроенные возможности OpenSpec.

В основном spec.md сценарий представлен коротким примером, относящимся к соответствующему REQ. Для автоматизируемого контроля покрытия проверки и данные находятся в каноническом сценарии JSON. Повествовательный сценарий может быть Markdown. Один ID сценария может упоминаться под несколькими REQ. Линтер проверяет связь каждого такого упоминания с реальной проверкой этого REQ. Смысловую согласованность краткого и полного описания проверяет ревьюер.

Изменение оформляется через openspec/changes/<change>/: предложение, delta specs, дизайн при необходимости, задачи и анализ влияния. До архивирования требуется проверить эффективный результат применения deltas и приёмочные артефакты. Поставленный линтер проверяет основной снимок; полноценное применение активных deltas выполняется OpenSpec и проверяется в отдельной копии/ветке MR. Архив содержит историю, а не второй действующий набор правил.

CLI OpenSpec закрепляется конкретной версией в проекте и обновляется отдельно. Его структурная проверка дополняет профиль команды. Успешное archive не является доказательством приёмки продукта.

12. Последовательность работы

1. Описать цель, контекст, роли, границы и применимость областей.
2. Сформулировать HLR и принципиальные критерии приёмки.
3. Выявить вопросы, допущения, зависимости и обязательные внешние источники.
4. Описать модели, контракты и атомарные правила REQ.
5. Разработать сценарии и независимые ожидаемые результаты вместе с данными.
6. Связать конкретные проверки с REQ и обязательными аспектами.
7. Разобрать влияние изменения; обновить связанные артефакты.
8. Запустить выбранные проверки и выполнить агентское/предметное ревью; при необходимости сформировать отчёты.
9. Согласовать базовую версию и передать в реализацию.
10. Реализовать проверки, выполнить их на заданной версии продукта, сохранить доказательства.
11. Принять изменение, обновить целевую спецификацию, архивировать пакет изменения.

Порядок итеративный: обнаруженный пробел возвращает работу к нужному шагу. Независимые области могут разрабатываться при открытых вопросах в других областях.

13. Готовность и приёмка

Готово к реализации: смысл согласован; существенное поведение определено; родители и источники указаны; блокировки реализации устранены явно, в том числе через принятые рабочие решения с открытыми вопросами; план проверок и необходимые данные существуют; последствия изменения разобраны.

Принято: проверки реализованы и исполнены; версии и среда зафиксированы; обязательные проверки успешны; отклонения явно согласованы; спецификация соответствует итоговому поведению. Для промышленного запуска дополнительно закрыты вопросы правового режима, эксплуатации и реальных интеграций.

Человек проверяет необходимость, смысл, полноту, достаточность сценариев и соответствие потребности. Линтер проверяет структуру, существование связей, формализованные ограничения и объявленное покрытие. Модель может предложить замечания к смыслу, но её предположения требуют подтверждения.

14. Как внедрить стандарт

Начните с вертикального среза «жалоба о неработающем освещении → уточнение категории → поручения двум ведомствам → согласованные ответы → публикация → показатель аналитики». Включите отказ чужому заявителю, повтор отправки, переназначение и сбой уведомления. Такой срез показывает основные типы зависимостей.

Обязательный минимум: HLR, REQ, вопросы, решения, сценарии/проверки, данные, протяжка, линтер ссылок и планового покрытия. Остальные артефакты добавляются по применимости и риску.

Для небольшого изменения достаточно нескольких абзацев и проверок. Для денежных, правовых, межведомственных и миграционных процессов требуется более подробная модель.

15. Источники и происхождение рекомендаций

• NASA: качество требований и матрица проверки — основа критериев атомарности, проверяемости и прослеживаемости.
• OpenSpec: понятия, CLI — структура спецификаций и пакетов изменений.
• Гойко Аджич: Specifying with examples — использование общих примеров для уточнения требований и проверки системы; методическая основа сценариев приёмки. Формат JSON и контрольные поля профиля являются соглашениями этого репозитория.
• jsonschema — валидация метаданных и данных по JSON Schema.

Профиль метаданных, обязательные аспекты покрытия, формат протяжки и поставленные инструменты образуют предлагаемый стандарт репозитория требований. Они не заявляются обязательными правилами перечисленных методологий.

Архитектура в процессе работы

Сначала выделить архитектурно значимые требования и риски; затем сопоставить варианты и зарегистрировать решение DEC-ARCH-*. Обновить общий каталог и выбранные взаимодействия. Существенные обязательства разработки оформить REQ в openspec/specs/architecture/spec.md с проверками реализации. В MR включить изменения нормативного снимка, архитектуры и протяжки; отчёты можно сформировать в CI. При смене решения проверить обратное влияние на исходные гарантии.

Распределение по элементам — связи многие-ко-многим: один REQ имеет основной ответственный элемент и участников, каждый элемент выполняет множество REQ. Само распределение не является покрытием и не доказывает реализацию.

Форматы для агентской разработки

Основная форма авторского материала — Markdown. Агент оценивает смысл и последствия; скрипты проверяют выбранные частые или опасные инварианты. Вопросы, решения, допущения, применимость, протяжка и архитектура редактируются напрямую. Два отчёта generated — необязательный кэш/CI artifacts. Подробный пересмотр всех артефактов: ARTIFACTS.md.

Архитектор заполняет architecture/technology-stack.md до выбора зависимых архитектурных решений. Входящие ограничения получают источник, версию и область применения; обязательность стека закрепляется REQ второго уровня, а представления ссылаются на один технологический базис.