architecture-decision-records

An architecture decision record captures context, forces, options considered including rejected alternatives, the chosen decision, and explicit consequences. It records decision context and tradeoffs in a portable Markdown format with explicit status and links to verification checks.

Architecture governance requires an ADR to include context, forces, options considered, rejected alternatives, consequences, status, supersession, and follow-up verification. It must explicitly link to implementation surfaces so the decision's validity remains trackable for future audits.

You need an architecture decision record when your team debates a significant technical choice, such as migrating critical configuration to a new storage approach. It captures the tradeoffs, migration obligations, and verification steps so future readers understand the rationale without relying on vanished discussions.

Reviewing an architecture decision record involves ensuring rejected options are concrete and consequences include costs and risks. The audit verifies that status and supersession are clear, and that the document maintains links to implementation surfaces and follow-up verification checks.

Yes, architecture decision records use a portable Markdown discipline to document decisions. You track status over time by explicitly recording the current status and supersession links, ensuring that any updates or replacements to the original decision are clearly documented for future readers.

The best way to document rejected alternatives in an architecture decision log is to record them as concrete options alongside the chosen decision. Including the specific costs, risks, and consequences of each rejected option ensures the rationale is durable and understandable for future verification.