Куда класть решение: в комментарий к коду или в ADR?

Комментарий объясняет строку, ADR объясняет выбор между вариантами. Если решение сводится к одной фразе в коде, ADR не нужен; если за ним стоит отвергнутая альтернатива, которую придётся вспоминать через полгода, документ окупается.

Глоссарий

ADR (Architecture Decision Record): документ одного решения

Коротко: ADR (Architecture Decision Record) это короткий документ, который фиксирует одно архитектурное решение: контекст, варианты, выбор и обоснование. В отличие от конвенций стиля, ADR описывает намерение: почему в проекте целые центы вместо float или слой кэша между модулем и базой. Код подчиняется ADR, а не наоборот: если код разошёлся с решением, это либо баг в коде, либо забытое обновление документа, и различить их может человек, а не агент. У живого ADR есть статус и дата, у конвенции в README их обычно нет.

Практический маркер различия с конвенцией: у ADR есть статус и обоснование, у строки в README их нет. Когда агент видит конфликт кода с документом, у которого есть rationale, это находка для человека, а не повод автоматически переписать что-то одно.