Topic: Decision documentation scope
ADR vs Decision Register — When to Use Each and How They Fit Together
Architecture Decision Records and decision registers are frequently confused because they both document decisions. They are not the same tool, they are not competing tools, and the most common mistake is trying to replace one with the other. An ADR is an immutable engineering-rationale record written for engineers. A decision register is a living project-management artifact written for stakeholders. This page explains the distinction, the overlap zone where both apply, and how to avoid the duplication trap.
TL;DR
ADR directory: engineering decisions, immutable rationale, lives in the code repo, audience is engineers. Decision register: all project decisions, living status tracking with RACI, lives in a PM tool, audience is stakeholders and auditors. Use ADRs for architecture calls. Use a decision register for cross-functional governance. Use both — with the ADR URL referenced from the register entry — for architecture decisions that also carry project-level impact.
What a decision register is
A decision register is a project management artifact rooted in formal PM methodologies (PRINCE2, PMBOK, ISO 21500). Its purpose is to ensure that every significant decision made during a project is recorded, attributed to an accountable owner, and visible to all stakeholders. Unlike an ADR, a register entry is not primarily about preserving rationale — it is about accountability and traceability across a project's lifecycle.
A typical decision register entry has these fields:
| Field | Purpose | Example |
|---|---|---|
| Decision ID | Unique reference for linking (DEC-0042) | DEC-0042 |
| Title | One-line summary | Select primary database engine |
| Date | When the decision was made | 2026-05-15 |
| Decision maker | RACI "Accountable" — one person | VP Engineering |
| Consulted | RACI "Consulted" — people asked before the decision | CTO, DBA lead |
| Decision | What was decided | Use Postgres as the primary relational store |
| Rationale | Why, at a summary level | Team has operational expertise; JSONB covers semi-structured needs |
| Alternatives | What was considered | MySQL, CockroachDB |
| Impact | Which teams, budget, timeline are affected | Platform team: 3-week migration; licensing: $0 (OSS) |
| Risk level | High / Medium / Low | Low |
| Status | Open / Deferred / Closed | Closed |
| Review date | When to re-evaluate | 2027-05-15 (annual) |
| Related docs | ADR, RFC, design doc links | /doc/decisions/0042-postgres.md |
The register is mutable. When status changes, when a decision is deferred, when a review date passes — the entry is updated in place. This is fundamentally different from an ADR, which is immutable once accepted. A "change" to an ADR requires writing a new ADR that supersedes the old one; the old ADR is marked Superseded, not edited.
What an ADR is
An Architecture Decision Record is an engineering artifact that preserves the rationale behind a specific architectural or technical choice in the form that will be most useful to a future engineer working on the same system. The audience is not stakeholders or auditors — it is the engineer who will read the ADR twelve months from now when they are debugging a constraint that exists because of the decision, or evaluating whether the decision should be revisited.
The ADR's defining properties:
- Immutability. Once an ADR is accepted, the body is never edited. Context shifts and status transitions are recorded in a dated Notes append; the original Decision and Consequences sections remain as written on the day of acceptance. This preserves what was known — and what was not yet known — at the time of the decision.
- Rationale depth. An ADR carries the full reasoning: the constraint that made this decision necessary (Context), what was considered and why it was insufficient (Alternatives considered or Decision body), and what becomes harder and what becomes easier as a result (Consequences). A decision register entry summarises the rationale in two sentences; an ADR may run to several hundred words of reasoning that would be too detailed for a PM register but is essential for engineering understanding.
- Co-location with code. ADRs live in the code repository — typically
doc/decisions/— so they version alongside the code they describe. When a developer checks out a branch, they get the ADRs that were valid on that branch. When an ADR is superseded, the supersession PR contains both the old ADR (now Superseded) and the new ADR (now Accepted), making the decision history traceable via git log. - Engineering scope. ADRs document decisions within the scope of what engineers decide: technology choices, architectural patterns, data models, API contracts, dependency selections, deployment strategies. They do not document procurement decisions, budget allocations, staffing calls, or scope changes — those belong in a decision register, not an ADR directory.
The five-dimension comparison
| Dimension | ADR directory | Decision register |
|---|---|---|
| Scope | Architecture and technical decisions only | All significant project decisions across all domains |
| Primary audience | Engineers (current and future) | PMs, stakeholders, executives, auditors |
| Mutability | Immutable once Accepted — changes require a new superseding ADR | Mutable — status, review date, and impact fields are updated in place |
| Storage | Code repository (doc/decisions/), versioned with git | PM tool (JIRA, Confluence, Notion, spreadsheet, SharePoint) |
| Rationale depth | Full — Context paragraph, Alternatives with rejection rationale, Consequences with downsides | Summary — two to four sentences covering what and why |
Three ways teams get this wrong
1. Trying to use the ADR format for all decisions
Some teams, after adopting ADRs for engineering work, attempt to use the same format for every organisational decision: vendor contracts, headcount approvals, budget allocations, scope reductions. The result is an ADR directory that mixes engineering rationale records with what are effectively management meeting minutes, written in a format that is too heavy for PM purposes (the RACI fields don't map to ADR fields) and too volatile for engineering purposes (these decisions get reopened, deferred, escalated — behavior that ADR's immutability discipline doesn't support well).
The fix: ADRs for engineering scope, decision register for project-management scope. The two coexist without conflict because their audiences and storage locations don't overlap.
2. Trying to replace ADRs with a decision register
The opposite mistake: a PM lead adopts a decision register for the project and argues that ADRs are redundant because "we already log every decision." The register captures the summary — enough for project tracking — but loses the depth that makes the ADR useful. The engineer who encounters an architectural constraint 18 months later needs to know not just that Postgres was chosen but why CockroachDB was ruled out (turned out the CRDB's transaction semantics had an edge case in the specific query pattern the team uses), what the operational implication was (the team had to build a custom read-replica health-check because the decision predated the pgBouncer migration), and which constraint is now the actual load-bearing reason the system works the way it does.
A decision register entry cannot carry that depth without becoming an ADR by another name. The register's value is precisely its brevity and its status-lifecycle fields, both of which an ADR deliberately lacks.
3. Maintaining duplicate records with diverging content
The most insidious failure mode: the team has both an ADR directory and a decision register, but updates them separately. The register entry for DEC-0042 says the database decision was "Closed" but the ADR says "Proposed" (the PR that changes it to Accepted never merged). Or the ADR has Consequences that include a significant operational downside, but the register entry's Impact field still says "Low" from the original estimate. Future readers get contradictory signals.
The fix is to treat the ADR as the authoritative source for engineering rationale and the register as the authoritative source for governance status. The register entry's Related docs field points to the ADR URL; the ADR does not attempt to duplicate the register's status-lifecycle fields. When the ADR's status changes (e.g., it is superseded), the register entry's Status field is updated to reflect the outcome and the Related docs field is updated to point to the new ADR.
The complementary use case: decisions that require both
Architecture decisions that have significant project impact — a technology choice that affects timeline, budget, team composition, or compliance posture — belong in both systems, with each system playing its role:
- Write the ADR in
doc/decisions/with full Context, Alternatives considered including rejection rationale, and Consequences including downsides. This is the engineering record. - Create a register entry in the PM tool with the accountability fields (Decision maker, RACI, Impact, Risk level, Review date). In the Related docs field, paste the GitHub permalink to the ADR. This is the governance record.
- Cross-reference in the other direction: in the ADR's Context or Notes section, include the register entry ID (e.g., "See DEC-0042 in the decision register for business impact assessment"). Engineers working from the ADR can navigate to the governance record; PMs working from the register can navigate to the rationale record.
This pattern is standard in organisations running TOGAF, where the ADR maps to the Architecture Repository and the register entry maps to the Governance Log — two artifacts in two systems, cross-referenced, each maintaining its own lifecycle. The TOGAF-aligned ADR template described on the TOGAF ADR template page uses a governance_review_id frontmatter field specifically for this cross-reference.
For Architecture Board-reviewed decisions, the pattern extends: the Board's charter specifies that every Board-reviewed decision requires both a PR-merged ADR in doc/decisions/ (the engineering record) and a Governance Log entry (the Board's authoritative record of who reviewed it and when). The architecture board charter template covers this boundary explicitly — every Board-reviewed decision IS an ADR plus an additional governance entry, not a different document format.
Decision register template
The following Markdown template is a lightweight decision register suitable for small to mid-size engineering teams that need governance tracking without a full PM toolchain. It is intentionally simpler than PRINCE2's full register format — three fields are dropped (Risk probability/impact matrix, full RACI table, formal change-control log) to keep the friction low enough that engineers will actually fill it in.
# Decision Register
| ID | Date | Title | Decision maker | Status | Related ADR |
|----|------|-------|----------------|--------|-------------|
| DEC-0001 | 2026-01-15 | Select primary database | VP Engineering | Closed | [ADR-0042](/doc/decisions/0042-postgres.md) |
| DEC-0002 | 2026-02-01 | CI/CD platform | CTO | Closed | [ADR-0051](/doc/decisions/0051-github-actions.md) |
| DEC-0003 | 2026-03-10 | Observability vendor | Platform lead | Open | — |
---
## DEC-0001: Select primary database engine
**Date:** 2026-01-15
**Decision maker:** VP Engineering (accountable)
**Consulted:** CTO, DBA lead, backend leads × 3
**Decision:** Use Postgres as the primary relational database for all services.
**Rationale:** Team has three years of operational Postgres expertise. JSONB covers semi-structured document needs without a separate store. CockroachDB's distributed transaction edge cases conflicted with the existing query patterns in the billing service (see ADR-0042 Context section for detail).
**Alternatives considered:** MySQL 8 (team unfamiliar, no JSONB), CockroachDB (see above), DynamoDB (AWS-only, conflicts with multi-cloud posture).
**Impact:** Platform team 3-week migration window. Infrastructure cost neutral (OSS). No new training required.
**Risk level:** Low.
**Review date:** 2027-01-15 (annual, or when team exceeds 500 req/s on writes).
**Status:** Closed.
**Related ADR:** [ADR-0042 — Use Postgres as primary relational store](/doc/decisions/0042-postgres.md)
For teams using a spreadsheet or JIRA-based register, the same fields map cleanly: DEC-0001 becomes a JIRA issue in a "Decision" issue type, the Related ADR field becomes a link custom field, and Status maps to a workflow state. The key discipline is the same regardless of storage: the ADR URL is a required field, and the register entry's Status is updated whenever the ADR's status changes.
When to use a decision log instead of either
A decision log — a chronological flat list of decisions without lifecycle fields — is appropriate for small teams (three to eight people) where the overhead of both an ADR directory and a decision register is not yet justified. The decision log template on this site offers a CSV and a Markdown version suited for this scale. The log is written as a single shared file, appended as decisions are made, never updated in place.
The signal that you have outgrown a decision log: a decision entry is being revisited and you need to track its status (open, deferred, superseded), or a stakeholder outside engineering needs to find a decision record for audit or onboarding purposes. At that point, split into an ADR directory (for engineering decisions) and a lightweight decision register (for governance), rather than trying to add lifecycle fields to the log format.
How WhyChose fits in
Both ADR directories and decision registers share a common problem: they capture decisions made in formal meetings and documented deliberation, but miss the engineering decisions made informally in AI chat sessions. A ChatGPT conversation about whether to use Redis or Postgres for a job queue, a Claude session evaluating three authentication libraries, a Perplexity research thread on database sharding strategies — these conversations contain the full rationale that belongs in an ADR, but they are rarely transcribed into one.
The WhyChose extractor reads ChatGPT and Claude export JSON and surfaces the decisions embedded in those conversations — with Decision, Context, and Consequences fields pre-populated from the conversation text. The output is a structured decision record that can be reviewed and promoted to either an ADR (if the decision is architectural) or a decision register entry (if it needs governance tracking), or both, depending on the scope.
This is particularly useful for the retrospective backlog: teams adopting ADRs for the first time often discover that 18 months of architecture decisions exist only in AI chat history, not in any register or directory. The extractor closes that gap without requiring engineers to reconstruct the reasoning from memory.
Related questions
Should I use a decision register instead of ADRs?
Not instead — each covers a different scope and audience. An ADR directory is the right tool for engineering decisions: it lives in the code repository, captures immutable rationale, and is written for engineers who will work on the system in the future. A decision register is the right tool for project decisions: it lives in a project management tool (JIRA, Confluence, spreadsheet), tracks cross-functional decisions with RACI and business impact, and is written for project managers, stakeholders, and auditors. Most software teams above 10 people benefit from both, scoped correctly rather than trying to collapse one into the other.
What fields does a decision register typically have?
A decision register typically has: Decision ID (sequential number, often prefixed DEC-), Decision title, Decision date, Decision maker (the RACI 'A' — accountable person), Consulted parties (the RACI 'C'), Decision summary (one to three sentences), Alternatives considered, Rationale (why this option was chosen), Impact (scope: which project areas or teams are affected), Risk level (High / Medium / Low), Status (Open / Deferred / Closed), Review date, and Related documents or links. The key difference from an ADR: the register entry is mutable — it can be updated, the status can change, and the impact assessment can be revised as the project evolves. An ADR is immutable once accepted.
Can I use an ADR as a decision register entry for architecture decisions?
You can reference an ADR from a decision register entry, but an ADR is not a drop-in replacement for a register entry. The ADR captures the engineering rationale in depth — Context, full Alternatives considered, Consequences including downsides — and is immutable. The register entry is the governance record: who was accountable, what the business impact was, what the review date is. For architecture decisions that also require governance (cross-team scope, budget impact, compliance implications), the right pattern is: write the ADR in /doc/decisions/ for the engineering record, and reference the ADR URL from a lighter decision register entry that captures the business dimension. Neither document replaces the other.
What is the difference between a decision log and a decision register?
The terms are often used interchangeably, but there is a meaningful distinction in formal project management practice. A decision log is a simple chronological record: date, decision, decision maker, rationale. It has no lifecycle management — entries are added but not updated. A decision register is a full project management artifact with lifecycle fields: status (Open / Deferred / Closed), risk level, review date, RACI assignments, and a link to related project documents. A decision log is appropriate for small teams keeping a lightweight record; a decision register is appropriate for projects with formal governance requirements or multiple stakeholder groups who need to track decision status over time.
Further reading
- Decision log template — CSV and Markdown downloads — the lightweight precursor to a full decision register; suited for three-to-eight person teams that need a chronological record without the lifecycle overhead of a formal register.
- When to write an ADR — a 4-question decision tree — the boundary question that precedes the ADR-vs-register question: is this decision architectural enough to warrant an ADR at all, or is it better captured in a decision log or register entry?
- ADR adoption guide — rolling out the practice to a skeptical team — the common objection is that "we already have a decision register in JIRA"; this page covers how to position the ADR directory as the engineering-rationale layer that complements rather than replaces existing PM governance artifacts.
- ADR vs RFC — what's the difference and when to use each — the upstream disambiguation: RFC is pre-decision deliberation, ADR is post-decision rationale record; both are distinct from the decision register's governance-tracking role.
- Architecture Board charter template — boards that review both ADRs and register entries need a charter that specifies which decisions go into which artifact; this page covers the Governance Log boundary and how Board-reviewed ADRs get cross-referenced in both systems.
- TOGAF ADR template — mapping to Phase H and the Architecture Repository — the enterprise-level pattern where the ADR maps to the Architecture Repository and the decision register entry maps to the Governance Log; includes the
governance_review_idfrontmatter field for cross-referencing both systems. - ADR storage format comparison — choosing where ADRs live (code repo Markdown, Notion, Confluence) affects how easily the Related docs cross-reference in the decision register can be maintained; this page covers each storage layer's trade-offs.
- Lightweight ADR template — the minimum viable format — for teams transitioning from a decision log to an ADR practice, the lightweight three-field format reduces the barrier to writing the first ADR while providing enough structure to cross-reference from the register.
- The open-source extractor — surfaces the informal architecture decisions from AI chat history that belong in the ADR directory, and the reasoning that the decision register's short rationale fields can reference for depth.