The ADR Nobody Wanted to Read
How Teams Make Decisions in a Page and a Half and How AI Agents Can Help
Tom’s 12-Page ADR
Tom is an engineer on the Data Platform team. Today, he’s writing his first ADR. The team needs to decide whether its Terraform code goes into a monorepo or into multiple repos. Tom wants to get it right, so he includes everything: the system design, discussions from three meetings, comparison tables, diagrams, risks, and a migration plan.
The result is twelve pages. Nobody reads it. Two colleagues skim the first page, one comments on a detail in the appendix, and the decision is still up in the air. Three weeks later, someone asks in the daily stand-up, “Did we actually decide this?”
I know this situation well: I’ve packed ADRs with details myself and tried to discuss, design, and decide in one document at the same time. It doesn’t work. In this post, I’ll show you a better way: how an entire team can write ADRs, and where AI agents can help.