Add architecture decision record templates

2026-05-24 14:35:35 +03:00
parent dc49b3497b
commit e45e1db002
4 changed files with 238 additions and 0 deletions
@@ -0,0 +1,81 @@
+---
+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`.
+
+## После записи
+
+Покажи пользователю путь к файлу и кратко содержание. Не коммить без
+явной просьбы.