ADR – короткая запись «почему мы выбрали именно так». Документ говорит «что», человек знает «почему», а ADR сохраняет рассуждение, когда человек ушёл. Без ADR через год никто не вспомнит, чем руководствовались, и перепишут всё с нуля.
Заголовок
ADR-№___: [коротко – какое решение принято] Статус: предложено / принято / устарело · Дата: ___
Контекст
Какая проблема, какие ограничения (команда, бюджет, сроки, существующая система, требования безопасности/комплаенса). Фактами, без оценок.
Варианты (минимум 2)
| Вариант | Плюсы | Минусы / риски |
|---|---|---|
| A. ___ | ___ | ___ |
| B. ___ | ___ | ___ |
| C. (ничего не делать) | ___ | ___ |
Решение
Выбрали вариант ___, потому что ____. Одна-две фразы, конкретно.
Последствия
- Появляется: ___ (новые возможности, зависимости).
- Теряется / усложняется: ___.
- Технический долг, который осознанно берём: ___.
- Когда пересмотреть: триггер (рост нагрузки ×N, смена команды, …).
Принципы
- Один ADR – одно решение. Короткий (1–2 страницы).
- «Вариант ничего не делать» – обязательный: он показывает цену изменения.
- Принятое и устаревшее не удаляем – история важнее «чистоты».
- Живёт рядом с кодом (repo/docs/adr), а не в чужой вики, которая умрёт.