@GKruglov Если я правильно понял твою задумку, из своего болезненного опыта я бы дополнил:
-- контакты ключевых персон (архитектор, тим лид), особенно если несколько поколений менялось
-- ссылка на compliance, если применимо (а ещё мы не храним информацию о leaver'ах, потому что 152-ФЗ)
-- упоминания о сюрпризах (там есть самописная библиотека, автор в Канаде уже 5 лет, права не оформлены)
-- как выделили ресурс на проект (входит в бюджет проекта X, утвердили на комитете _ссылка)

Не уверен, что это все ещё про дизайн)).

Остальное из списка очень знакомо, плюсую.

Хороший опросник, но всё же сервиса, а не всего решения. Из критики сходу - для rest для понимания, чего оно делает, ссылки на свагер зачастую недостаточно, потому что разрабы не заполняют описательную часть и верят, что имени метода достаточно

А как так получается что swagger/openapi спека появляется раньше сервиса? )

А как так получается что swagger/openapi спека появляется раньше сервиса? )

Много где встречал specification first. Особенно в купе с кодогенерацией.

А как так получается что swagger/openapi спека появляется раньше сервиса? )

Кодогенерацию вживую не видел рабочую. Но есть инструменты для контроля соответствия сервиса сваггеру

У нас в проде есть несколько golang-сервисов запиленных с go-swagger.

А поддержка документов о сервисе в актуальном состоянии и должна быть работой архитектора. Это его задача давать отделам компании инструменты для взаимодействия сервисов между собой. Это его задача отражать на бумаге изменения снизу и транслировать вниз изменения сверху в виде ТЗ.

У меня брюки не настолько подвёрнуты, поэтому только джавка и питон

Конечно нет. Если дизайн в голове разработчиков, то они его и должны "выгружать" в мир

Вы умрёте, если будете более или менее сложный проект изучать по исходникам, которые к тому же периодически меняются

Зачем? Если они имеют внутреннюю достаточную (для их задач) им документацию о дизайне, зачем вытаскивать ее наружу? Какую задачу для разработчика сервиса вы решите этим?