82 lines
5.7 KiB
Markdown
82 lines
5.7 KiB
Markdown
---
|
||
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`.
|
||
|
||
## После записи
|
||
|
||
Покажи пользователю путь к файлу и кратко содержание. Не коммить без
|
||
явной просьбы.
|