3.7 KiB
Вести историю решений в виде 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, шаблон — в
template.md. Для единообразия заполнение
автоматизировано скиллом adr (.claude/skills/adr/).
Последствия
+Сохраняется обоснование решений и отвергнутые альтернативы.+Датовый ID даёт хронологию «из коробки» и не мешает оформлять записи задним числом.+Единый формат: записи делает человек или агент по одному шаблону.-Небольшая дисциплина: сделав значимое изменение, нужно не забыть оформить ADR.- Скилл
adrберёт на себя имя файла, шаблон и обновление индекса вREADME.md, снижая трение.