---
name: adr
description: >-
  Создаёт и сопровождает Architecture Decision Records (ADR) в docs/adr/.
  Используй, когда уже сделанное архитектурное или инфраструктурное
  изменение нужно зафиксировать постфактум: выбор инструмента/подхода,
  структурное решение, намеренный отказ от очевидного варианта, либо
  прямая просьба «записать решение / завести ADR». А также когда старую
  ADR нужно пометить заменённой или устаревшей. ADR пишут ПОСТФАКТУМ;
  идеи, планы и обсуждения — это drafts, а не ADR.
---

# Работа с ADR

ADR живут в `docs/adr/`. Формат и соглашения — `docs/adr/README.md`,
шаблон — `docs/adr/template.md`. Читай README перед первой записью в
сессии: правила там — источник истины, эта инструкция лишь даёт порядок
действий.

Язык записей — **русский**, стиль — как в `docs/drafts/`: конкретно,
по делу, без воды. Калибровка под личный хобби-сервер: не раздувай
запись, не предлагай корпоративные процессы.

## Сначала реши, нужен ли ADR

Заводи, если изменение **уже сделано** и это: выбор технологии/
инструмента, структурное решение, решение с долгосрочными последствиями
или дорогим откатом, либо намеренный отказ от очевидного варианта.

Не заводи:
- для рутины (бамп версии образа, сервис по накатанной схеме) и того,
  что видно из кода/git;
- для идей, планов и того, что ещё не реализовано — это `docs/drafts/`,
  а не ADR.

Если сомневаешься — спроси пользователя, не плоди записи молча.

## Создание новой ADR

1. **Дата.** Когда изменение реально сделано. Обычно сегодня
   (`date +%F`). Если оформляем задним числом — уточни дату у
   пользователя, не подставляй сегодняшнюю вслепую.
2. **Идентификатор и имя файла:** `ADR-ГГГГ-ММ-ДД-kebab-slug.md`
   (slug — латиницей). Если за эту дату уже есть ADR — slug просто
   должен отличаться; проверь `ls docs/adr/`.
3. **Файл.** Возьми за основу `docs/adr/template.md`.
4. **Заполни** по шаблону:
   - Заголовок `# Человеческий заголовок` (без даты/ID в тексте).
   - Метаданные: только `- Дата: ГГГГ-ММ-ДД`. **Строку статуса не
     добавляй** — у активной записи статуса нет.
   - **Контекст** — какая проблема и ограничения вынудили это делать.
   - **Рассмотренные варианты** — *опциональная* секция. **Спроси
     пользователя, рассматривал ли он какие-то альтернативы.** Если да —
     перечисли их с плюсами/минусами (особенно те, что отвергнуты); если
     нет (решение было единственным очевидным) — удали секцию целиком.
   - **Решение** — что сделано и, **главное, почему**: какое намерение и
     причина за этим стоят.
   - **Последствия** — `+`/`-` и что нужно сделать как следствие.
5. **Индекс.** Добавь строку в таблицу «Список записей» в
   `docs/adr/README.md`, **сверху** (новые сверху). Статус — `—`.

Самое важное в ADR — сохранить **почему**: намерение и причинность, а не
просто «что сделали». Не придумывай причины и альтернативы за
пользователя — если их нет в контексте сессии, обязательно спроси: что
подтолкнуло к изменению и какие варианты рассматривались.

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

Старые ADR неизменяемы. Если решение пересмотрено:

1. Заведи новую ADR (шаги выше). В её «Контексте» — строка
   «Заменяет ADR-ГГГГ-ММ-ДД-slug».
2. В старой ADR добавь строку статуса сразу под датой:
   `- Статус: заменено на ADR-ГГГГ-ММ-ДД-slug` (или `- Статус: устарело`,
   если замены нет). Тело не трогай.
3. Обнови статус старой записи в индексе `README.md`.

## После записи

Покажи пользователю путь к файлу и кратко содержание. Не коммить без
явной просьбы.