| 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
- 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).
- Capture drivers. List functional needs and the 3-5 quality attributes that dominate (e.g., consistency, latency p99, regulatory locality).
- Generate options. Produce 2-4 realistic options. Reject any straw-man. Include a "do nothing / extend current" option.
- 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?
- Decide. Choose, name the decision owner, and record an ADR using MADR 4.x. Status begins as
Proposed and moves to Accepted after review.
- Define fitness functions. Specify automated or periodic checks that prove the decision still holds (latency probe, dependency scan, architectural test).
- 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
