Architecture Decision Records

Originated by Michael Nygard (Documenting Architecture Decisions, 2011).

Records each significant decision in a short numbered note giving its context, the choice made, and its consequences, stored beside the work it governs.

When to reach for it

Any decision that will have to be explained to newcomers or reopened months later, whose reasoning would otherwise live only in memory.

How it runs

1. Open a new numbered record for each significant decision.
2. Write the context: the situation, forces, and constraints.
3. State the decision in one active sentence.
4. List the consequences: what it enables, what it costs, what follows.
5. Mark the status, and link any later record that replaces it.

Where it sits in SOLVE eX

• 6.4 Conducting Follow-Up and Taking Feedback
• 3.2 Finding the Past Facts

Go to the source

• Documenting Architecture Decisions, Cognitect blog, 15 November 2011, 2011