Давайте будем документировать архитектурные решения!

Хороший лозунг, понятно из какой боли он произрастает. Сложно онбордить, сложно поддерживать, сложно дорабатывать, сложно рефакторить. Хочется общую картинку.

Я часто видел, как в результате команды приходили к идее сделать какой-то вид ADR (Architecture Decision Record) — фиксировать каждое архитектурное решение в виде этакой блогозаметки.
На мой взгляд это хорошее решение и это ужасное решение.

Хорошее — потому что это лучше чем ничего, и даже внедрение подобного подхода требует мощного волевого усилия. Вот, кстати хорошая статья с самым простым шаблоном: https://infraeng.dev/decision-log/

Плохое — потому что начиная записей с 30 разобраться в этом становится невозможно. Мне кажется, что тут лучше подход wiki: выделить абстрактные сущности (например, такие: https://youtu.be/NGiN3df_YGc?t=571) и с каждым решением — обновлять описания каждой из сущностей, затрагиваемых изменением (методы API, компоненты, фунциональные/не функциональные требования, бизнес-возможности пользователей и т.п.) и аккуратно пролинковывать зависимости.
Это сложнее, требует сурового онбординга для новичков, но гораздо прозрачнее в использовании. Причём изучение можно начать с того места, которое тебя волнует здесь и сейчас — меняя сущность ты от неё можешь размотать все взаимосвязи.