Why ADRs Matter: Capturing Architectural Decisions with Purpose

Why ADRs Matter: Capturing Architectural Decisions with Purpose Have you ever looked at a piece of code and asked yourself, "Why did we do it this way?" Welcome to the world of Architecture Decision Records (ADR) — a simple but powerful technique to preserve the "why" behind technical decisions in your projects. What Problem Does ADR Solve? In every software project, decisions are made. We decide which framework to use, why a service communicates over REST instead of gRPC, or why a particular domain model was split into two bounded contexts. But over time, people leave, contexts shift, and the reasoning behind those choices gets lost. ADR is the answer to the question “Why did we do this?” It gives a voice to decisions, capturing not just the what, but more importantly, the why. It’s not enough to read the code — ADRs give you the intent behind it. What Is an ADR? An Architecture Decision Record is a short text document describing a single architectural decision. That’s it. Each ADR should be: Immutably stored – Once created, the document should not change. And should not be removed! Dated and versioned – You need to know when the decision was made. Status-driven – A decision can be Proposed, Accepted, Deprecated, Superseded, or Obsolete. Tracked over time – The collection of ADRs forms a historical timeline of the architecture. The Structure of an ADR A typical ADR document includes the following sections: Title – Short and descriptive (e.g. “Use PostgreSQL as main data store”) Status – Current state of the decision (Accepted, Rejected, etc.) Context – The background and forces at play when the decision was made. Decision – What was decided, clearly stated. Consequences – What happens as a result of this decision. If you're wondering where the "why" is captured — it's mainly in the Context section. This is where you describe the situation, constraints, trade-offs, or previous options that led to this particular choice. Without it, the decision is just a fact. With it, it becomes a rationale. Why Not Just Use Jira Tickets or Docs? Because those are too broad or ephemeral. ADRs are focused, atomic, and always close to the codebase. They’re typically stored in the repository itself, usually in a folder like /docs/adr/, making them accessible to everyone in the team — including reviewers, future contributors, and stakeholders. They’re also just Markdown. This simplicity ensures they’re easy to read, version, and integrate into your tooling. Sylius ADRs Looking for real-world examples? Sylius, an open-source e-commerce platform, uses ADRs to capture and document its architectural decisions. These records are publicly available in their GitHub repository and provide a great reference for how ADRs can be structured and written in practice.

Apr 7, 2025 - 10:40

Why ADRs Matter: Capturing Architectural Decisions with Purpose

Have you ever looked at a piece of code and asked yourself, "Why did we do it this way?"

Welcome to the world of Architecture Decision Records (ADR) — a simple but powerful technique to preserve the "why" behind technical decisions in your projects.

What Problem Does ADR Solve?

In every software project, decisions are made. We decide which framework to use, why a service communicates over REST instead of gRPC, or why a particular domain model was split into two bounded contexts. But over time, people leave, contexts shift, and the reasoning behind those choices gets lost.

ADR is the answer to the question “Why did we do this?”

It gives a voice to decisions, capturing not just the what, but more importantly, the why. It’s not enough to read the code — ADRs give you the intent behind it.

What Is an ADR?

An Architecture Decision Record is a short text document describing a single architectural decision. That’s it. Each ADR should be:

Immutably stored – Once created, the document should not change. And should not be removed!
Dated and versioned – You need to know when the decision was made.
Status-driven – A decision can be Proposed, Accepted, Deprecated, Superseded, or Obsolete.
Tracked over time – The collection of ADRs forms a historical timeline of the architecture.

The Structure of an ADR

A typical ADR document includes the following sections:

Title – Short and descriptive (e.g. “Use PostgreSQL as main data store”)
Status – Current state of the decision (Accepted, Rejected, etc.)
Context – The background and forces at play when the decision was made.
Decision – What was decided, clearly stated.
Consequences – What happens as a result of this decision.

If you're wondering where the "why" is captured — it's mainly in the Context section. This is where you describe the situation, constraints, trade-offs, or previous options that led to this particular choice. Without it, the decision is just a fact. With it, it becomes a rationale.

Why Not Just Use Jira Tickets or Docs?

Because those are too broad or ephemeral. ADRs are focused, atomic, and always close to the codebase. They’re typically stored in the repository itself, usually in a folder like /docs/adr/, making them accessible to everyone in the team — including reviewers, future contributors, and stakeholders.

They’re also just Markdown. This simplicity ensures they’re easy to read, version, and integrate into your tooling.

Sylius ADRs

Looking for real-world examples? Sylius, an open-source e-commerce platform, uses ADRs to capture and document its architectural decisions. These records are publicly available in their GitHub repository and provide a great reference for how ADRs can be structured and written in practice.