Architecture Decisions

Use an Architecture Decision Record (ADR) for a choice that will constrain future work or otherwise be expensive to rediscover.

Good ADR subjects include persistence models, compatibility strategy, identity schemes, protocol boundaries, framework selection and cross-product service contracts. Routine implementation details do not need an ADR.

Decision states

• Proposed — under review.
• Accepted — current decision.
• Superseded — replaced by a newer ADR; retain the old record and link both directions.
• Rejected — considered but not chosen; retain when the rejected option is likely to recur.

An ADR should explain context, decision, alternatives, consequences and follow-up work. Use Templates/Architecture-Decision-Record.