Add architecture decision record templates

2026-05-24 14:35:35 +03:00
parent dc49b3497b
commit e45e1db002
4 changed files with 238 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Architecture Decision Records (ADR)
+
+Журнал значимых архитектурных и инфраструктурных решений по серверу.
+Одна запись — одно решение. ADR пишем **постфактум**, когда изменение
+уже сделано: идеи, планы и обсуждения живут в [`../drafts/`](../drafts),
+а в ADR попадает только то, что реализовано. Записи **неизменяемы**:
+передумали → не правим старую, а заводим новую и помечаем старую.
+
+Чем ADR отличается от журналов в `../drafts/`: drafts — оперативная
+хроника и черновики («что делаю / собираюсь сделать»), ADR — фиксация
+выбора и его обоснования («почему сделал так, а не иначе»).
+
+Главная ценность записи — сохранить **почему**: намерение и причинность.
+Это важнее аккуратности оформления и полноты остальных секций.
+
+## Когда заводить ADR
+
+- Выбор технологии или инструмента (Caddy vs Nginx, restic vs borg).
+- Структурные решения (схема бэкапов, организация плейбуков, сеть).
+- Решения с долгосрочными последствиями или дорогим откатом.
+- **Намеренный отказ** от очевидного подхода — чтобы потом не
+  переоткрывать «а почему мы не сделали X».
+
+Не заводить для рутины (бамп версии образа, добавление сервиса по
+накатанной схеме) и того, что и так видно из кода и git.
+
+## Соглашения
+
+- **Имя файла = идентификатор:** `ADR-ГГГГ-ММ-ДД-kebab-slug.md`.
+  Идентификатор — имя без `.md` (например `ADR-2026-05-24-adr-process`).
+  Slug — латиницей.
+- **Дата** — когда изменение реально сделано (можно задним числом, а не
+  дата оформления записи).
+- Несколько ADR за один день различаются по slug.
+- **Заголовок в файле:** `# Человеческий заголовок` (без даты и ID — они
+  в имени файла и в строке «Дата»).
+- Секция **«Рассмотренные варианты» — опциональна**: оставляй её, только
+  если альтернативы реально рассматривались.
+- Шаблон новой записи — [`template.md`](template.md).
+- Исключение: основополагающая мета-запись о самом процессе ADR
+  использует дату-сентинел `0000-00-00`, чтобы всегда оставаться в самом
+  низу списка. Реальные записи такую дату не используют.
+
+## Статусы
+
+Активная запись статуса **не имеет**. Статус появляется, только когда
+запись теряет силу, и значений всего два:
+
+- `заменено на ADR-ГГГГ-ММ-ДД-slug` — решение пересмотрено новой ADR.
+- `устарело` — решение потеряло смысл и замены нет.
+
+## Замена и устаревание
+
+1. Заводим новую ADR; в её «Контексте» — строка
+   «Заменяет ADR-ГГГГ-ММ-ДД-slug».
+2. В старой ADR добавляем строку `- Статус: заменено на ADR-…` сразу под
+   датой. Тело не трогаем — это часть истории.
+3. Обновляем статус старой записи в индексе ниже.
+
+## Список записей
+
+Новые сверху.
+
+| Дата       | Запись                                                                          | Статус |
+| ---------- | ------------------------------------------------------------------------------- | ------ |
+| 0000-00-00 | [Вести историю решений в виде ADR](ADR-0000-00-00-record-architecture-decisions.md) | —      |