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,54 @@
+# Вести историю решений в виде ADR
+
+- Дата: 0000-00-00
+
+> Основополагающая запись о самом процессе ADR. Дата-сентинел
+> `0000-00-00` (фактически создана 2026-05-24) — исключение: так запись
+> всегда остаётся в самом низу списка и не путается с реальными
+> изменениями.
+
+## Контекст
+
+Сервер развивается итеративно: меняются прокси, схема бэкапов, набор
+сервисов, провайдер хостинга. Решения принимаются по одному, часто с
+неочевидными компромиссами под ресурсы сервера и стоимость. Через
+несколько месяцев мотивация забывается, и возникает риск «переоткрыть»
+уже отвергнутый вариант или сломать то, что было сделано осознанно.
+
+Журналы в `docs/drafts/` фиксируют хронологию и черновики, но не
+обоснование выбора — по ним не видно, какие альтернативы отвергнуты и
+почему.
+
+## Рассмотренные варианты
+
+- **ADR (отдельный файл на решение)** — стандартный формат, каждая
+  запись неизменяема, видно эволюцию через накопление и замену записей.
+- **Один changelog-файл** — проще вести, но правки затирают историю
+  рассуждений, и формат расплывается со временем.
+- **Ничего, держать в голове / в git-сообщениях** — нулевые затраты,
+  но обоснование теряется, а git-история не отвечает на вопрос «почему».
+
+## Решение
+
+Заводим каталог `docs/adr/` с записями в формате ADR (Nygard + блок
+«Рассмотренные варианты»). Идентификатор записи — датовый,
+`ADR-ГГГГ-ММ-ДД-slug`: дата (когда изменение реально сделано) сразу
+видна в списке и позволяет оформлять записи задним числом. ADR пишем
+постфактум, поэтому жизненный цикл сведён к двум статусам у потерявших
+силу записей — `заменено на` и `устарело`; идеи и планы остаются в
+`docs/drafts/`.
+
+Формат и процесс описаны в [`README.md`](README.md), шаблон — в
+[`template.md`](template.md). Для единообразия заполнение
+автоматизировано скиллом `adr` (`.claude/skills/adr/`).
+
+## Последствия
+
+- `+` Сохраняется обоснование решений и отвергнутые альтернативы.
+- `+` Датовый ID даёт хронологию «из коробки» и не мешает оформлять
+  записи задним числом.
+- `+` Единый формат: записи делает человек или агент по одному шаблону.
+- `-` Небольшая дисциплина: сделав значимое изменение, нужно не забыть
+  оформить ADR.
+- Скилл `adr` берёт на себя имя файла, шаблон и обновление индекса в
+  `README.md`, снижая трение.