Структура репозитория требований
Каждая строка описывает назначение папки или значимого артефакта. Ссылки ведут к материалам этого самостоятельного репозитория; нормативные определения читаются из исходных документов, а отчёты — из generated/.
Файлы в корне
| Артефакт | Назначение |
|---|---|
| .gitattributes | Правила обработки текстовых файлов и переводов строк. Поддерживают единый формат Markdown, JSON, Python и YAML в разных рабочих окружениях. |
| .gitignore | Исключения Git для окружений, секретов, временных файлов и вычисляемых отчётов. Исходные документы и необходимые материалы требований сохраняются в репозитории. |
| .gitlab-ci.yml | Конфигурация проверок для самостоятельного репозитория: lint --ready, отчёты и тесты инструментов. В составе комплекта файл находится во вложенном каталоге и не подключается корневой конфигурацией. |
| AGENTS.md | Рабочие правила для агентов: сохранение ID, источников истины, связей и выбранных проверок. Применяются при подготовке изменений в этом репозитории. |
| README.md | Чеклист подготовки исходного контекста: цель системы, исходные материалы, предварительная карта возможностей и входящие ограничения. Содержит справочные ссылки и критерий достаточности для начала проработки требований. |
| requirements-tools.txt | Зафиксированные зависимости Python для инструментов проверки. Используется для воспроизводимой установки окружения локально и в CI. |
| STRUCTURE.md | Справочник размещения и назначения папок и значимых артефактов. Помогает выбрать место для нового материала и найти его канонический источник. |
acceptance/
| Папка или артефакт | Назначение |
|---|---|
| acceptance/ | План приёмки: сценарии, проверяемые наблюдения, тестовые данные и порядок получения доказательств. Связи CHECK с REQ показывают запланированное покрытие, а результаты исполнения учитываются отдельно. |
| acceptance/evidence/ | Правила оформления результатов испытаний и ссылок на доказательства. Фактические логи, протоколы и снимки сохраняются как CI artifacts или в согласованном хранилище. |
| acceptance/evidence/README.md | Состав результата реальной проверки: наблюдение, статус, версии продукта/требований/тестов/данных и ссылки на доказательства. Различает успешное исполнение, пропуск и блокировку проверки. |
| acceptance/strategy.md | Риски, категории сценариев, методы проверки, среда и условия готовности к приёмке. Объясняет достаточность выбранного плана и сочетания, для которых требуется дополнительная проверка. |
architecture/
| Папка или артефакт | Назначение |
|---|---|
| architecture/ | Проект архитектуры: границы, части, данные, взаимодействия, размещение и обеспечение качеств. Обязательные правила реализации оформляются как REQ, а причины выбора — как DEC. |
| architecture/README.md | Маршрут чтения архитектуры и вопросы, на которые отвечают представления. Показывает, где искать собственные факты каждого представления и общие определения. |
| architecture/catalog.md | Канонические определения элементов, связей, владельцев данных, распределения REQ и нормативных ограничений. Выбранные каталоговые инварианты проверяются при явном включении архитектурного контроля. |
| architecture/concepts.md | Описание сквозных механизмов, используемых несколькими частями системы. Область действия и ограничения механизма задаются в одном месте. |
| architecture/context.md | Граница системы, внешние участники и взаимодействия через эту границу. Названия и определения элементов берутся из общего каталога. |
| architecture/data.md | Границы данных и объяснение владения, записи и чтения. Владельцы и разрешённые доступы определяются в каталоге, а предметные состояния — в модели и REQ. |
| architecture/deployment.md | Размещение экземпляров по средам, сетевые границы и границы отказа. Неопределённые параметры целевой среды явно связываются с открытыми вопросами. |
| architecture/quality.md | Связь значимых качественных требований с механизмами, решениями и способами проверки. Показывает проектное обоснование, которое должно быть подтверждено испытаниями реализации. |
| architecture/runtime.md | Последовательности существенных взаимодействий, транзакционные границы и отказные ветки. Детализирует выбранные механизмы, а не каждый пользовательский сценарий. |
| architecture/technology-stack.md | Базис технологий, который заполняет архитектор: продукты, версии, обязательность, источники и область применения. Представления и нормативные REQ ссылаются на этот документ, а состав конкретной поставки подтверждается инвентаризацией. |
| architecture/structure.md | Декомпозиция на части, их ответственность и интерфейсы. Объясняет, какие элементы участвуют в выполнении требований, без повторного определения общих фактов каталога. |
docs/
| Папка или артефакт | Назначение |
|---|---|
| docs/ | Контекст продукта, верхнеуровневые требования и общие предметные определения. Здесь также находятся вопросы, решения, допущения и оценка применимости областей требований. |
| docs/applicability.md | Оценка применимости областей чек-листа: что рассмотрено, что применимо и где находятся соответствующие артефакты. Обоснование пишется в Markdown; pending означает незавершённое рассмотрение области. |
| docs/assumptions.md | Допущения, на которых основаны требования и проектные решения. Для каждого указываются основания, риск, способ подтверждения и при необходимости блокируемые требования. |
| docs/decisions.md | Предлагаемые, рабочие и окончательно принятые решения с обоснованием, альтернативами и последствиями. Архитектурные DEC-ARCH хранятся в том же реестре, чтобы у выбора был один источник. |
| docs/glossary.md | Единые определения предметных терминов и допустимых названий. Другие документы ссылаются на эти определения вместо создания собственных трактовок. |
| docs/models.md | Общие модели сущностей, состояний, прав и правил расчёта. Спецификации явно указывают, какие части модели являются нормативными для соответствующего REQ. |
| docs/overview.md | Проблема, ожидаемый результат, пользователи, контекст и границы системы. Определяет, какие возможности входят в текущую область требований и какие требуют дальнейшей детализации. |
| docs/questions.md | Открытые и разрешённые вопросы с вариантами, влиянием и ответственными. Контрольные поля задают блокировки и раздельные ссылки на рабочий вариант и окончательный ответ; рабочий вариант сохраняет вопрос открытым. |
| docs/requirements/ | Канонические HLR, сгруппированные по предметным областям и сквозным гарантиям. Оглавление помогает читать комплект; определения и статусы требований находятся в документах пакетов. |
| docs/requirements.md | Ссылка с прежнего адреса на оглавление каталога requirements/. В новом комплекте не содержит собственных определений HLR. |
| docs/requirements/README.md | Карта областей и ссылки на канонические HLR. Навигационная группировка не добавляет уровня требований и не дублирует их статусы или приоритеты. |
| docs/requirements/feature1/ | Первая заготовка предметной области с draft-требованием HLR-FEATURE1-001. Переименуйте область по смыслу возможности и заполните цель, границы и приёмку до согласования. |
| docs/requirements/feature1/README.md | Первая заготовка предметной области с draft-требованием HLR-FEATURE1-001. Канонические определения HLR-FEATURE1-001 содержат метаданные, результат, границы и приёмку. |
| docs/requirements/feature1/assets/ | Материалы, принадлежащие одному пакету HLR, с описанием их происхождения и нормативной роли. Иллюстрации и приложения размещаются раздельно. |
| docs/requirements/feature1/assets/README.md | Описание или перечень материалов: назначение, источник/версия, связанные HLR и роль. Позволяет отличить поясняющую картинку от нормативного источника. |
| docs/requirements/feature1/assets/attachments/ | Приложения предметной области: формы и исходные документы. Для нормативного источника фиксируются версия и применимые разделы. |
| docs/requirements/feature1/assets/attachments/README.md | Назначение приложений области и правила фиксации их источника, версии и применимых разделов. Связывает исходные документы с описанием материалов и нормативными требованиями. |
| docs/requirements/feature1/assets/images/ | Изображения предметной области: схемы, иллюстрации и макеты. Подпись и описание материала определяют его назначение и обязательность визуальных деталей. |
| docs/requirements/feature1/assets/images/README.md | Правила размещения и оформления изображений области. Описывает подписи, относительные ссылки и сохранение редактируемого исходника. |
| docs/requirements/feature2/ | Вторая заготовка предметной области с draft-требованием HLR-FEATURE2-001. Она показывает, как добавлять независимые пакеты с собственными требованиями и материалами. |
| docs/requirements/feature2/README.md | Вторая заготовка предметной области с draft-требованием HLR-FEATURE2-001. Канонические определения HLR-FEATURE2-001 содержат метаданные, результат, границы и приёмку. |
| docs/requirements/feature2/assets/ | Материалы, принадлежащие одному пакету HLR, с описанием их происхождения и нормативной роли. Иллюстрации и приложения размещаются раздельно. |
| docs/requirements/feature2/assets/README.md | Описание или перечень материалов: назначение, источник/версия, связанные HLR и роль. Позволяет отличить поясняющую картинку от нормативного источника. |
| docs/requirements/feature2/assets/attachments/ | Приложения предметной области: формы и исходные документы. Для нормативного источника фиксируются версия и применимые разделы. |
| docs/requirements/feature2/assets/attachments/README.md | Назначение приложений области и правила фиксации их источника, версии и применимых разделов. Связывает исходные документы с описанием материалов и нормативными требованиями. |
| docs/requirements/feature2/assets/images/ | Изображения предметной области: схемы, иллюстрации и макеты. Подпись и описание материала определяют его назначение и обязательность визуальных деталей. |
| docs/requirements/feature2/assets/images/README.md | Правила размещения и оформления изображений области. Описывает подписи, относительные ссылки и сохранение редактируемого исходника. |
| docs/requirements/shared/ | Общие материалы нескольких пакетов HLR. Документы областей ссылаются на один источник вместо копирования файлов. |
| docs/requirements/shared/assets/ | Файлы и описание общих материалов: их назначение, происхождение и нормативная роль. Глоссарий и предметные модели сохраняют отдельные канонические документы. |
| docs/requirements/shared/assets/README.md | Описание или перечень материалов: назначение, источник/версия, связанные HLR и роль. Позволяет отличить поясняющую картинку от нормативного источника. |
generated/
| Папка или артефакт | Назначение |
|---|---|
| generated/ | Вычисляемые отчёты покрытия и прослеживаемости. Это необязательный кэш или CI artifacts; авторские требования здесь не редактируются. |
| generated/coverage.md | Вычисляемая матрица планового покрытия REQ и аспектов через CHECK и случаи данных. Выявляет объявленные пробелы; не подтверждает исполнение проверок. |
| generated/traceability.md | Вычисляемый индекс связей HLR → REQ для навигации и ревью. Связи определяются в метаданных спецификаций и здесь вручную не редактируются. |
handbook/
| Папка или артефакт | Назначение |
|---|---|
| handbook/ | Методическая инструкция, включённая в самостоятельный репозиторий. Объясняет качество требований, форматы, архитектурный подход и выбор автоматизации. |
| handbook/ARCHITECTURE.md | Место архитектуры относительно HLR/REQ, вопросы представлений и распределение источников истины. Объясняет переход от проектного решения к обязательству разработки. |
| handbook/ARTIFACTS.md | Обоснование формы каждого артефакта и выбора автоматизации. Фиксирует, где достаточно Markdown и агентского ревью, а где нужен машинный формат или вычисляемый отчёт. |
| handbook/FORMAT.md | Канонические источники, выбранные контрольные поля и смысл связей между артефактами. Объясняет, какую часть Markdown проверяет скрипт и какую оценивает ревьюер. |
| handbook/GUIDE.md | Основная инструкция: качество требований, состав комплекта, два уровня детализации, процесс изменения и приёмка. Содержит чек-лист применимости и порядок наполнения пакетов HLR. |
| handbook/TOOLS.md | Команды проверки, условия готовности, формирование отчётов и ограничения автоматизации. Помогает запускать необходимые проверки и правильно читать результат. |
impact/
| Папка или артефакт | Назначение |
|---|---|
| impact/ | Знания о влиянии изменений и сохранённые результаты пересмотра. Матрица задаёт «изменил X → пересмотри Y», а конкретный разбор фиксирует выводы и основания. |
| impact/stretch-matrix.md | Авторские правила обязательного пересмотра при изменении ID или путей. Причина каждой зависимости объясняет, почему затронутый материал нужно пересмотреть. |
openspec/
| Папка или артефакт | Назначение |
|---|---|
| openspec/ | Нормативные спецификации REQ и жизненный цикл их изменений. Текущий согласованный снимок отделён от предложений, дельт и архива. |
| openspec/config.yaml | Настройки OpenSpec, схема процесса и контекст для подготовки изменений. Инструкции конфигурации дополняют нормативные документы, а не заменяют их. |
profile/
| Папка или артефакт | Назначение |
|---|---|
| profile/ | Конфигурация выбранных механических проверок и схемы их метаданных. Строгость контроля определяется проверяемыми инвариантами, частотой проверки и ценой ошибки. |
| profile/profile.json | Режим профиля, рассматриваемые области и включение выбранных архитектурных проверок. Это конфигурация инструмента, а не описание поведения продукта. |
| profile/schemas/ | JSON Schema для настроек профиля, метаданных требования, сценария и набора данных. Эти схемы проверяют устройство артефактов, а предметные входные данные описываются в contracts/. |
| profile/schemas/dataset.schema.json | Форма набора DATA и случаев CASE с входами, эталонами и условиями подготовки. Предметный формат входа проверяется отдельной схемой из contracts/. |
| profile/schemas/profile.schema.json | Допустимые поля и значения настройки профиля. Защищает от неоднозначной или ошибочной конфигурации проверки. |
| profile/schemas/requirement.schema.json | Форма контрольных метаданных HLR/REQ: ID, статус, владелец, связи, риск и аспекты проверки. Нормативный текст требования остаётся в Markdown. |
| profile/schemas/scenario.schema.json | Форма метаданных приёмочного сценария и CHECK, включая ссылки на обязательства и данные. Проверяет устройство плана, а не достаточность его наблюдений. |
scripts/
| Папка или артефакт | Назначение |
|---|---|
| scripts/ | Инструменты проверки комплекта, расчёта отчётов и анализа влияния. Скрипты проверяют выбранные формальные условия; содержательное ревью остаётся отдельной работой. |
| scripts/architecture_profile.py | Чтение каталога и проверка выбранных архитектурных инвариантов, ссылок и запретов. Диаграммы, достаточность механизмов и соответствие кода оцениваются отдельным ревью и испытаниями. |
| scripts/doclinks.py | Помощник оформления локальных ссылок в Markdown. Учитывает расположение документа и пропускает кодовые блоки, чтобы команды и примеры не меняли смысл. |
| scripts/markdown_records.py | Чтение контрольных полей Markdown-реестров и таблиц. Позволяет проверять статусы, блокировки и связи без преобразования авторских документов в JSON. |
| scripts/reqtool.py | Основной CLI: структурный lint, проверки готовности, отчёты покрытия/прослеживаемости и план влияния изменения. Читает канонические Markdown-источники и выбранные машинные метаданные. |
| scripts/tests/ | Регрессионные и отказные проверки инструментов репозитория. Подтверждают обнаружение ошибок метаданных, связей и форматов; это не испытания продукта. |
| scripts/tests/test_architecture.py | Проверки выбранных ограничений каталога, владельцев и доступа к данным. Выявляют нарушения проектной модели, без анализа реального кода или прав среды. |
| scripts/tests/test_doclinks.py | Проверки формирования относительных локальных ссылок. Защищают от повреждения кода, команд и уже оформленных ссылок. |
| scripts/tests/test_markdown_records.py | Проверки чтения Markdown-реестров, контрольных значений и блокировок. Подтверждают обнаружение неоднозначных полей и ошибочных ссылок. |
| scripts/tests/test_reqtool.py | Отказные проверки связей, покрытия, готовности и отчётов основного инструмента. Подтверждают, что ошибочный план не считается корректным. |
| scripts/tests/test_requirement_packages.py | Проверки вложенных пакетов HLR, исключения приложений, уникальности ID и влияния файла с несколькими HLR. Также подтверждают работу без прежнего requirements.md. |
templates/
| Папка или артефакт | Назначение |
|---|---|
| templates/ | Заготовки документов, метаданных и разделов для создания новых артефактов. Их копируют в предметную область, заполняют и присваивают собственные ID. |
| templates/acceptance-strategy.md | Заготовка риск-ориентированного плана приёмки, категорий сценариев и доказательств. Объясняет выбор проверок и условий их выполнения. |
| templates/architecture-constraint.md | Заготовка обязательного архитектурного REQ с областью действия и методом проверки реализации. Отличает нормативный запрет от предпочтения проектировщика. |
| templates/architecture-decision.md | Архитектурное решение DEC-ARCH с требованиями-основаниями, альтернативами и компромиссами. Использует общий реестр решений. |
| templates/architecture-view.md | Заготовка представления с вопросом, областью, собственными фактами и ссылками на общие определения. Помогает отделить представление от дублирующей модели. |
| templates/assumption.md | Карточка допущения с основанием, риском и способом подтверждения. При необходимости задаёт блокируемые требования. |
| templates/change-proposal.md | Предложение изменения: проблема, ожидаемый результат, область и влияние. Объясняет, зачем менять текущие обязательства. |
| templates/contract.md | Состав API/событийного контракта: структура данных, протокол, ошибки, безопасность, версии и совместимость. Машинная схема дополняет этот текст. |
| templates/dataset.json | Машинные метаданные DATA и CASE с входами, эталонами, подготовкой и очисткой. Контракт входа указывается явно. |
| templates/decision.md | Карточка решения с обоснованием, альтернативами, последствиями и источником. Замещение принятого выбора оформляется ссылкой на предыдущее решение. |
| templates/high-level.md | Карточка HLR: потребность, пользователи, результат, границы, основные потоки и критерии успеха. Выбранные метаданные обеспечивают идентификацию и связи. |
| templates/impact-review.md | Разбор конкретного изменения с затронутыми материалами, статусами и основаниями выводов. Заполняется после формирования плана пересмотра. |
| templates/impact-rule.md | Правило «изменил X → пересмотри Y» с триггерами и причиной каждой зависимости. Сохраняет авторские знания о влиянии изменения. |
| templates/migration.md | План изменения данных и совместимости, включая включение, проверку и откат. Применяется при переходе между версиями продукта или справочников. |
| templates/models.md | Заготовка предметных сущностей, состояний, ролей и таблиц решений. Общие определения формируются один раз и используются несколькими REQ. |
| templates/nfr.md | Форма качественного требования: метрика, порог, условия и способ измерения. Помогает заменить неопределённые обещания проверяемым обязательством. |
| templates/overview.md | Структура обзора системы с проблемой, целями, контекстом и границами. Заполняется до подробных правил поведения. |
| templates/question.md | Карточка вопроса с контекстом, вариантами, влиянием и выбранными полями блокировки. Разрешённый вопрос связывается с решением DEC. |
| templates/scenario.json | Машинные метаданные сценария с GIVEN/WHEN, CHECK, ссылками на REQ и DATA. Заготовочные ID заменяются ID конкретной проверки. |
| templates/screen.md | Постановка экрана с действиями, состояниями, ошибками, доступностью и связанными REQ. Макет сопровождается описанием обязательных деталей. |
| templates/spec.md | Заготовка нормативного REQ в формате OpenSpec со сценарием и контрольными метаданными. Используется для детализации обязательства верхнего уровня. |
Папки, создаваемые по мере наполнения
В Git сохраняются папки с файлами. Следующие каталоги появятся после добавления соответствующих артефактов; пустые папки специально создавать не требуется.
| Папка | Назначение |
|---|---|
| acceptance/scenarios/ | Приёмочные сценарии с GIVEN/WHEN и именованными CHECK. Один сценарий может проверять несколько REQ, а каждая CHECK задаёт аспекты обязательства, ожидаемый результат и способ проверки. |
| acceptance/datasets/ | Исходные состояния и эталоны приёмочных сценариев, сгруппированные в наборы DATA и случаи CASE. Наборы указывают контракт входа, подготовку и очистку данных. |
| contracts/ | Машинные схемы предметных входов и представлений данных, используемых сценариями. Они задают проверяемые форматы; полный интеграционный контракт дополнительно описывает протокол, авторизацию, версии и ошибки. |
| ux/ | Экранные контракты, макеты и условия устойчивости интерфейса. Поведение, состояния и доступность описываются текстом и связываются с REQ, а изображения поясняют выбранные визуальные детали. |
| openspec/specs/ | Действующие спецификации по областям поведения и ограничений. Каждый REQ содержит нормативный текст, выбранные метаданные и сценарии. |
| openspec/changes/ | Отдельные пакеты изменений: предложение, проектный подход, задачи и дельты спецификаций. Они описывают переход к новому состоянию, а не заменяют действующий снимок. |
| impact/reviews/ | Разборы конкретных изменений с перечнем затронутых артефактов, статусами пересмотра и основаниями выводов. Незакрытые обязательные позиции учитываются выбранной проверкой готовности. |