← Back to principles
Architecture
Decisions Are Intentional and Recorded
Statement
Decisions Are Intentional and Recorded
What this means in practice
Significant architectural decisions are explicitly recorded with clear rationale, trade-offs, and constraints. Documentation is concise, purposeful, and kept current, reflecting the actual state of the system rather than theoretical designs. Decisions are made deliberately rather than by default or drift.
Why this matters
Recorded, intentional decisions preserve architectural understanding and enable change with confidence. Without this, teams repeat past debates, reverse decisions unknowingly, and struggle to assess change impact. Knowledge is lost when people move on, slowing delivery and leading to inconsistent or fragmented architecture.
Practices that meet this principle
Architecture Decision Records (ADRs) or equivalent lightweight records are maintained for significant decisions
Each record captures context, options considered, rationale, and known trade-offs
Decision records are version-controlled and accessible to the delivery team
Records are reviewed and updated when decisions are revisited or superseded
Decision-making forums or checkpoints exist to ensure decisions are made explicitly
Validation
A project meets this principle when:
Significant architecture decisions are documented with rationale and trade-offs
Decision records are accessible, current, and version-controlled
OR:
Superseded decisions are clearly marked and linked to their replacements
Scoring Guide
Score −1 — Disagreement / Rejected: The team acknowledges this principle is applicable but has explicitly decided not to follow it for this product. A rationale and decision record exist explaining why intentional decision recording is not adopted.
Score 0 — Not doing: Significant decisions are made informally or by default. No decision records exist. Rationale and trade-offs are not captured. Past decisions cannot be located or referenced.
Score 1 — Planned: The team has committed work to adopt intentional decision recording. An owner and target date exist for introducing ADRs or equivalent lightweight records. The plan is tracked.
Score 2 — Adopted for new work: All significant decisions for new work are recorded with context, options, rationale, and trade-offs. Records are version-controlled, accessible, and reviewed when decisions are revisited. A defined process exists for capturing decisions. Any exceptions are explicit and reviewed.
Score 3 — Enforced for new work + migration plan: Intentional decision recording is systematically enforced for all new work through process or tooling (e.g. mandatory ADR templates, decision review gates). A tracked migration plan exists to document key legacy decisions and bring existing records into a consistent, current state.
Score 4 — Fully adhered: Decision records are comprehensive across all work. Records are current, version-controlled, and actively maintained. Superseded decisions are clearly marked and linked. Teams routinely reference records when assessing change. Decision-making forums ensure decisions are always made explicitly. Remaining gaps are minimal, known, and time-bound.