О разделе "ADR и архитектурная память"
ADR (Architectural Decision Record) — короткий документ о важном архитектурном решении: что выбрали, в каком контексте, какие компромиссы приняли. Без ADR знания остаются в головах ушедших сотрудников, в закрытых PR и в устных "мы так всегда делали". Новый разработчик тратит недели на повторение споров; инциденты вскрывают допущения, о которых никто не записал.
Раздел для новичка и для команды, которая хочет архитектурную память без тяжёлой документации: шаблон Nygard, статусы, хранение в Git, примеры в продукте, аутсорсе и госсекторе.
Разработчику — где искать "почему Redis" и как предложить ADR в PR.
Архитектору и SA — минимальный процесс review и связь с NFR.
PM и тимлиду — когда решение влияет на срок и change request.
Что вы узнаете
| Тема | Результат |
|---|---|
| Определение ADR | Контекст, решение, последствия, статус |
| Когда писать | Дорого отменить — фиксируем |
| Шаблон Nygard | Готовый каркас для первого ADR |
| Статусы | Proposed → Accepted → Deprecated / Superseded |
| docs-as-code | ADR в Git, review в PR |
| Контексты | Продукт, аутсорс, гос, легаси |
Как читать раздел
| Шаг | Материал | Содержание |
|---|---|---|
| 1 | ADR — запись архитектурных решений | Шаблон, статусы, хранение, примеры |
| 2 | Итоги | Резюме и FAQ |
| 3 | Чек-лист | Самопроверка архитектурного журнала |
Параллельно полезны проектирование и архитектура и ADR docs-as-code. На старте проекта — архитектура на старте.
Соседние разделы
| Вопрос | Куда идти |
|---|---|
| NFR, SLA, trade-off | Проектирование |
| Wiki и онбординг | Базы знаний |
| Легаси и эволюция | Легаси-код |
| Инцидент → новое решение | Инциденты |
| Git и PR | Основы Git |
ADR — не то же самое, что ТЗ
В заказной разработке и госсекторе есть ТЗ и формальные письма. ADR дополняет их: объясняет инженерную развилку коротко и живёт рядом с кодом. ТЗ меняется медленно; ADR обновляется через Superseded, когда команда осознанно меняет подход.
Признаки, что ADR нужны вам
- На каждом онбординге спорят про СУБД или брокер.
- Postmortem пишет "не было документации по кэшу".
- Архитектор в отпуске — команда боится трогать интеграции.
- Заказчик просит обоснование для экспертизы — собираете с нуля за ночь.
- PR на "переезд на Kafka" без текста "почему".
Если узнали команду — глава 1 и чек-лист.
Термины раздела
| Термин | Кратко |
|---|---|
| ADR | Запись архитектурного решения |
| Контекст | Проблема и ограничения |
| Последствия | Плюсы, минусы, риски |
| Proposed | ADR на обсуждении |
| Accepted | Действующее решение |
| Superseded | Заменён другим ADR |
| docs-as-code | ADR в Git с кодом |
Первые шаги для команды без ADR
- Создать
docs/adr/README.md. - Описать 3 уже принятых решения (БД, auth, деплой).
- Добавить в шаблон PR ссылку на ADR.
- На онбординге — "прочитай ADR по своему сервису".
ADR — запись архитектурных решений
Architectural Decision Record — что это, шаблон Nygard, статусы, хранение в Git, примеры для продукта, аутсорса и госсектора.
ADR — итоги раздела
Резюме ADR, статусы, docs-as-code; FAQ для новичка и архитектора.
ADR — чек-лист самопроверки
Проверка архитектурного журнала решений в проекте.
ADR — о разделе
Architectural Decision Records — как фиксировать технические решения, сохранять контекст и не переоткрывать споры в команде.