Ошибки в работе с Architecture Decision Records

Architecture Decision Records – практика записи всех ключевых технических решений, принимаемых командой, с объяснением их контекста. Про какие ошибки идет речь в треде:

📚Держать ADR отдельно от кода, к которому они относятся, описывая их в виде документов и презентаций. Из-за этого их реже будут открывать, появятся дополнительные барьеры для их заведения, и все превратится в бюрократию.
🔀Выстраивать отдельный процесс по написанию и оформлению ADR. Проще не относиться к этому как к отдельному этапу разработки, а вести ADR по ходу обсуждений, сразу же записывая ключевые идеи принятого решения. ADR должны быть интегрированы в процесс разработки, а не отделены от него.
📝Вместо описания принятого решения слишком много времени тратить на перечисление возможных альтернатив. Из-за этого объем ADR раздувается, их сложнее читать, и меньше фокуса уделяется самому важному – принятому командой решению.

В треде еще много интересных обсуждений про другие ошибки в ведении ADR и подходящую организацию для их хранения, тоже советую почитать!