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

Ну, ADR - тоже для всех, по идее. 21 штука за 3 месяца - это как-то дофига.
Я бы уже рисовал архитектурное описание продукта, а уже с него делал ссылки на ADRки.

а что такое "архитектурное описание"? одна из ADRок как раз про это, с общей схемой и что где куда, и почему

Одна? Это же постоянный и живой документ, изменения в котором описываются ADR.

Интересная структура, а как сделать наблюдаемее из кода без шага git blame -> задача?
Трекер тоже может смениться в теории, если проект живёт годы
В коммите ссылка на задачу есть уже :) начали писать месяца 3 назад

От "микросервисы" или "монолит" и до какой REST выбрали.

и это всё в одном, живом документе?

Когда меняется трекер - оставляется старый или делается перенос (

В одном живом дереве страниц в Confluence )
С ссылками на встречи или обоснования (т.е. ADRки) - если нужно

У меня старый относительно проект, поэтому треть адр это брифы интервью на тему "вот я код вижу, а откуда ноги растут - что там за проблема была и почему ее решили именно так"
Если удалось найти того кто делал в компании)
Или расследования по датам коммита с сопоставлением в трекер (если повезло и на это была задача/дата стоит после появления трекера)

Впрочем, если есть ресурсы, то лучше asciidoc+pluntuml из которого формируется Confluence. Но это сложнее.

Документация легаси - да, это отдельная проблема всегда.
Но это вряд ли ADR

а, ну если есть ресурсы, то есть кому править Confluence, то хорошо )

но подход с ADR прекрасен именно низким порогом входа
когда инженеры, прежде чем начинать пилить какую-то важную часть системы, справляются написать про предположения и допущения, про выбранные решения, про последствия (плюсы, минусы, требования вытекающие и тп)
и потом можно уже всех тыкать в ADR по номеру - и всем всё понятно

и да, у нас ADR тоже коммитится в мастер через ревью )

В общем смотрю как на небольшой док-пояснялку о решениях, не обязательно строго архитектурных
Что-то делать или не делать - тоже решение, типа пока не публиковаться в Mac app store

Надо не забывать прикладывать дизайны к новым задачам, и будет довольно красиво как Фил предложил :)
Прослеживаемость код-задача-техдизайн-решения

Но из кода ссылка как-то проще в плане что нет необходимости лазить в трекер лишний раз

Так у вас это не совсем про ADR, это зачаток design review. Если его сделать обязательным для каждой задачи и ревьюить до написания кода и убрать из git (где с ним только сложнее работать), то будет совсем хорошо.

Для вашего подхода я, вот, плохо представляю, как ADR совмещаются с прочими процессами работы с git (работа с ветками, привязка к задачам и т.п.). К тому же ADR (как и Design Review) важен и для продуктов и для бизнес-аналитиков, прятать его в гите - странно.

В общем, я все это рассказываю на докладе, лень повторять. Лучше задавать вопросы по существу, а не придумывать что-то про то, что я предлагаю

Тут зависит от процесса.
Например, мне быстрее открыть страницу задачи, сразу увидеть и требования и design и выдать review. Это занимает минут пять в среднем. Внутри гита это будет сложнее (тем более что review обычно делается до бранча на фичу и в гите вообще не понятно, а куда это писать).
Ну и Design Review важен не только для разработки и QA

Я правильно понимаю, что ты имеешь в виду такой процесс?
1) разработчик берет задачу
2) пишет дизайн в задачу как набор ссылок на решения
3) ты их смотришь и отвечаешь
То есть я пытаюсь понять техдизайн/набор решений это одна сущность или несколько разных, где техдизайн это нечто большее чем просто набор ссылок
Думаю что второе
В целом спора нет, it depends :)
Веток может и не быть если у людей tbd по хардкору

Привет! Немного не в контексте, а есть ссылка на доклад?

Не совсем.
2) пишет как ее будет делать (тех.дизайн), в котором могут быть ссылки на ADR (а могут и не быть)