Architecture decision log
Last reviewed: .
An architecture decision log is a chronological index of important software architecture decisions. A single ADR documents one decision; a decision log helps a team browse, audit, and maintain the full set of decisions as the system evolves.
What is an architecture decision log?
It is a durable list of records—usually markdown files in a repository—each of which should answer “what did we decide, and what were we thinking?” for one choice. The log is the set of those files plus whatever index you use (README, generated index, or portal) so people can find decisions by status, area, or time.
The relationship to ADRs is simple: the log is the collection; an individual ADR document is one entry. Teams often use numbered filenames (0001-…) or a shared prefix so the log sorts predictably in git and in search.
ADR vs architecture decision log
| ADR | Decision log |
|---|---|
| One decision, one file (or one record) | The index and history of many decisions |
| Context, decision, consequences in depth | Discovery, status, and traceability across entries |
What should a decision log include?
Per entry, teams usually track some combination of the following in the index (and often in the ADR body too):
- ADR or record identifier
- Title
- Status (e.g. Proposed, Accepted, Superseded)
- Date of last meaningful update
- Authors or approvers, when that matters for audit
- Affected systems, boundaries, or teams
- Links to related or superseding ADRs
- Tags or categories (data store, security, platform, …)
Example architecture decision log
Save this illustrative index as docs/adr/README.md. Replace the rows with your own decisions and create the linked files in the same folder. Keep the index and records in the same pull request so their status and links stay aligned.
# Architecture decision log
| ID | Decision | Status | Record |
| --- | --- | --- | --- |
| ADR-0001 | Use PostgreSQL for primary relational data | Accepted | [ADR-0001](0001-use-postgresql.md) |
| ADR-0002 | Split billing from the core application | Proposed | [ADR-0002](0002-split-billing.md) |
| ADR-0003 | Use a shared cache for read-heavy endpoints | Superseded by ADR-0004 | [ADR-0003](0003-shared-cache.md) |
| ADR-0004 | Bound cache lifetime and define database fallback | Accepted; supersedes ADR-0003 | [ADR-0004](0004-cache-policy.md) |
How to maintain a decision log
When a decision is superseded
- Write a new ADR describing the changed constraint or evidence and the replacement decision.
- Link the new record to the old one, and change the old status to “Superseded by ADR-…”. Keep its original rationale.
- Update both index rows in the same change. A reader arriving at either record should be able to find the other.
- Check the relative links in the repository viewer and include the updated index in review.
Deprecated means a choice is no longer recommended. Superseded identifies a replacement decision. State which applies instead of silently replacing an accepted record. The ADR lifecycle guide covers these statuses.
- Keep ADRs in git next to the code or in a well-known docs path; treat changes like code review.
- When a decision is revised, update status and add links to the superseding ADR; avoid silent edits to meaning.
- Link ADRs from relevant pull requests so reviewers see the record of intent.
- Keep index rows short; put depth in the ADR file, not in the log table only.
- Prefer consistent naming and fields over one-off “perfect” documentation for each entry.
Start your decision log
Use a format you will actually maintain: templates for Nygard, MADR, Y-Statement, Outcome-First, and ISO 42010 Companion, the markdown generator for a working draft, and worked examples for tone and level of detail.