Всем привет!
Вы часто меня спрашиваете, куда я пропала (нет) 🤣
В прошлый раз вернуться я не смогла, потом оказалось, что у меня выгорание и пришлось из него выходить)) Про стадии выгорания, и что помогло мне из него выйти я обязательно напишу пост, а сейчас о другом)

Коллега посоветовал классную книгу, «Фундаментальный подход к программной архитектуре» (обложку покажу в каментах), в ней описаны различные подходы к проектированию архитектуры, паттерны, антипаттерны и приёмы, виды архитектуры и др.
Одна из глав книги посвящена такому понятию как записи архитектурных решений (Architecture Decision Record, ADR). Это созвучно с тем, что мы сейчас реализуем у себя в команде разработки, поэтому очень хочу рассказать)

Architecture Decision Record - это текстовый файл, который создаётся для описания конкретного архитектурного решения. Мы у себя используем .md файлы и храним их в Git. Есть и другие инструменты и форматы, например, страница в вики вашей компании.
Файл должен быть лаконичным, и содержать разделы, о которых я расскажу ниже.

1️⃣ Название - короткое описание архитектурного решения, должно быть информативным и понятным, чтобы быстро ориентироваться, о чём эта запись
2️⃣ Статуc ADR - на какой стадии находится данное арх. решение: принято, или ещё обсуждается (Request For Comments, RFC), а может заменено новым ADR
3️⃣ Контекст - ситуация, которая привела к созданию ADR и принятию решения
4️⃣ Решение - сама суть архитектурного решения и его полное обоснование. Важно уделить особое внимание именно обоснованию решения, ответить на вопрос «почему». Этот момент является ключевым и самым полезным (имхо) в документировании архитектуры
5️⃣ Последствия - описание того, что влечёт за собой принятое архитектурное решение. Какие плюсы и минусы у него есть, их анализ
6️⃣⭐️ Альтернативы - опциональный раздел, в котором сосредоточены альтернативные решения указанной проблемы, и причины, по которым эти решения не были приняты командой
7️⃣ ⭐️ Комплаенс - в книге рекомендуется включать этот раздел в свои ADR. Это описание, каким образом контролировать соблюдение требований данного арх. решения, должно ли это контролироваться вручную или можно автоматизировать. У нас пока такого раздела нет
8️⃣⭐️ Примечания - также опциональный раздел для указания автора, дат утверждения и замены, лиц, участвующих в принятии и утверждении данного решнеия и т. д.
9️⃣ ❓❓❓
🔟 Вы великолепны 🤪😂

Вы спросите меня, зачем всё это нужно? И я вам отвечу)))

🌟 Это эффективный способ документировать архитектуру - всё в одном месте, можно наблюдать инкремент, описаны альтарнативы, + и -
🌟 Не приходится проводить повторные R&D, потому что результаты предыдущих архитектурных дилемм записаны, оформлены, подведены итоги
🌟 Чуть полегче онбордить новых разработчиков/внедрять иннерсорс, когда приходят с «а почему», можно прислать ссылку на «а потому» и вопрос исчерпан (но естественно пересмотр архитектуры и принятых решений должен быть)
🌟 Можно унифицировать подход к архитектуре микросервисов и тем самым снизить эксплуатационные издержки на поддержку

Приземлю на конкретику. Если вы приходите в сервисы и не понимаете

🟢 почему условный Вася воткнул тут кафку, а не обошёлся рестом
🟣 почему решили использовать gRPC, а не десериализовать json’ы до талого))
🔵 почему используется именно эта библиотека для генерации PDF
🟡 зачем тут Camunda прости господи)))
🟢 почему эту интеграцию реализовали из г… теми ресурсами, которые были доступны на тот момент 🥲
🟣 почему все сервисы развёрнуты в k8s, а один стоит на виндовой тачке в другом контуре

Как я уже упомянула, мы у себя потихоньку начали внедрять практику написания ADR. Пока описано не всё, но уже сейчас удобно вспомнить какие решения мы приняли и почему решили именно так.

Расскажите, знаете про такой инструмент? Практикуете?