К документации у инженеров отношение понятное: её пишут, чтобы сдать, и не открывают, чтобы работать. При этом две практики за последние пару лет стали моими рабочими инструментами, и обе про документы.
Первая: ADR, короткая запись об архитектурном решении. Одна страница: контекст, варианты, что выбрали и почему, какие последствия. Не отчёт для начальства, а памятка для будущих себя и коллег. Через год, когда кто-то спросит, почему здесь Kafka, а не очередь в базе, ответ находится за минуту, а не за неделю раскопок.
Вторая: SDD, разработка от спецификации. Сначала коротко и явно описываем, что должно получиться: интерфейсы, ограничения, критерии приёмки. Потом пишем код. С появлением агентов это перестало быть бюрократией и стало необходимостью: агент пишет код ровно настолько хорошо, насколько хорошо сформулирована задача. Мусорная спецификация даёт мусорный код, просто теперь быстрее и в больших объёмах.
Заметил забавную вещь: команды, которые раньше саботировали любые документы, с приходом агентов сами начали писать спеки. Потому что это единственный способ получить от машины предсказуемый результат.
Вывод простой. Документ нужен не тогда, когда «так принято», а когда он дешевле, чем последствия его отсутствия. ADR и короткие спецификации этот тест проходят.