Architecture Decision Records — ADR
During a year-end review, we discussed how projects constantly face new situations. The architecture evolves, and so do the people building it. We need systematic reflection, adjustment, and knowledge sharing to keep everyone aligned.
A teammate suggested Architecture Decision Records (ADRs). I’d skimmed the concept before and then forgotten it—time to close the loop.
ADR
ADR stands for Architecture Decision Record. Projects are living systems, so we need a structured way to document their major decisions. The team also needs an easy way to consume that information, and documentation fits naturally.
Current Practice
- Blog posts—handy for personal summaries
- Internal documentation—Confluence, etc.
- Tribal knowledge—in someone’s head
That’s clearly not systematic. ADRs fill the gap.
ADR Template
The community shares a commonly used template. Treat it as a starting point, not orthodoxy—adapt it to deliver value.
Final Thoughts
- CL means changelist. Version control captures code, but ADR decisions don’t map one-to-one with commits, and some decisions may be discouraged or deprecated later. CLs alone aren’t enough.
- Architecture changes the codebase. Keeping ADR Markdown files alongside the repository provides context and history together.
- ADRs are just one systematic answer to a software-engineering need—use them pragmatically.
