Architecture Decision Records

This is a way for architects to communicate their decisions. Most developers will at some point need to follow guidance from architects and might be shown Architectur Decision Records so it could be good to know what they are.

Session outline

Connect: What is an architecture decision

Pick only the correct items

Which of these is an architecture decision?

Some of them are perhaps grey areas? Try not to get into a big discussion though. Hopefully this will lead you into the next section.

Concept: Architecture Decision Record

Explain what you think an Architecture Decision is. For example Neal Ford and Mark Richards say “a good architecture decision is one that helps guide development teams in making the right technical choices” in their book “Fundamentals of Software Architecture”. Grady Booch says “Architecture represents the significant design decisions that shape a system, where significant is measured by cost of change.”

The source for Architecture Decision Records is Michael Nygard’s blog post - go through it.

Active Review

Find some publically available ADRs that are good examples of what you are looking for. For example The winning entry in O’Reilly’s architectural katas competition in 2022. You want people to read them actively, so prepare a version of them where you have deliberately introduced errors - eg you swapped some of the sections and titles. Ask them to read them through and tell you the errors.

Write your own ADR

Make an architecture deicion for the Instavoiced system. For example you could decide:

Work in pairs. Pick an area, make a decision, and write it up in the form of an Architecture Decision Record.

Join two pairs together to review one another’s ADRs. Suggest improvements to make them even better.


When should you use this? Looking at your own team’s situation, are there any decisions you should write up as ADRs?