Architecture Decision Record Workshop

Purpose

Architecture decisions are expensive to reverse and easy to forget. This workshop structures the decision-making process: the team evaluates options against criteria, selects the best fit, and captures the reasoning in an ADR so future team members understand the why.

At a glance

How to run

1. State the context (10 min) — What architectural question needs answering? What forces and constraints are at play?
2. List options (10 min) — Brainstorm possible approaches. Include the status quo as an option.
3. Define evaluation criteria (5 min) — What matters most? Performance, maintainability, cost, team skill, time to market, etc.
4. Evaluate options (20 min) — For each option, discuss pros and cons against the criteria. Use a decision matrix if the choice is complex.
5. Decide (5 min) — Consensus or consent-based decision. If no consensus, the architect or tech lead decides.
6. Write the ADR (10 min) — Capture: Title, Status, Context, Decision, Consequences. Store in the repository alongside the code.

Materials needed

• ADR template (Title, Status, Context, Decision, Consequences)
• Decision matrix template (options vs. criteria)
• Whiteboard or shared document
• Architecture diagrams for context

Pitfalls & common mistakes

• No written record — Verbal decisions get forgotten or reinterpreted. Always write the ADR.
• Analysis paralysis — Time-box the evaluation. A good-enough decision now beats a perfect decision later.
• Not revisiting — Mark ADRs as superseded when the decision changes.
• Excluding implementers — Developers who will build it must be in the room.

Inclusion & accessibility

• Share the context and options in advance so all participants can prepare.
• Use decision matrices to make evaluation transparent and objective.
• Allow written contributions for those who prefer async input.

Variations

• Lightweight ADR — A one-paragraph record for small decisions.
• MADR format — Markdown Architectural Decision Records stored in a git repository.
• Spikes before ADR — Run time-boxed spikes to gather data before the decision workshop.

When NOT to use this

• For trivial decisions that are easily reversible.
• If the architecture is dictated by policy with no room for alternatives.

Source & further reading

• Nygard, M. (2011). "Documenting Architecture Decisions." cognitect.com
• Keeling, M. (2017). *Design It!* Pragmatic Bookshelf.