Architecture Decision Records (ADR)

Журнал значимых архитектурных решений по jellybit. Одна запись — одно решение. ADR пишем постфактум, когда решение принято и зафиксировано в коде/проекте: идеи и неподтверждённые планы живут в docs/drafts, а не в ADR. Записи неизменяемы: передумали → не правим старую, заводим новую и помечаем старую.

Главная ценность записи — сохранить почему: намерение и причинность. Это важнее аккуратности оформления и полноты остальных секций.

Формат и процесс унаследованы от соседнего проекта umbar.

Когда заводить ADR

Выбор технологии или инструмента.
Структурные решения (хранилище, организация компонентов, протоколы).
Решения с долгосрочными последствиями или дорогим откатом.
Намеренный отказ от очевидного подхода — чтобы потом не переоткрывать «а почему мы не сделали X».

Не заводить для рутины (бамп версии зависимости, добавление эндпоинта по накатанной схеме) и того, что и так видно из кода и git.

Соглашения

Имя файла = идентификатор: ADR-ГГГГ-ММ-ДД-kebab-slug.md. Идентификатор — имя без .md. Slug — латиницей.
Дата — когда решение реально принято.
Несколько ADR за один день различаются по slug.
Заголовок в файле: # Человеческий заголовок (без даты и ID — они в имени файла и в строке «Дата»).
Секция «Рассмотренные варианты» — опциональна: оставляй её, только если альтернативы реально рассматривались.
Шаблон новой записи — template.md.

Статусы

Активная запись статуса не имеет. Статус появляется, только когда запись теряет силу, и значений всего два:

заменено на ADR-ГГГГ-ММ-ДД-slug — решение пересмотрено новой ADR.
устарело — решение потеряло смысл и замены нет.

Замена и устаревание

Заводим новую ADR; в её «Контексте» — строка «Заменяет ADR-ГГГГ-ММ-ДД-slug».
В старой ADR добавляем строку - Статус: заменено на ADR-… сразу под датой. Тело не трогаем — это часть истории.
Обновляем статус старой записи в индексе ниже.

Список записей

Новые сверху.

Дата	Запись	Статус
2026-06-13	Docker как единица деплоя	—
2026-06-13	Хардлинки вместо копирования и симлинков	—
2026-06-13	Go и доставка одним бинарём	—

3.9 KiB Raw Blame History