Architecture decision log
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 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
A minimal index (your real one might be generated or live in a README):
| ID | Status | Decision | Area | Date |
|---|---|---|---|---|
| ADR-0001 | Accepted | Use PostgreSQL for primary relational data | Database | 2026-04-24 |
| ADR-0002 | Proposed | Split billing from the core application | Architecture | 2026-04-25 |
| ADR-0003 | Deprecated | Use Redis for long-term event replay | Infrastructure | 2026-05-01 |
How to maintain a decision log
- 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, and an ISO 42010–inspired shape, the markdown generator for a working draft, and worked examples for tone and level of detail.