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