# Вести историю решений в виде 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`, снижая трение.