Architecture & structure · Documentation convention
Architecture decision records
Preserve why a consequential choice was made and what follows from it.
What it helps you do
Let a future reader understand the rationale for a choice without reconstructing the original discussion.
Starting knowledge: No specialist knowledge is required.
- Record the concrete problem and constraints.
- State the decision and its status.
- Preserve consequences, alternatives, and the conditions under which to revisit it.
The problem it came from
Michael Nygard’s 2011 article popularized lightweight architecture decision records. He proposed small records for significant decisions rather than a single document that is difficult to keep current.
The core record names context, decision, status, and consequences. Later templates add options, evidence, and review triggers; these are useful adaptations rather than one universal standard.
Work through an example
Context: the guide must have no runtime model costs.
Decision: publish prepared content and browser-side interactions.
Status: accepted for this release.
Consequences: arbitrary visitor documents cannot receive generated feedback.
Revisit: if the desired capabilities change.- The constraint supports the choice.
- The consequence records what the architecture gives up.
- The revisit condition avoids pretending the decision is universal.
Where it helps. Where it stops.
Use it when
- Selecting a data store, policy boundary, output format, or operational approach.
- A team repeatedly revisits a choice because its rationale was lost.
Potential benefits
- An explicit status separates a proposal from an accepted decision.
- Consequences help future maintainers understand the tradeoff they inherit.
Limits and common mistakes
- An ADR records judgment; it does not prove the choice was optimal.
- A stale accepted record must be superseded or revisited rather than silently treated as timeless truth.
The prompt below asks for this structure. It does not guarantee accuracy, complete coverage, better learning, or conformance to a standard. Treat those outcomes as separate checks.
Practise the judgment
Try a choice, inspect a boundary, then explain a case yourself. Hints and answers are available whenever you need them.
A draft suggests replacing a database but nobody has agreed. Which status fits?
Hint
A polished document does not create agreement.
Explained answer
Best answer for this case: Proposed
A record must distinguish a suggestion from a team decision.
The original constraints no longer hold. What should happen?
Hint
Make change traceable.
Explained answer
Best answer for this case: Review the decision and preserve the history when superseding it
Historical rationale remains useful even when a new decision replaces it.
Write one consequence of choosing a static site with no LLM.
Hint
What remains possible entirely in the browser?
Explained answer & self-review rubric
The site can provide prepared examples, rules, and templates, but cannot interpret arbitrary user documents to generate tailored semantic feedback. Visitors can apply templates themselves or in their own tools.
- Connect consequence to choice
- State a real capability boundary
- Avoid claiming all interactivity is impossible
Take it into your own work
Manual template
Use this structure yourself, with a colleague, or in your preferred writing tool.
# Decision record
Title:
Status: proposed / accepted / superseded
Context and constraints:
Options considered:
Decision:
Evidence and assumptions:
Consequences:
Revisit when:
Supersedes / superseded by:
Review the result
- Is the status accurate?
- Can someone reconstruct the reasons?
- Are consequences and revisit conditions concrete?
Use this approach with your own AI tool
Help me apply Architecture decision records to the material below.
Reader and existing knowledge: [describe]
Task and desired outcome: [describe]
Use these principles: Record the concrete problem and constraints.; State the decision and its status.; Preserve consequences, alternatives, and the conditions under which to revisit it..
Preserve source facts, identifiers, quantities, conditions, exceptions, and uncertainty.
Separate supplied facts from assumptions. Ask for missing information instead of inventing it.
Explain your representation choices and provide a review checklist. Do not claim formal compliance or correctness from formatting alone.
Material: [paste only information you are permitted to share]Go to the source
History and the underlying approach are grounded in these references. Examples, prompts, and practice cases here are original educational adaptations. Edition-specific details should be checked against the referenced publication.
Last editorial review: 2026-10-24. An overview is not certification, and this guide is not a reproduction of a standard.