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