architecture

name	architecture
description	Make defensible architecture decisions by translating requirements into trade-offs and ADRs. Use when choosing styles, components, or integration approaches that need a documented rationale.
risk	unknown
source	community
date_added	2026-02-27

Architecture Decision Framework

Architecture is the set of decisions hard to change later. This skill turns requirements and constraints into evaluated options and durable decision records using MADR 4.x ADRs, the C4 model, and ISO/IEC 25010:2023 quality attributes.

Stack Baseline (2026)

Concern	Recommended
Decision record format	MADR 4.x in /docs/adr (one ADR per decision)
Quality model	ISO/IEC 25010:2023
Architecture description	ISO/IEC/IEEE 42010:2022 (concerns, viewpoints, views)
Diagrams	C4 model (Structurizr DSL or Mermaid C4)
Discovery template	arc42 sections 1, 2, 3, 9, 10
Trade-off framework	Cost / Risk / Benefit matrix + sensitivity to each quality attribute
Currency signal	ThoughtWorks Tech Radar; internal Adopt/Trial/Hold list

When to Use

• Choosing between styles, frameworks, datastores, or integration models.
• Recording a significant decision before implementation.
• Revisiting an existing decision because constraints or context changed.
• Onboarding a new system and reconstructing missing rationale.

Prerequisites

• Documented functional and quality attribute requirements.
• Known constraints: budget, compliance, team skills, deadlines.
• Two or more candidate options worth comparing (no straw-man).
• A decision owner accountable for outcomes.

Instructions

flowchart LR
    R[Requirements + constraints] --> O[Generate 2-4 options]
    O --> T[Trade-off analysis]
    T --> D[Decide and record ADR]
    D --> V[Validate with fitness functions]
    V -->|drift| O

1. Frame the decision. State the question in one sentence ("How do we propagate order events to billing?"). Identify decision owner, deadline, and reversibility (one-way vs two-way door).
2. Capture drivers. List functional needs and the 3-5 quality attributes that dominate (e.g., consistency, latency p99, regulatory locality).
3. Generate options. Produce 2-4 realistic options. Reject any straw-man. Include a "do nothing / extend current" option.
4. Score trade-offs. For each option, score against the dominant quality attributes plus cost, risk, team fit, and time-to-value. Note sensitivities — what assumption, if wrong, flips the decision?
5. Decide. Choose, name the decision owner, and record an ADR using MADR 4.x. Status begins as Proposed and moves to Accepted after review.
6. Define fitness functions. Specify automated or periodic checks that prove the decision still holds (latency probe, dependency scan, architectural test).
7. Communicate. Link the ADR from the C4 view it changes, the team handbook, and any affected runbook.

ADR skeleton (MADR 4.x):

# ADR-NNNN: <decision title>
Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
Date: YYYY-MM-DD
Deciders: <names>
Context: <forces, constraints, drivers>
Options:
  - Option A: ...
  - Option B: ...
Decision: <chosen option and why>
Consequences: <positive, negative, follow-ups>
Fitness functions: <how we will know this is still right>

Common Pitfalls

Pitfall	Why it hurts	Mitigation
Deciding before defining quality attributes	Optimizes the wrong axis	Anchor every decision to ISO/IEC 25010:2023 attributes
One-option ADRs	No real evaluation	Require >=2 credible options including status quo
Treating reversible and irreversible decisions the same	Slows trivial calls, rushes critical ones	Tag one-way vs two-way doors and adjust rigor
ADRs as prose only	Searchable but not testable	Add fitness functions and link from code/CI
Ignoring team skill fit	Beautiful design, failed delivery	Include team capability as an explicit driver
Stale ADRs	Misleading newcomers	Quarterly review; mark Deprecated/Superseded promptly

Output Format

# Decision: <one-sentence question>
- Owner: <name> | Reversibility: one-way | Due: YYYY-MM-DD

## Drivers and Quality Attributes
## Options Considered (A, B, C)
## Trade-off Matrix (attribute x option, with weights)
## Decision and Rationale
## Consequences (positive / negative / follow-up actions)
## Fitness Functions
## Links: ADR-NNNN, C4 view(s), affected runbooks

Authoritative References

• Mark Richards & Neal Ford, Fundamentals of Software Architecture, 2e.
• Neal Ford et al., Software Architecture: The Hard Parts.
• Gregor Hohpe, The Software Architect Elevator.
• MADR 4.x: https://adr.github.io/madr/.
• ISO/IEC/IEEE 42010:2022; ISO/IEC 25010:2023.
• C4 model: https://c4model.com; arc42: https://arc42.org.
• ThoughtWorks Technology Radar: https://www.thoughtworks.com/radar.