Документацию любого вида писать вообще довольно запарно. Обычно от неё пользы примерно столько же сколько и вреда. Написать однозначно понятно – сложно, сделать так, чтобы её читали – сложно, актуализировать – очень сложно.
Любые гайдлайны "как писать код", которые одни разработчики на проекте пишут для других, ничем в этом смысле не отличаются. А соблазн довольно велик. Ты якобы один раз написал человекочитаемым текстом такой закон, которого теперь люди должны придерживаться. Потом привлекаешь к ответственности за нарушения этого закона на код ревью, кидаешься ссылкой на доку, вместо того чтобы каждому всё заново расписывать. Но почти всегда – это полумера и костыль.
На практике это полезно разве что для какого-то онбординга. Т.е. когда ты новенький пытаешься в максимально короткие сроки познакомиться с культурой или каким-то новым подходом. Ну или ты старенький, помнишь что у тебя есть документация, но не помнишь что в ней написано. Потому что сделать так, чтобы все соблюдали эти требования непросто.
Да и откуда уверенность, что ты вообще прав описывая рамки, в которых команда должна работать? Мне в целом не нравится запретительная риторика. А если она на словах, то это всегда предмет каких-то абсолютно ненужных споров. Всё что не запрещено – разрешено, и это прекрасно. Консистентность это хорошо, но не ценой всей гибкости в принятии решений. Разработчик в конкретной команде сам лучше знает как ему написать фичу.
Вопрос легаси в этом вопросе тоже очень сложный. Вы явно будете свой подход дорабатывать. Вот где та грань, где мы привлекаем к ответственности за нарушение актуальных гайдлайнов и заставляем переписывать, а где нет? Что если человек залез в легаси которому 10 лет? Что если он 1 строчку потрогал? Обратную силу закон имеет? Формально ревьювер будет прав. 👮
Мне очень нравится документация, описывающая какой-то верхнеуровневый вижн проекта, стратегию там какую-нибудь, HLD, перечень принятых решений на развилках истории. Мне совсем не нравится документация, которая зачем-то дублирует правила детекта или досканально описывает какие классы у тебя обязательно должны быть в архитектуре фичи. Она делает хуже.
Если важно – максимально формализуй и автоматизируй, неважно – отпусти.