Architecture Decisions Are Design in Motion
I used to think ADRs were just paperwork. Another layer of documentation to satisfy some imagined governance board lurking somewhere in the cloud. Then I realized they’re basically the engineering version of a time capsule: a short, sharp memo to your future self explaining what on earth you were thinking.
And wow, has that future self been grateful.
Why I Bother Writing Them
AI can implement faster than I can sip a coffee, but it still can’t explain why that implementation exists. Decisions, trade-offs, constraints - those are the pieces that separate a functioning app from an evolving system.
That’s where Architecture Decision Records come in. A good ADR captures one meaningful choice, in plain language. It doesn’t try to impress. It just explains context, decision, and consequences. That’s it. No architecture diagram extravaganza. No fifteen-page justifications. One page, one choice.
Lukas Niessen wrote a great piece about how ADRs and RFCs are better thought of as alignment tools, not paperwork. I like that framing: ADRs are about the conversations you have to make the decision, as much as the text you write after it.
A Real Example (with the messy parts removed)
Recently, we were dealing with a component that had quietly evolved into a mini-monolith. Everyone had opinions. Some wanted to rewrite, some wanted to optimize, some wanted to move on and pretend it didn’t exist.
We started an ADR. Simple template:
- Context
- Decision
- Consequences
Once we wrote the context - what hurt and why - it was suddenly obvious where our real problem was. The decision part basically wrote itself after that. And when implementation started, we weren’t second guessing every move because we’d already done the heavy thinking.
That one page gave us clarity, consensus, and a little peace of mind. Not bad for something that took a few hours to write. And please don't rob yourself of the mental exercise by having AI do it...
ADRs Are More About People Than Architecture
Teams don’t struggle to decide. They struggle to remember why they decided. An ADR is a portable memory. It saves your reasoning at a moment in time before entropy kicks in and messages vanish.
Niessen’s framing helped me think of it this way:
- RFCs are where you open the floor for ideas.
- ADRs are where you close the loop.
RFCs spark debate. ADRs preserve agreement. Both are necessary if you want your team to make progress without repeating themselves every quarter.
A Few Things I’ve Learned the Hard Way
- Keep it short enough that your future self won’t groan when reading it.
- Write like you’re explaining it to a colleague over coffee, not defending a thesis.
- Never edit old ADRs. Supersede them. You can’t rewrite the past, and you’ll lose valuable context if you try.
- Store them next to the code. A decision buried in your wiki might as well not exist.
- Don’t write them for compliance. Write them to make thinking visible.
The Bigger Picture
If code is the what, ADRs are the why. And as generative tools start helping us with the what, the why becomes the craft worth honing. ADRs aren’t bureaucratic - they’re how we practice deliberate design. They remind us that good architecture isn’t just about knowing patterns, it’s about capturing judgment.
You can probably get away without writing them. You can also get away without brushing your teeth for a few days. Both choices catch up eventually.
How to Start
If your team hasn’t used ADRs before, pick one real decision and write it down. Something that stirred discussion or uncertainty. Don’t overthink the format - just cover the basics: context, decision, consequences. Store it in your repo. Done.
When you need to revisit the topic down the line, you’ll find something magical: the conversation starts one level higher, because everyone already has the backstory.
That’s the real point. ADRs aren’t for compliance. They’re for sanity.
ok ok, I can hear you now. You want a template to get a visible about what I'm talking about. Here is one for you. An ADR I wrote for my compony on why we use Golang.