Create Architectural Decision Record

What Is This?

Overview

Architectural Decision Records capture significant technical choices with their context, options considered, and consequences, creating searchable history explaining why systems are built certain ways and guiding future decisions. Software architecture decisions shape system design for years, but context and rationale fade quickly without documentation.

Create Architectural Decision Record generates structured ADR documents following established formats. Each record includes decision context and problem statement, options evaluated with tradeoffs, chosen solution with justification, and expected consequences both positive and negative. Records receive sequential numbers and immutable storage preserving decision history.

ADRs document significant choices about frameworks, patterns, infrastructure, data storage, and system boundaries. They create organizational memory explaining not just what was decided but why, what alternatives existed, and what tradeoffs were accepted.

Who Should Use This

Software architects, technical leads, engineering managers, platform teams, and developers proposing or overseeing architectural changes. Any team wanting decision transparency and searchable history.

Why Use It?

Problems It Solves

Architectural decisions lack documentation, causing confusion months later about why systems work certain ways. ADRs capture reasoning when context is fresh.

Teams repeatedly debate settled questions because previous decisions are forgotten. Searchable ADR history shows past discussions and conclusions, preventing redundant debate.

New team members struggle understanding system design rationale. An ADR collection provides a learning resource explaining architectural evolution and the tradeoffs accepted along the way.

Changing requirements prompt revisiting past decisions, but original tradeoffs are lost. ADRs document what problems decisions solved, enabling informed reconsideration rather than guesswork.

Core Highlights

Structured documentation format with context and problem statement. Options evaluation with explicit tradeoffs. Decision justification and rationale. Consequence identification, both positive and negative. Sequential numbering for easy reference. Immutable records preserving history. Searchable decision database.

How to Use It?

Basic Usage

Describe the architectural decision to document, including the problem, options considered, and chosen solution. The skill generates an ADR following standard format with appropriate sections.

Create ADR for choosing PostgreSQL over MongoDB
for our primary datastore

Generate architectural decision record documenting
our move to microservices architecture

Specific Scenarios

For framework selection, emphasize evaluation criteria and team experience. For infrastructure choices, highlight operational concerns and scaling needs. For pattern decisions, explain applicability and long-term consequences.

Document decision to use React over Vue
considering team experience and ecosystem

Create ADR for Kubernetes adoption
covering scaling needs and operational complexity

Real World Examples

A team debates REST versus GraphQL for a new API. Discussions happen in meetings and chat but no formal decision is recorded. Six months later, new developers question why GraphQL was not used and original context is lost. Using ADR practice, the team documents decision context including client needs and team experience, evaluates both options with specific tradeoffs, records the REST choice based on simpler operations and better team expertise, and notes the consequence of potentially needing migration if query flexibility becomes critical.

An architecture team adopts event-driven architecture for a new platform, a major shift with lasting consequences. Their ADR documents the context of increasing system coupling and scaling challenges, evaluates continued monolith, synchronous microservices, and event-driven approaches, records the decision to use event-driven with Kafka, and captures expected consequences including improved scalability alongside increased operational complexity. The ADR guides implementation teams and explains the approach to stakeholders.

A startup chooses managed cloud services over self-hosted infrastructure. The ADR captures the context of a small team with limited operations expertise, evaluates self-hosted Kubernetes against fully managed services, documents the choice accepting higher costs for faster delivery, and notes vendor lock-in risk alongside immediate productivity gains. When the company grows and hires operations engineers, the ADR provides clear context for revisiting the decision.

Advanced Tips

Write ADRs when decisions are made while context is fresh. Include links to supporting discussions or documents. Store in version control with code. Use a consistent template across the organization. Mark superseded ADRs clearly, linking to replacements. Review ADRs during onboarding and architecture reviews.

When to Use It?

Use Cases

Framework and library selection. Infrastructure and platform decisions. Data storage technology choices. Architectural pattern adoption. Security and authentication approaches. System boundary definition. Technology migration decisions.

Important Notes

Requirements

Clear decision with defined options. Understanding of context and constraints. Knowledge of tradeoffs. Awareness of expected consequences. Commitment to documenting decisions consistently.

Limitations

Requires discipline to maintain consistently and only delivers value if the team actually writes records. Cannot capture all nuance of complex decisions and may feel like overhead initially. Quality depends on thoroughness, and old ADRs may not reflect current understanding. Ultimately requires cultural commitment to documentation.