Step 9: Make and record decisions

What you get from this step

You get a short list of the important decisions behind your system. Each entry gives the context, the options you compared, the choice, the reasons and the consequences. People who join later can read why the system looks the way it does. In arc42, this list is section 9. See arc42 Architecture Decisions.

An architectural decision is a choice of one option from several, made against stated criteria. Writing down the reasons lets others retrace the choice.

What you need first

Significant requirements and quality goals. Decisions need something to be traced to. See Architecturally Significant Requirement. Keep the list short, about ten scenarios, each specific and measurable.
Constraints. A constraint limits how freely you can design. Know which ones you must obey and which ones you can negotiate.
Forces. Forces are pressures that you weigh against each other, such as a deadline against quality. Constraints are different: you must deal with them.
Stakeholders and their concerns. See Stakeholder Concern.
Your solution strategy (section 4). The most fundamental decisions live there, short but with reasons. Section 9 refers to them and does not repeat them.

If something is missing

No clear requirements yet. Write a rough draft of the requirements and drivers. The Definition of Ready asks for them to be at least identified and drafted. Requirements and architecture grow together, and each round informs the other. See Twin Peaks Model.
No constraints listed. Collect them in one place first. For each one, note who wants it and why, and what it costs you.
Unclear who decides. Name the people involved in a RACI matrix. Each decision gets exactly one accountable party. A role is enough; you do not need a name.
Only one option in sight. Do not add filler options to satisfy a template. Look for a real alternative. See Architectural Decision Management.
Too early to decide. Check the last responsible moment. Wait only while waiting keeps your options open. If the moment has come, decide.
No template. Pick one and try it before you record decisions. Markdown Architectural Decision Records and the Y-Statement are both short.

How to do it

Choose what to record. Record only decisions that are hard or costly to change, or that carry high risk or cost. Small local choices stay out, so the log stays small enough to maintain. The integration style is a typical hard-to-reverse decision. See Architecturally Significant Decision and Seven Types of Architectural Decisions.
Check that you are ready to decide. Use the START criteria: stakeholders, time, alternatives, requirements, template. See Architectural Decision Definition of Ready.
Phrase the issue as a short question. For example, “How do we exchange data with system X?” See Architectural Design Issue.
State the context and the drivers. Cover technical, political, social and project aspects. Take the criteria from the context and requirements, not from the properties of the option you prefer. See ADR Common Mistakes and Review Checklist.
List at least two real options. Give pros and cons for each, including the ones you reject. Say why you reject each.
Decide and give the reason. Name the chosen option and say why it won, citing requirements and evidence. Avoid killer phrases and single anecdotes. See Architecture Decision Rationale and Architectural Decision Making Fallacies. If AI helped with a draft, people must check every claim and make the final choice. See GenAI Support for Architectural Decision Records.
List all consequences. Include the negative ones and the price you accept. For a buy-versus-build choice, include the total cost of ownership. For availability, name the cost and complexity of redundancy you accept. See Architectural Decisions for Availability.
Record one decision per record. Use one template. Keep each record short and put design details in separate documents. See Architectural Decision Record.
Link and schedule. Note follow-on decisions and refer to section 4 where relevant. Say when you will review the decision or which change would trigger a review. Mark outdated records as superseded and point to the replacement. See Decision Dependencies and Architectural Decision Management Cycle.

Example: ClinicBook

ClinicBook books appointments for 40 small practices. Each practice already runs its own practice-management software, from different vendors. The team is small and the launch date is fixed. The team looks at its decisions and picks the ones that are costly to change.

Recorded in section 9:

How ClinicBook exchanges data with the practice-management software. It is hard to reverse and touches every practice.
How ClinicBook keeps booking available during morning peaks.

Not recorded: the choice of a date-picker widget in the mobile app. It is local and easy to change.

Fundamental decisions stay in section 4. Section 9 points to them.

The team writes the integration decision as a short record:

Title: Use a ClinicBook-owned calendar with per-vendor adapters to integrate practice-management software

Question: How does ClinicBook exchange appointment data with the practices’ existing software?

Context: The software comes from different vendors and is legacy. The team is small. The launch date is fixed. Bookings must work in morning peaks. Health data needs protection.

Drivers: availability in morning peaks; privacy and security; effort for a small team; launch date.

Options:

Call each practice system live on every booking. Pro: one source of truth. Con: if a practice system is slow or down, booking fails.

Keep the booking calendar in ClinicBook and sync with each practice system through one adapter per vendor. Pro: booking works even when a practice system is down. Con: two copies of the data.

Ask all vendors to implement one common interface. Con: ClinicBook cannot make vendors do this before launch, so it rejects the option.

Decision: Option 2, because availability in morning peaks outweighs the effort of syncing.

Consequences:

Good: booking does not depend on each vendor’s uptime.

Bad: the team must resolve conflicts between the two calendars.

Bad: every new vendor needs a new adapter, which costs effort the small team has little of.

Bad: health data now lives in more places, so privacy work grows.

Review: when a vendor offers a stable standard interface, or when adapter effort threatens the launch date.

Follow-on decisions: how conflicts are resolved; how adapters are tested; how data in transit is protected.

The team also writes the core of it as a one-sentence Y-Statement for the overview: “In the context of integrating with practice software from different vendors, facing the need for booking to work in morning peaks, we decided for a ClinicBook-owned calendar with per-vendor adapters, to gain availability, accepting that we must resolve conflicts between two calendars and build one adapter per vendor.”

The record shows constraints and forces apart. The fixed launch date is a constraint. The effort-versus-availability trade-off is a force the team weighs. The accountable party is a role, such as the lead developer, and the practice-software contact is consulted.

Done when

Section 9 lists only important, costly or risky decisions, and refers to section 4 for the fundamental ones. See arc42 Architecture Decisions.
Each record covers one decision, with a question, context and drivers rooted in real requirements. See Architectural Decision Record.
Each record compares at least two real options and explains why the rejected ones lost. See Architectural Decision Management Cycle.
Each record lists negative consequences as well as positive ones. See ADR Common Mistakes and Review Checklist.
Each record names who decided, and the team accepts the outcome and its rationale. See Definition of Done for Architectural Decisions and RACI Matrix.
Each record says when it will be reviewed, lists follow-on decisions, and points to its replacement if superseded. See Decision Dependencies.