5.7 KiB
name, description
| name | description |
|---|---|
| adr | Создаёт и сопровождает 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
- Дата. Когда изменение реально сделано. Обычно сегодня
(
date +%F). Если оформляем задним числом — уточни дату у пользователя, не подставляй сегодняшнюю вслепую. - Идентификатор и имя файла:
ADR-ГГГГ-ММ-ДД-kebab-slug.md(slug — латиницей). Если за эту дату уже есть ADR — slug просто должен отличаться; проверьls docs/adr/. - Файл. Возьми за основу
docs/adr/template.md. - Заполни по шаблону:
- Заголовок
# Человеческий заголовок(без даты/ID в тексте). - Метаданные: только
- Дата: ГГГГ-ММ-ДД. Строку статуса не добавляй — у активной записи статуса нет. - Контекст — какая проблема и ограничения вынудили это делать.
- Рассмотренные варианты — опциональная секция. Спроси пользователя, рассматривал ли он какие-то альтернативы. Если да — перечисли их с плюсами/минусами (особенно те, что отвергнуты); если нет (решение было единственным очевидным) — удали секцию целиком.
- Решение — что сделано и, главное, почему: какое намерение и причина за этим стоят.
- Последствия —
+/-и что нужно сделать как следствие.
- Заголовок
- Индекс. Добавь строку в таблицу «Список записей» в
docs/adr/README.md, сверху (новые сверху). Статус ——.
Самое важное в ADR — сохранить почему: намерение и причинность, а не просто «что сделали». Не придумывай причины и альтернативы за пользователя — если их нет в контексте сессии, обязательно спроси: что подтолкнуло к изменению и какие варианты рассматривались.
Замена / устаревание решения
Старые ADR неизменяемы. Если решение пересмотрено:
- Заведи новую ADR (шаги выше). В её «Контексте» — строка «Заменяет ADR-ГГГГ-ММ-ДД-slug».
- В старой ADR добавь строку статуса сразу под датой:
- Статус: заменено на ADR-ГГГГ-ММ-ДД-slug(или- Статус: устарело, если замены нет). Тело не трогай. - Обнови статус старой записи в индексе
README.md.
После записи
Покажи пользователю путь к файлу и кратко содержание. Не коммить без явной просьбы.