Architecture Decision Records

ADR фиксирует значимое архитектурное решение: контекст, само решение, отклонённые альтернативы и причины. Назначение — чтобы через год вопрос «а почему бы не…» имел письменный ответ, а пересмотр решения начинался с его записанных аргументов, а не с чистого листа.

Правила

• ADR неизменяемы. Запись не редактируется задним числом. Пересмотр решения — новый ADR; старый получает статус Superseded by ADR-N.
• ADR — не документация. Основная документация описывает систему как она есть; ADR описывает, почему она такая. Устаревший ADR не «чинится» — он остаётся историческим фактом.
• Порог значимости: решение попадает в ADR, если его пересмотр затронет несколько компонентов или потребует миграции данных/контракта.

Шаблон

# ADR-NNN: <решение одной строкой>

Status: Accepted | Superseded by ADR-NNN
Date: YYYY-MM-DD

## Контекст
## Решение
## Отклонённые альтернативы
## Последствия

Реестр

ADR	Решение	Статус
001	Декларативное desired state вместо императивных команд	Accepted
002	Агент устанавливает соединение с backend	Accepted
003	PostgreSQL как единственное хранилище	Accepted
004	Без Event Sourcing и replay-реконструкции	Accepted
005	Pluggable KMS вместо обязательного Vault	Accepted
006	Доступ через группы; цепочка — свойство инбаунда	Accepted
007	Неймспейс движка в контракте без generic-абстракции	Accepted
008	Монорепозиторий	Accepted
009	Админы и клиенты — раздельные популяции	Accepted
010	Саморегистрация клиентов: режимы и креденшелы	Accepted
011	Recovery-слот мастер-ключа (модель LUKS)	Accepted