# What is an architecture decision record (ADR)?

> An architecture decision record (ADR) is a short note on a decision, why it was made and what follows. Learn the format, when to write one and examples.

An architecture decision record is a short note that captures one decision: what was chosen, why and what follows from it. It saves the next engineer from asking why on earth it was done this way.

Web page: https://kansohq.app/guides/what-is-an-adr

Updated: 5 October 2026

## What an ADR is

An architecture decision record, or ADR, is a short document about a single decision that shapes a system: which database, which queue, how services talk, how errors are handled. It records the decision, the context it was made in and the consequences. It is kept, not edited away, so the history stays honest.

## Why teams write them

- People leave and memory fades. A year later nobody remembers why the system works as it does.
- New engineers can read the reasoning instead of guessing at it.
- A decision that is written down can be revisited properly when the conditions change, instead of by argument.

## The format

Keep it to a page. The sections that earn their place:

1. **Title:** a short, specific name for the decision.
2. **Status:** proposed, accepted or superseded.
3. **Context:** the forces at play, including constraints and deadlines, and what you did not know.
4. **Decision:** what you are doing, stated in the present tense.
5. **Consequences:** what gets easier, what gets harder and what you now have to live with.
6. **Revisit when:** the condition that would make you reopen it.

**An example, in brief**

> **Decision:** We store uploaded images in object storage and keep only their addresses in the database.
> **Context:** Images made up most of the database size and slowed every backup.
> **Consequences:** Backups are faster and cheaper. Reading an image is now a second request, and deleting a page must also delete its files.
> **Revisit when:** image traffic grows enough to need a CDN in front.

## When to write one

Write an ADR when a decision is hard to reverse, affects more than one team or will surprise a future reader. Do not write one for every choice: a record for each variable name buries the ones that matter.

## How to keep them useful

- Number them in order and never delete one. If a decision changes, write a new record and mark the old one superseded.
- Keep them next to the design docs and the code they describe.
- Write them while the decision is fresh, not months later from memory.
- Link them from the [technical design](https://kansohq.app/guides/how-to-write-a-technical-design-doc.md) that led to them.

## The statuses a record can have

| Status | Meaning |
| --- | --- |
| Proposed | Written and open for comment. Not yet in effect. |
| Accepted | Agreed, and the team is acting on it. |
| Superseded | Replaced by a later record, which it links to. |
| Deprecated | No longer followed, and nothing has replaced it. |

## When a decision changes

Decisions change when the world does: the team grows, the cost of a service rises, a better option appears. Do not edit the old record to say something new, because then nobody can tell what the team believed at the time. Write a new record, say what changed, set the old one to superseded and link the two. Anyone reading either can follow the trail.

**A superseded record**

> **Old record, status superseded:** We use one database for everything.
> **New record, status accepted:** We move search to its own index. The single database could not answer search quickly once pages passed a hundred thousand.
> **Link:** the new record points at the old one, and the old one points forward to the new one.

## Alternatives to a formal record

- A **decision log** at the top of the design doc, a table with the date, the decision and the reason, is enough for small teams.
- A **short note in the task** works for decisions that affect only that task.
- A **dated decision in the meeting notes** is better than none, if the notes are easy to find.

The format matters less than the habit: write down what was decided and why, in one place people can find, close to the work.

## Decision records in Kanso

The [decision record template](https://kansohq.app/templates/decision-record.md) has the decision, status, context, consequences and revisit condition ready to fill in. Keep each record as a sub-page of the project it affects, so the reasoning sits beside the work. See [Kanso Docs](https://kansohq.app/product/docs.md).

## Questions

### What does ADR stand for?

ADR stands for architecture decision record: a short document that captures one significant technical decision, the context it was made in and its consequences.

### How long should an ADR be?

About a page. Long enough to explain the context and the consequences, short enough that people actually read it.

### Where should ADRs be stored?

Next to the design docs and the code they describe, in the same project, so the reasoning is easy to find when someone asks why.

### Can an ADR be changed?

Do not rewrite history. If a decision changes, write a new record and mark the old one as superseded, with a link between the two.

## Keep reading

- [How to write a technical design doc](https://kansohq.app/guides/how-to-write-a-technical-design-doc.md): A technical design doc explains how you will build something and why. Learn the sections to include, how to compare options and how to get a useful review.
- [What is a PRD? How to write one, step by step](https://kansohq.app/guides/what-is-a-prd.md): A PRD is a product requirements document. Learn what goes in one, how long it should be, how to write it step by step and the mistakes to avoid.
- [Decision record template (ADR) to copy | Kanso](https://kansohq.app/templates/decision-record.md): An architecture decision record (ADR) template with the decision, status, context, consequences and revisit condition. Copy it, or start it in Kanso.
- [Technical design doc template for engineers | Kanso](https://kansohq.app/templates/technical-design.md): A technical design doc template with context, approach, data model, alternatives, trade-offs, rollout and open questions. Copy it, or start it in Kanso.

## Parts of Kanso used

- [Kanso Docs](https://kansohq.app/product/docs.md): Pages with headings, to-dos, tables and code, kept inside the project they describe, next to its board and its release.

[Kanso home, with plans and prices](https://kansohq.app/index.md)