THE GITHTML FIELD GUIDE
Architecture decision record template with review triggers
Use an architecture decision record to explain one consequential choice, not to summarize an entire system. Capture the problem, the options considered, the selected approach, and the consequences. Include evidence and a condition that would reopen the decision so future readers can distinguish a deliberate tradeoff from an obsolete assumption.
Define the decision boundary
Start with a title that names the choice: where to validate an import, which service owns a workflow, or whether a queue is necessary. Add status, date, decision owner, and the repository revision reviewed. Proposed and accepted records should look different. Write the constraint that makes this decision necessary before describing a solution. The ADR community describes a record as one decision plus its rationale; your surrounding implementation guide can remain separate. Avoid turning the record into a vote count or a transcript of every meeting.
Fill a small, testable template
An illustrative import decision could read: Context: uploaded files may contain invalid rows. Options: reject the whole file, import valid rows, or stage a preview. Decision: stage a preview before confirmation. Consequence: storage and cleanup become explicit responsibilities. Evidence: link the parser, upload limit, and product requirement at the reviewed revision. Revisit when files exceed the documented staging capacity. This example is a writing pattern, not a recommendation for every import system. Name the cost you accepted and explain why the rejected options failed the actual constraints.
- Write the decision in one sentence that can be challenged.
- List an advantage and a cost for each serious alternative.
- Assign an owner to the unresolved follow-up, not merely to the document.
Preserve history when circumstances change
Do not silently rewrite an accepted decision to match today's implementation. Mark it superseded and link the replacement, preserving the original reasoning for maintainers investigating older behavior. Review each evidence link before publication, especially when a source points to a moving branch. Put the decision, status, and consequences near the top of the HTML page for a quick phone review. A later reader should be able to answer what was chosen, why it was reasonable then, and what changed without opening a discussion archive.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.