---
title: "Architecture Decision Record Template: Fields and Examples"
description: "A practical architecture decision record template with fields, real examples, and rollout tips for teams working with AI agents on shared code."
url: https://projectify.si/blog/architecture-decision-record-template
updated: 2026-11-02
---
# Architecture Decision Record Template: Fields and Examples
Published 2026-10-18 by the Projectify team · Topics: ADR template, architecture decision record, engineering decisions, AI agent workflow, team documentation
A developer asks why the team stopped using message queues. Someone remembers a cost discussion, someone else remembers a reliability concern, and the answer seems to be buried in a Slack thread. Meanwhile, an AI agent has proposed adding a queue back because nothing in the project explains why it was removed.
## Table of Contents
- [The Decision That Disappeared and Why It Hurt](#the-decision-that-disappeared-and-why-it-hurt)
- [What an ADR is and is not](#what-an-adr-is-and-is-not)
- [The Fields That Actually Get Filled In](#the-fields-that-actually-get-filled-in)
- [ADR field reference](#adr-field-reference)
- [Copyable entries with a purpose](#copyable-entries-with-a-purpose)
- [Three Real Decisions Written With the Template](#three-real-decisions-written-with-the-template)
- [A reversible background-job change](#a-reversible-background-job-change)
- [A harder-to-reverse analytics datastore choice](#a-harder-to-reverse-analytics-datastore-choice)
- [An agent-proposed dependency workflow](#an-agent-proposed-dependency-workflow)
- [Closing the Gaps Most Templates Leave Open](#closing-the-gaps-most-templates-leave-open)
- [Acceptance isn't implementation approval](#acceptance-isnt-implementation-approval)
- [Attribution without blurred authority](#attribution-without-blurred-authority)
- [Rolling the Template Out Without a Fight](#rolling-the-template-out-without-a-fight)
- [A practical adoption schedule](#a-practical-adoption-schedule)
- [Make retrieval part of the pilot](#make-retrieval-part-of-the-pilot)
- [Where ADR Templates Quietly Fail](#where-adr-templates-quietly-fail)
- [Warning signs worth challenging](#warning-signs-worth-challenging)
- [A Scannable Template and How to Wire It Into Your Workflow](#a-scannable-template-and-how-to-wire-it-into-your-workflow)
- [The complete authoring checklist](#the-complete-authoring-checklist)
- [Connect the record to agent work](#connect-the-record-to-agent-work)
## The Decision That Disappeared and Why It Hurt
In that situation, the expensive part isn't finding the old discussion. It's reconstructing which constraints mattered, which alternatives were considered, and whether those constraints still apply. Without that reasoning, the developer and agent can argue convincingly for a change the team previously rejected.
An **architecture decision record template** provides a consistent place to capture that reasoning. The engineer proposing the change writes the record, or an agent drafts it for human review. The accountable person accepts the decision before implementation proceeds.
The modern format is generally traced to Michael Nygard's **November 15, 2011** essay, which proposed short repository-based records with **Status, Context, Decision, and Consequences**, sequential identifiers that aren't reused, and retained records when decisions are superseded ([Documenting Architecture Decisions](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)).
### What an ADR is and is not
The distinctions below describe a recommended operating model, not restrictions inherent to each file format.
| Artifact | Records why | Updates over time | Readable by agents | Append-only history |
|---|---|---|---|---|
| ADR | Explicit rationale and trade-offs | Lifecycle changes; replacement decisions get new records | Yes, with accessible text and structured metadata | Preserve accepted reasoning |
| Design document | May include rationale alongside design detail | Usually revised as the design develops | If accessible | Not necessarily |
| Work item | Usually emphasizes scope and execution | Changes as work progresses | If the agent has access | Activity history isn't a decision chain |
| Chat discussion | Scattered across messages | Conversation continues | Only when available to the session | Doesn't establish which conclusion governs |
An ADR is a **lightweight contract**, not a design specification. It says what the team agreed to, under which conditions, and what costs it knowingly accepted.
> Write the record before or during deliberation. A polished explanation assembled afterward can't preserve alternatives nobody bothered to capture.
The practical deliverable is a field-by-field template, three worked examples, and a rollout plan you can use next week.
## The Fields That Actually Get Filled In
Start with the original core, then add fields that make review and follow-up possible. Microsoft recommends consistent anatomy covering context, rationale, alternatives, trade-offs, confidence, and status, with separate records for phased decisions ([Microsoft's ADR guidance](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record)).
**Keep the field names stable.** Put identifiers, status, and ownership in structured metadata, such as YAML front matter, rather than asking an agent to infer them from prose. The examples below are illustrative copyable entries, not reported production results.
### ADR field reference
| Field | Purpose | What goes wrong if empty |
|---|---|---|
| Identifier | Establish stable identity | References become ambiguous |
| Status | Show whether the decision governs work | Proposals look approved |
| Title | Name the choice precisely | Readers can't scan the collection |
| Date | Establish timing | Readers can't relate the choice to constraints |
| Owners | Assign accountability and approval | Nobody follows up |
| Context | Explain requirements and affected components | The choice looks arbitrary |
| Alternatives | Preserve rejected options and reasons | Reviewers repeat the debate |
| Decision | State the selected response | Implementation proceeds on assumptions |
| Consequences | Expose benefits, costs, and risks | Review becomes advocacy |
| Confidence | Make uncertainty explicit | Assumptions look proven |
| Verification | Define evidence of success or failure | Nobody can invalidate the choice |
| Rollout and rollback | Bound implementation and recovery | Acceptance gets mistaken for readiness |
| Related links | Connect evidence and execution | Readers lose provenance |
### Copyable entries with a purpose
- **Identifier and status:** Establish identity and authority. Example: `id: ADR-JOBS; status: proposed`. Allocate actual identifiers sequentially. Define **accepted**, **superseded**, and **deprecated** explicitly, with deprecated meaning no longer applicable without a replacement.
- **Title:** State the choice, not just the topic. Example: “Store background jobs in the application database.”
- **Date:** Record proposal and acceptance timing separately. Example: “Acceptance date is recorded when the reviewer approves.”
- **Owners:** Separate decision owner, approvers, contributors, and implementation owner. Example: “Maya owns the decision; Sam approves operations; the coding agent contributes the draft.”
- **Context:** Name the problem, requirements, constraints, and components. Example: “The worker must recover interrupted jobs without increasing the platform's operating burden.”
- **Alternatives:** Include credible options and rejection reasons. Example: “Retaining the hosted queue preserves its recovery tooling but doesn't satisfy our simplification objective.”
- **Decision:** Use active language. Example: “We will store pending jobs in the application database.”
- **Consequences:** Separate positive effects, negative effects, and uncertain risks. Example: “We remove a service dependency, add database work, and risk contention during bursts.”
- **Confidence:** Explain uncertainty rather than attaching an unsupported score. Example: “Confidence is moderate because burst behavior remains unverified.”
- **Verification:** Identify tests, metrics, and acceptance boundaries. Example: “The implementation owner checks recovery tests and queue age against the requirements in the linked validation plan.”
- **Rollout and rollback:** State executable transitions. Example: “Pilot with internal jobs; restore hosted processing if recovery checks fail.”
- **Links:** Connect related ADRs, tasks, source artifacts, and successors. Example: “Attach the implementation task, validation results, and any record this decision replaces.”
Keep benchmarks and implementation instructions in supporting documents. The ADR needs enough evidence to explain the choice, not every detail required to build it.
## Three Real Decisions Written With the Template
These are **hypothetical worked examples**, not customer case studies. They show realistic engineering choices using the same fields, with different amounts of supporting detail. Each would inherit the identity, dates, ownership metadata, and linked work defined above.
### A reversible background-job change
**Title:** Store internal background jobs in the application database.
**Context:** The team wants to remove the hosted queue's ongoing cost. Internal jobs can tolerate delayed execution, but they must remain recoverable.
**Alternative:** Keep the hosted queue. Reject it for this scope because the team prioritizes reducing service overhead, provided validation confirms the database approach meets requirements.
**Decision:** Use a database-backed job table for internal jobs only.
**Consequences:** The worker and database become more tightly coupled. The team must implement and test claiming, retries, and recovery rather than assuming the table provides them.
**Owner and verification:** Maya owns the decision. She checks oldest pending job age, failed-job handling, and interrupted-worker recovery against the linked requirements.
**Rollout and rollback:** Pilot an internal job category. Preserve the hosted processing path until recovery passes; stop new database dispatch and reconcile pending jobs before switching back.
That last sentence matters. A rollback that can execute the same job twice isn't a rollback plan.
### A harder-to-reverse analytics datastore choice
**Title:** Use Postgres for the new analytics surface.
**Context:** The planned analytics queries combine related business entities. The team needs a datastore choice before committing schemas and ingestion code.
**Alternatives:** Evaluate a managed NoSQL store and a dedicated analytics platform. In this hypothetical decision, reject the former because the proposed access model requires duplicated representations, and defer the latter because operating a separate analytics pipeline isn't justified by the current requirements.
**Decision and confidence:** Choose Postgres, with moderate confidence pending representative query validation.
**Consequences:** The team accepts responsibility for schema evolution and query tuning. Replacing the datastore later requires data migration and application changes, so this isn't a simple toggle.
**Verification:** Sam checks analytics query latency and ingestion lag against agreed requirements using representative data, then monitors those signals in production.
**Rollout:** Validate the query set before expanding access. If validation fails, pause launch and reopen the datastore proposal rather than improvising a production migration.
### An agent-proposed dependency workflow
**Title:** Allow automated dependency-upgrade pull requests.
**Status and attribution:** The coding agent contributes a proposed ADR. Maya reviews it and becomes the named decision owner and approver when she accepts it.
**Decision:** Automation may open upgrade pull requests, but it may not merge them.
**Alternative:** Continue manual upgrades. Reject that option for routine updates while retaining human review for compatibility and security concerns.
**Verification and rollback:** Require the applicable tests and review checks. Disable automated proposal creation if it generates changes outside the permitted scope; review outstanding pull requests separately.
**Match depth to reversal cost**, while keeping ownership and validation explicit in every example.
## Closing the Gaps Most Templates Leave Open
A decision can be intellectually sound and operationally unfinished. The author may explain every alternative while leaving nobody responsible for migration, monitoring, or checking whether the expected benefit occurred.
Google's ADR outline includes authors, teams, requirements, affected critical user journeys, options, and reasons ([Google's architecture decision record guidance](https://docs.cloud.google.com/architecture/architecture-decision-records)). Those fields establish useful decision context. The operating model proposed here extends that context into implementation and validation.
### Acceptance isn't implementation approval
Separate the person accountable for the choice from the person responsible for delivering it. They can be the same engineer, but the record should say so.
| Operational question | Field that answers it | Evidence to attach |
|---|---|---|
| Who accepts the trade-off? | Decision owner and approvers | Review or approval record |
| Who delivers the change? | Implementation owner | Linked implementation work |
| Who checks the outcome? | Verification owner | Test results and monitoring review |
| Who responds to failure? | Rollback and incident owner | Recovery procedure |
| When can deployment proceed? | Rollout milestones | Completed readiness checks |
An ADR can be **accepted while rollout remains blocked**. For example, reviewers may agree on the database-backed worker while requiring recovery validation before deployment. Record that distinction rather than creating a status that tries to represent decision approval, implementation progress, and operational readiness simultaneously.
> **Review gate:** Don't accept a decision unless someone can identify the evidence that would prove it unsafe, ineffective, or no longer appropriate.
### Attribution without blurred authority
An agent that drafts an ADR isn't the decision-maker. Record the agent as a contributor and identify the person it acted for, then record the human reviewer separately.
For example, an attribution entry might read: **Contributor: coding agent acting for Maya. Decision owner: Maya. Approver: Sam.** The acceptance evidence should point to Sam's review, not merely to a document containing his name.
Enforce that boundary in workflow permissions. An agent shouldn't gain approval authority just because it can edit the status field. Treat the metadata as a description of authorized actions, not a substitute for authorization.
Discoverability has another dimension: project identity. A reader needs to know whether the decision governs this repository, a shared component, or an entire platform. Require an explicit scope and connect the record to the relevant project, work item, source artifact, and successor decision.
The result is a **lightweight control mechanism**. Engineers can inspect not only the reasoning, but also whether the responsible people implemented, verified, and maintained the conditions attached to acceptance.
## Rolling the Template Out Without a Fight
Don't announce a documentation mandate before learning where people lose decisions. Ask engineers about recent handoffs, repeated architecture debates, and changes whose rationale they couldn't find. Use those answers to draft the smallest useful template.
Use this sequence to keep the pilot tied to actual engineering friction.
An incremental approach has research support. A **three-month** action-research study used **seven interviews** before introducing ADRs, finding improvements in documentation culture, knowledge transfer, prioritization, and cooperation, while shared and distributed component challenges remained ([industrial ADR adoption study](https://link.springer.com/chapter/10.1007/978-3-031-70797-1_22)). That's a reason to pilot, not a promise that records will resolve cross-team architecture.
### A practical adoption schedule
Use the **30-, 60-, and 90-day checkpoints** suggested by that incremental adoption approach to evaluate your local workflow, not to claim a guaranteed improvement.
- **By day 30:** Pilot on a project with an active architectural change. Reconstruct a small selection of recent decisions, label them retrospective, and distinguish remembered rationale from surviving evidence.
- **By day 60:** Add an ADR check to the definition of done for architectural changes. Review whether authors can fill the fields without duplicating an entire design document.
- **By day 90:** Audit current records. Supersede replaced choices, deprecate those that no longer apply, and investigate verification commitments nobody checked.
Baseline the **percentage of significant decisions with recorded rationale**, **median time to locate the governing decision**, and **decisions reopened because consequences were unknown**. Also count records with overdue verification. These are proposed local measures, not industry benchmarks.
### Make retrieval part of the pilot
Keep the canonical record in an accessible, versioned location. Link it from the code repository, project, and work item rather than maintaining competing copies in each place.
Test retrieval with a developer and a fresh agent session. Ask each to identify the governing decision, its scope, and its validation evidence without assistance. If either needs someone to explain where it lives, the rollout isn't finished.
For a discussion alongside the pilot, use the accompanying video.
## Where ADR Templates Quietly Fail
An impressive template doesn't prove that engineers are using it. The **2025 software-architecture survey** reported **48% of respondents using ADRs and 52% not using them**, a respondent split rather than a universal industry adoption rate ([State of Software Architecture Survey 2025](https://icepanel.io/blog/state-of-software-architecture-survey-2025)).
The wrong response is to demand more documents. Inspect whether the records help someone make or revisit a decision.
### Warning signs worth challenging
- **Every commit gets an ADR:** Reviewers spend their attention on routine edits. Reserve records for material structural, dependency, interface, or operational choices.
- **Alternatives contain only names:** Listing a database and a queue doesn't explain why either lost. Require the constraint or trade-off that ruled each option out.
- **Obsolete records still look authoritative:** A reader can follow the document correctly and still implement the wrong thing. Audit lifecycle transitions, not just file existence.
- **The collection has no entry point:** An unindexed wiki or unlinked folder requires insider knowledge. Test the discovery path instead of assuming storage equals access.
- **Everything arrives already accepted:** Reviewers receive an approval form rather than a live proposal. Ask whether they had a genuine opportunity to change the choice.
Retrospective records can recover useful history, but they must disclose missing evidence. Don't let an agent fill those gaps with plausible reasoning and present it as the team's original deliberation.
> The value isn't the document count. It's the discipline of exposing alternatives and consequences while the choice can still change.
A rollout that permits owner-less, post-hoc assertions has introduced paperwork, not a reliable decision practice.
## A Scannable Template and How to Wire It Into Your Workflow
Use this checklist beside the canonical ADR location. Keep the full field set even when a small decision needs only a sentence per field. Mark inapplicable fields explicitly instead of leaving blanks that readers can't interpret.
The visual captures the identity and accountability fields that should be immediately scannable.
### The complete authoring checklist
- **Identity:** Identifier, precise title, proposal date, acceptance date, and machine-readable status.
- **Accountability:** Decision owner, approvers, implementation owner, and contributors, including any agent and the person it represents.
- **Context:** Architectural problem, business requirements, measurable constraints, affected components, and scope.
- **Options:** Credible alternatives and the reasons for rejecting them.
- **Decision:** Selected option and rationale in active language.
- **Consequences:** Positive effects, negative effects, risks, and conditions that would invalidate the choice.
- **Confidence:** Current uncertainty, assumptions, and evidence still needed.
- **Verification:** Responsible reviewer, tests, metrics, dashboards, and requirement boundaries.
- **Execution:** Rollout milestones, rollback conditions, recovery ownership, and linked implementation tasks.
- **Relationships:** Project, source artifacts, supporting evidence, related ADRs, `supersedes`, and `superseded_by`.
### Connect the record to agent work
When an agent proposes an architectural change, require a draft with **status: proposed** and explicit contributor attribution. The human reviewer checks the constraints, challenges the alternatives, and authorizes acceptance through the review workflow. Only then should the accepted decision govern implementation.
Keep execution progress in linked tasks and handoffs. Attach validation evidence to the record's verification references so another session can distinguish promised checks from completed checks.
At session start, retrieve applicable accepted ADRs by project and component scope, then follow replacement references. If the implementation conflicts with the governing decision, the agent should flag the discrepancy and propose a replacement record, not rewrite accepted reasoning.
Next week, choose a recent decision whose rationale someone has already asked about. Write it using this template, link it from the work item, and have the next agent session retrieve it before changing the affected component. You'll learn more from that retrieval test than from another debate about template formatting.
---
Projectify offers shared project work, decision records that agents propose and people accept, and attributed activity for human-agent teams. Visit [Projectify](https://projectify.si) to connect architectural decisions to tasks and handoffs, so the next session starts with the rationale instead of another explanation in chat.