Design rationale

Design rationale is the explicit documentation of the reasoning behind a decision made in designing an architectural element. Per ISO/IEC/IEEE 42010, a rationale records the basis for a decision that has already been made, including the alternatives considered, the trade-offs weighed between them, the decision’s expected consequences, and citations to any further sources that informed it.

A rationale is what turns a record of what was decided into an account of why — the part a future maintainer actually needs, since the decision itself is usually visible in the code or the architecture views regardless. Capturing it as it is made, rather than reconstructing it after the fact, is a core activity of architectural knowledge management. The architecture decision record (ADR) is the most common lightweight format for doing so.

See also