# Architecture Decision Records (ADR)

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

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

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

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

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

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

## Соглашения

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

## Статусы

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

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

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

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

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

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

| Дата       | Запись                                                            | Статус |
| ---------- | ---------------------------------------------------------------- | ------ |
| 2026-06-13 | [Авто-раскладка только при матче в метабазе](ADR-2026-06-13-auto-link-requires-db-match.md) | — |
| 2026-06-13 | [Docker как единица деплоя](ADR-2026-06-13-docker-deploy.md)      | —      |
| 2026-06-13 | [Хардлинки вместо копирования и симлинков](ADR-2026-06-13-hardlinks.md) | — |
| 2026-06-13 | [Go и доставка одним бинарём](ADR-2026-06-13-go-single-binary.md) | —      |