LEARN. PRACTICE. GROW.Concept and mechanism
An architecture decision should be reconstructable: which problem existed, which options were considered, what constrained the choice, and which consequences were accepted. An ADR preserves that memory without repeating the entire detailed design. When an accepted decision changes, a new record should explain why and link to the superseded decision, retaining earlier context. Record relevant uncertainties as well. A proof of concept can answer a limited question, such as compatibility or performance on one dataset, but does not itself establish security, recovery, or operational readiness. Define the hypothesis and observation criterion before starting the experiment.
Guided application
In a fictional exercise, a local search is fast with one thousand records, but the service must support twenty million and a remote dependency. The team should not extrapolate without examining volume, data distribution, networking, and failures. Prepare a representative experiment and identify what remains outside its scope. If the result changes the selected option, update decision history with the new evidence and inform affected consumers. Compare available skills, maintenance, and platform conditions as well. A technically possible option can remain unsuitable for the deadline or existing support capability.
A proof of concept validates a bounded hypothesis; production entry needs explicit additional work.
Common pitfalls
Prototype treated as a product; ADR without consequences; deleted decision history; benchmark without context.
Related topics: Mandate and technical direction · Review, quality, and feedback · Integration, flow, and technical debt
Keep reasons, alternatives, and evidence limits accessible to the team.
Reference: Maintain an architecture decision record · Google Engineering Practices, SRE and DORA; Microsoft architecture decision and collaboration guidance; OWASP threat modeling; UK lead developer framework; inspected 2026-10-01