Наглядность корпоративных стандартов¶

Требования этого документа применяются к нормативным и справочным материалам и авторам этого объединённого репозитория стандартов. Они не входят в вычисляемый набор требований прикладного проекта и не регулируют его документацию. Уровни обязательности определены в корневом README.md.

DOC-CLR-001. Явная область документа¶

Уровень: MUST

Применяется к: каждому нормативному документу

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

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

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

Читатель и ИИ-агент должны определить применимость документа до разбора отдельных требований.

Проверка¶

review названия и вводной части;
проверка отсутствия нормативных обязанностей без ID во введении;
сопоставление области со смежными документами.

Исключения¶

Не допускаются.

DOC-CLR-002. Одна проверяемая норма на требование¶

Уровень: MUST

Применяется к: каждому нормативному требованию

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

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

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

Атомарные требования позволяют однозначно ссылаться на норму, проверять её и оформлять исключения.

Проверка¶

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

Исключения¶

Связанные условия одного результата могут оставаться в одном требовании, если их раздельное выполнение не имеет смысла.

DOC-CLR-003. Единая терминология¶

Уровень: MUST

Применяется к: всем материалам репозитория

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

Необщеупотребимый термин должен быть определён при первом использовании либо ссылаться на единое определение. Синонимы не должны использоваться для стилистического разнообразия, если они могут изменить толкование.

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

Различающиеся названия создают ложные сущности и мешают машинному сопоставлению требований.

Проверка¶

поиск вариантов ключевых терминов по репозиторию;
сопоставление документа с корпоративной таблицей полей;
review новых сокращений и определений.

Исключения¶

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

DOC-CLR-004. Обоснованное использование визуализации¶

Уровень: SHOULD

Применяется к: материалам со сложными связями

Таблицу или схему следует добавлять, если она делает существенно понятнее:

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

Для простого линейного правила визуализацию добавлять не следует. Следует использовать минимальную достаточную форму: таблицу для сопоставления, flowchart для потока, sequence diagram для взаимодействия во времени и дерево для иерархии.

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

Визуализация полезна для отношений, но дублирует и усложняет простое требование.

Проверка¶

review необходимости каждого визуального материала;
проверка соответствия выбранного типа изображаемой связи;
проверка отсутствия декоративных элементов без смысловой нагрузки.

Исключения¶

Проза MAY использоваться, если она передаёт связь не менее однозначно и компактно.

DOC-CLR-005. Нормативный текст имеет приоритет¶

Уровень: MUST

Применяется к: таблицам, схемам и другим справочным представлениям

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

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

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

Несколько равноправных представлений одного правила создают неоднозначный источник правды.

Проверка¶

сопоставление каждого элемента схемы или таблицы с ID требования;
review пометки о ненормативном статусе;
проверка ссылок на нормативные документы.

Исключения¶

Машинно-проверяемая схема может быть нормативной только после отдельного требования, явно устанавливающего такой статус и порядок версионирования.

DOC-CLR-006. Отдельное хранение примеров¶

Уровень: MUST

Применяется к: примерам кода, конфигурации, payload и интеграции

Реализационные примеры должны храниться только в верхнеуровневом каталоге examples/, отдельно от docs/ и schemas/. В нормативном документе допускается только ссылка на пример.

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

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

Физическое разделение снижает вероятность принять частную реализацию за обязательный или готовый к использованию контракт.

Проверка¶

проверка расположения файлов;
проверка предупреждения, ID и ограничений;
secret scanning и review тестовых данных.

Исключения¶

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

DOC-CLR-007. Запрет прямого переиспользования примеров¶

Уровень: MUST NOT

Применяется к: ИИ-агентам и разработчикам, использующим examples/

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

Пример запрещено позиционировать как production-ready, универсальный шаблон или рекомендуемую конфигурацию по умолчанию. ИИ-агенту запрещено использовать пример иначе чем для понимания намерения требования и запрещено выбирать реализацию на его основании.

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

Пример намеренно показывает ограниченный сценарий и быстро устаревает относительно библиотек, инфраструктуры и контекста безопасности.

Проверка¶

review текста примера и ссылок на него;
review изменений прикладного проекта на механическое копирование;
проверка отдельного обоснования выбранной реализации.

Исключения¶

Переиспользуемый артефакт должен быть оформлен не как пример, а как отдельный версионируемый шаблон с владельцем, тестами и явно определённым контрактом.

DOC-CLR-008. Синхронное обновление представлений¶

Уровень: MUST

Применяется к: изменению требования, связанного со справочными материалами

При изменении смысла, полей или границ требования связанные таблицы, схемы, JSON Schema и примеры должны быть проверены и обновлены в том же merge request.

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

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

Устаревший справочный материал убедительно демонстрирует уже недействующее поведение и опаснее отсутствующего материала.

Проверка¶

поиск ID изменённого требования по репозиторию;
проверка связанных файлов в diff;
автоматическая проверка локальных ссылок и ссылочных ID.

Исключения¶

Если синхронное обновление невозможно, справочный материал должен быть удалён или явно помечен как устаревший в том же merge request.

DOC-CLR-009. Минимально достаточный набор требований¶

Уровень: MUST

Применяется к: добавлению или пересмотру нормативного требования

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

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

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

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

Проверка¶

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

Исключения¶

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

DOC-CLR-010. Уровень обязательности по последствиям¶

Уровень: MUST

Применяется к: выбору MUST, SHOULD или MAY

MUST или MUST NOT должны использоваться, если нарушение создаёт хотя бы одно из следующих последствий:

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

Для оптимального, но заменимого способа снижения риска должен использоваться SHOULD или SHOULD NOT. Допустимый вариант, не требующий обоснования выбора, должен использовать MAY.

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

Уровень, связанный с последствиями нарушения, направляет ресурсы на наиболее существенные риски.

Проверка¶

сопоставление уровня с перечисленным последствием;
проверка наличия допустимой альтернативы;
review стоимости обязательного контроля относительно регулируемого риска.

Исключения¶

Корпоративно выбранный протокол, формат или компонент MAY иметь уровень MUST, если единообразие само является явно названным архитектурным решением.

DOC-CLR-011. Положительные признаки применимости¶

Уровень: MUST

Применяется к: области нормативного документа и отдельного требования

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

Если признак представлен в .standards/standards.yaml, документ должен использовать термин и семантику из STD-MAN-003.

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

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

Проверка¶

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

Исключения¶

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

DOC-CLR-012. Контракт вместо способа реализации¶

Уровень: MUST

Применяется к: проектированию нормативного требования

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

Выбранная технология может быть обязательной только когда она является интеграционной границей или явно принятым корпоративным решением; это основание должно быть названо в области или обосновании требования.

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

Контракт сохраняет свободу выбрать наиболее дешёвую подходящую реализацию и не заставляет проекты поддерживать лишний toolchain.

Проверка¶

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

Исключения¶

Не допускаются без явно принятого корпоративного технологического решения.

DOC-CLR-013. Удаление требования без повторного использования ID¶

Уровень: MUST

Применяется к: требованию, которое больше не регулирует необходимый риск или решение

Устаревшее или избыточное требование должно быть удалено либо сужено, а не сохраняться только ради стабильности текста. Освобождённый ID не должен назначаться новому смыслу и должен быть добавлен в catalog/retired-ids.json. Все ссылки на удалённый ID должны быть удалены или заменены в том же изменении.

Нормативное изменение смысла, уровня или области сохраняемого ID должно быть явно указано в результате работы.

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

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

Проверка¶

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

Исключения¶

Историческая ссылка MAY сохраняться в журнале изменений с явным статусом удалённого требования.