My Agile Architecture Workflow Using ADRs

Minimising documentation and capturing the decision process as it happens.

Architecture decision records (ADRs) are a simple way to document why a decision was made.

ADRs outline the business context and problem statement; considered options — including pros and cons; the decision; and consequences.

Until recently, ADRs were always an afterthought — something tedious I had to complete after the decision was approved. However, the challenge with this approach is that I often forget important details of how we arrived at the decision point.

Nowadays, I’ve started to use ADRs right from the outset — allowing me to capture the decision process as it happens.

Workflow

My workflow looks something like this:

Architecture Requirements

1) Initial Meeting: This is where I’ll get an understanding of the problem and business context from the stakeholders. I also like to include a diagram in the ADR — it helps set the scene in later playback sessions.