ADR — итоги раздела
ADR — память архитектуры: контекст, решение, последствия, статус. Храните в Git, ревьюите как код, не удаляйте устаревшие — помечайте Deprecated или Superseded. Один ADR — одна значимая развилка; детали — в коде, диаграммах и runbook.
Резюме
| Элемент | Запомнить |
|---|---|
| Контекст | Проблема, NFR, ограничения команды |
| Решение | Что выбрали — коротко |
| Последствия | Плюсы, минусы, риски, follow-up |
| Статусы | Proposed, Accepted, Deprecated, Superseded |
| Место | docs/adr/ в Git, PR review |
| Триггер | Дорого отменить или часто спрашивают |
FAQ — частые вопросы
Вопрос. Что такое ADR одним предложением?
Ответ. Короткая запись о важном архитектурном решении — почему выбрали этот путь и какие компромиссы приняли. См. глава 1.
Вопрос. ADR заменяет архитектурную документацию?
Ответ. Нет. ADR дополняет диаграммы, API, ТЗ. Это журнал решений, не полное описание системы. См. проектирование.
Вопрос. Кто должен писать ADR?
Ответ. Обычно инициирует архитектор или SA; review — тимлид, разработчики, DevOps. Любой может предложить ADR в PR.
Вопрос. Сколько страниц должен занимать ADR?
Ответ. Часто 1–2 экрана. Длиннее — вынести детали в spike, wiki или код. ADR на 40 страниц не читают.
Вопрос. Нужен ли ADR на выбор React вместо Vue?
Ответ. Если смена стека дорогая и влияет на найм — да. Если команда единогласна и стек зафиксирован в README — можно короткий Accepted ADR или запись в онбординге.
Вопрос. Proposed и Accepted — в чём разница?
Ответ. Proposed — на обсуждении, код ещё не обязан следовать. Accepted — действующее решение после merge PR.
Вопрос. Можно ли удалить старый ADR?
Ответ. Лучше не удалять. Поставьте Deprecated или Superseded by ADR-NNN — сохраняется история для легаси.
Вопрос. ADR в Confluence — плохо?
Ответ. Хуже, чем в Git, если нет связи с PR и версий. Идеал — docs-as-code (статья 23); в wiki — ссылка на файл в репо.
Вопрос. Новый разработчик спросил "почему PostgreSQL" — куда отправить?
Ответ. В ADR-000X с контекстом и отвергнутыми вариантами. Если ADR нет — завести Proposed и не спорить устно в коридоре.
Вопрос. Postmortem показал, что решение неверно — что с ADR?
Ответ. Новый ADR + старый Superseded. Не править Accepted задним числом без следа. См. инциденты.
Вопрос. Заказчик в аутсорсе требует согласования ADR?
Ответ. Часто да для СУБД, интеграций, безопасности. Держите статус Proposed до письма заказчика; см. договор.
Вопрос. Сколько ADR нужно на старте?
Ответ. Часто 3–5 на стек, БД, auth, интеграции, среды. См. старт проекта.
Вопрос. ADR и spike — что раньше?
Ответ. При высокой неопределённости — spike, затем ADR с результатами. Иначе ADR фиксирует догадку.
Вопрос. Нужно ли PO читать все ADR?
Ответ. PO — консультант, если ADR влияет на срок roadmap. Читает выжимки; детали — SA и тимлид. См. продуктовые роли.
Вопрос. adr-tools обязателен?
Ответ. Нет. Достаточно папки и нумерации. adr-tools удобен для adr new и оглавления.
Связь с другими практиками
- NFR в контексте ADR — NFR.
- CR с архитектурным влиянием — управление изменениями.
- Культура — ADR в уважении к инженерам.