John D. Gómez

Technical decisions

Leave a decision that someone else can carry forward

What context to preserve so a technical decision can be implemented and reviewed without relying on one person’s memory.

Approving an option closes a conversation. For the work to continue, the team needs to preserve why that option was reasonable, under which conditions and what might require changing it. Someone who was not at the meeting should be able to retrieve that information.

Record what matters

Microsoft recommends preserving the context, alternatives and consequences of architecture decisions [1]. The following checklist adds practical questions for implementation and review.

Make assumptions visible

A volume estimate, a delivery date or a supplier’s capability can change. Identify which conditions support the decision and what signal would justify reopening it. Revisiting the direction then responds to new information rather than shifting preferences.

Match the effort to the consequences

A change that is easy to reverse may need only a brief note and a test. A migration affecting data, contracts or people requires more investigation. The document’s length should serve the decision, not a template that requires the same content in every case.

Test whether the decision can be handed over

Give the record to a teammate and ask them to explain what they need to do and what they must not compromise. The questions that arise help improve the decision before those gaps turn into rework.

References

[1]
Microsoft, “Maintain an architecture decision record (ADR),” Microsoft Learn. Accessed: Sep. 23, 2026. [Online]. Available: https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record

Read sourceSource recordAuthor notes: MicrosoftReturn to text 1

Download references: CSL JSON · BibTeX

Update history

Source-supported statements were clarified and standardized citations and references were added.