Архитектурные решения и исключения¶

Требования применяются к Architecture Decision Record (ADR), которыми проект фиксирует архитектурное решение или исключение из стандартов. Уровни обязательности определены в корневом README.md.

DEV-ADR-001. Содержание ADR-исключения¶

Уровень: MUST

Применяется к: каждому ADR, оформляющему исключение из требования

ADR должен начинаться с YAML front matter:

id — непустой стабильный идентификатор ADR;
status — одно из proposed, accepted, rejected, superseded или expired;
requirement_id — точный нарушаемый ID требования;
expires_on — последний день действия исключения по UTC в формате YYYY-MM-DD.

Основной текст должен содержать контекст и причину решения, оценённые риски, компенсирующие меры, владельца и проверяемые условия пересмотра. Manifest должен содержать только requirement_id как ключ сверки и путь к ADR; статус, срок и содержание решения не должны переноситься в manifest.

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

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

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

Проверка¶

review наличия и непустого содержания перечисленных частей решения;
scripts/standards.py validate или check;
сопоставление ID с manifest и зафиксированной версией стандартов;
review рисков, мер, владельца и условия пересмотра.

Исключения¶

Не допускаются для ADR, указанного в exceptions manifest.

DEV-ADR-002. Жизненный цикл ADR¶

Уровень: MUST

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

ADR должен храниться в Git вместе с проектом, иметь стабильный идентификатор, уникальный среди ADR проекта, и один из однозначно определённых статусов: proposed, accepted, rejected, superseded или expired. Для ADR-исключения идентификатор и статус должны находиться в front matter по DEV-ADR-001. Заменённый ADR должен иметь статус superseded и ссылаться на новое решение. ADR-исключение после даты expires_on должно иметь статус expired.

Объект exceptions manifest должен ссылаться только на ADR со status: accepted, совпадающим requirement_id и не прошедшей датой expires_on. Нарушение любого из этих условий должно блокировать validate и check до принятия нового решения либо удаления исключения.

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

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

Проверка¶

проверка front matter, уникальности ID, срока и истории файла;
проверка ссылки для заменённого ADR;
негативный тест истёкшего или непринятого исключения.

Исключения¶

Формат и язык ADR, не оформляющего исключение, выбирает проект. Для ADR-исключения формат и язык основного текста также выбирает проект, но YAML front matter из DEV-ADR-001 сохраняется без переименования полей и значений.

DEV-ADR-003. Связь решения с изменением¶

Уровень: MUST

Применяется к: изменению, которое требует ADR

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

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

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

Проверка¶

проверка ссылки из merge request;
сопоставление статуса ADR и изменённых файлов;
проверка реализации компенсирующих мер.

Исключения¶

Не допускаются, когда требование прямо требует ADR до изменения.

DEV-ADR-004. Условия обязательного архитектурного решения¶

Уровень: MUST

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

Проект должен принять ADR до merge реализации, если изменение:

создаёт, удаляет, разделяет или объединяет независимо развёртываемые компоненты;
меняет владельца, источник истины, write boundary, транзакционную границу или модель согласованности устойчивых данных;
меняет обязательное взаимодействие с синхронного на асинхронное или обратно;
вводит обязательную межсервисную зависимость либо coordinated deployment;
меняет гарантии восстановления обязательного эффекта;
осознанно ухудшает утверждённый SLO, security-границу или recovery contract.

ADR должен иметь status: accepted до merge изменения и быть связан с merge request по DEV-ADR-003.

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

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

Проверка¶

сопоставление изменённых deployment units, contracts и data ownership с ADR;
проверка статуса ADR и ссылки из merge request;
негативный тест policy gate для изменения без принятого ADR.

Исключения¶

Изолированный experiment вне production MAY не иметь принятого ADR, если не публикует контракт, не использует production-данные и имеет срок удаления. Экстренное изменение выполняется по OPS-INC-003.

DEV-ADR-005. Альтернативы и компромиссы¶

Уровень: MUST

Применяется к: ADR, обязательному по DEV-ADR-004

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

Для выбранного и отклонённых вариантов должны быть сопоставлены затронутые доступность, latency или throughput, безопасность, изменяемость, стоимость эксплуатации и recovery — только в той части, где характеристика меняется. ADR должен содержать измеримый критерий принятия выбранного варианта и условие пересмотра решения.

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

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

Проверка¶

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

Исключения¶

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

DEV-ADR-006. Сценарий критичной характеристики¶

Уровень: MUST

Применяется к: ADR, меняющему характеристику, которая ограничивает release по SLO, security contract, capacity limit или recovery contract

ADR должен определить сценарий с полями source, stimulus, environment, artifact, response и measure. measure должен задавать численный порог, закрытый набор допустимых результатов либо другое объективно проверяемое условие. ADR должен ссылаться на проверку сценария и назначение этой проверки для merge или release.

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

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

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

Проверка¶

структурная проверка наличия полей сценария;
controlled test указанного stimulus в указанном environment;
сопоставление результата с measure и обязательным gate.

Исключения¶

Сценарий MAY ссылаться на действующий SLO, threat model или recovery test, если источник содержит все перечисленные поля и зафиксированную версию.