In talking to my team, my advice has been "whenever it will be useful", which is of course a bit glib but I don't think we want hard and fast rules. It's going

In talking to my team, my advice has been "whenever it will be useful", which is of course a bit glib but I don't think we want hard and fast rules. It's going to be more true of things that are harder to change, more true of things that touch more places in the code, more true when decisions are higher risk, more true when reasoning is less obvious. I also think we should err on the side of writing too many ADRs, and writing ADRs that are too lightweight. There's some implicit pressure that if we're writing down our reasoning we'd better make sure it's good reasoning, but it's simultaneously true that some decisions don't deserve a lot of deliberation and when a decision didn't get a lot of deliberation we would like to know that down the line. If we capture some number of ADRs that say "decided XYZ because shrug", then down the line when we're inevitably bit by some bad decisions, we can look at whether those were disproportionately the ADRs that got less thought.