designing-systems

Document architecture decisions by creating an Architecture Decision Record (ADR) that frames the problem, evaluates viable options, and justifies the chosen approach. This provides a structured, auditable record under .context/decisions/ to prevent relitigating resolved technical debates.

Write an ADR when introducing a new technology or service, designing system components like schema or API contracts, refactoring at non-trivial scale, or resolving competing technical approaches. Do not use it for implementation details, naming conventions, or one-off decisions with obvious rationale.

An Architecture Decision Record should include the context of the design problem, the chosen decision, evaluated options, the rationale justifying the approach, and the resulting consequences. This structure ensures the technical reasoning is auditable and traceable.

Update or supersede prior ADRs to reflect evolving decisions and maintain traceability. By documenting the new context, options, and rationale in a new Architecture Decision Record, teams keep an auditable history of why previous technical approaches were replaced.

Yes, documenting API contracts and service boundaries is a primary use case for an ADR. Framing the design problem, evaluating service boundary options, and recording the rationale provides clear architectural guidance for system design.

The best way to evaluate competing technical approaches during a non-trivial refactor is to frame the design problem, evaluate at least two viable options, and justify the chosen approach in an Architecture Decision Record to ensure the reasoning is auditable.