signcodify
Start free

Architecture Decision Record (ADR)

A free Architecture Decision Record (ADR) template: title, status, context, decision, consequences and alternatives considered, with a numbered example and guidance on when to write one.

Best for
Teams making decisions that are expensive to reverse: databases, frameworks, boundaries between services
Length
One to two pages
Sections
7

An ADR records one decision and why it was made, at the time it was made. Six months later it answers the question every new engineer asks: why is it built like this?

ADRs are short, numbered and never edited after they are accepted. When a decision changes, write a new ADR that supersedes the old one.

Tip. Write the ADR before the decision is final and share it for comments. An ADR written afterwards tends to justify rather than explain.

  1. 01

    Title and number

    A short noun phrase that names the decision, with a sequential number. Numbers make ADRs easy to reference in code reviews and commit messages.

    markdown
    # ADR 0014: Use Postgres logical replication for the analytics pipeline

  2. 02

    Status

    One of Proposed, Accepted, Deprecated or Superseded, plus the date and the people who decided. If it is superseded, link to the new ADR.

    text
    Status: Accepted, 2026-03-11
Deciders: data platform team
Supersedes: ADR 0009

  3. 03

    Context

    The forces at play: the problem, the constraints, what the team knew and did not know. Write it so that someone without the meeting can follow it. Facts, numbers and links, not opinions.

    text
    Nightly batch exports from the orders database take 3h 40m and block
reporting until 9 a.m. Volume grows about 8% a month. The analytics
team needs data that is no more than 15 minutes old. We run Postgres 16
on a managed service that supports logical replication.

  4. 04

    Decision

    The choice, stated in one or two sentences in the active voice, followed by the details that matter for implementation.

    text
    We will stream changes from the orders database to the warehouse with
Postgres logical replication and a Debezium connector, and retire the
nightly export once two weeks of parallel runs match.

  5. 05

    Consequences

    What becomes easier and what becomes harder, honestly. Include new operational work, costs and risks. This is the section future readers trust most.

    • Reporting data is minutes old instead of a day old
    • A new service to run and monitor: the connector
    • Schema changes on orders now need a replication check
    • Batch export code can be deleted

  6. 06

    Alternatives considered

    Each serious option with one or two lines on why it was not chosen. This stops the same debate from restarting every quarter.

    • Faster batch exports: does not meet the 15-minute requirement
    • Dual writes from the application: risk of drift, needs changes in five services
    • A managed CDC product: higher cost, same operational shape

  7. 07

    References

    Links to the design doc, benchmarks, tickets and any discussion threads, so the evidence is one click away.

Mistakes to avoid

  • Editing an accepted ADR when the decision changes, which erases the history it exists to keep.
  • A context section that only makes sense to people who were in the meeting.
  • Listing only the benefits in Consequences.
  • Writing ADRs for small, easily reversed choices, so the important ones get lost.
  • Storing ADRs somewhere engineers never look. Keep them next to the code or linked from it.

Questions about this template

When should we write an ADR?
When a decision is expensive to reverse or affects more than one team: choosing a datastore, a framework, a service boundary, an auth model. Skip it for choices that can be undone in an afternoon.
Where should ADRs live?
Many teams keep them as markdown in a docs/adr folder in the repository. With Signcodify Git sync, that folder publishes as a readable, searchable section of your docs and stays in step with the repo.
Can an ADR be changed after it is accepted?
Fix typos, but do not change the decision. Write a new ADR that supersedes it and update the status of the old one to point to the new one.

Last updated October 30, 2026

Suggest an edit

Use this template in Signcodify

It opens in the block editor with every section above in place. Sync it to your repository or publish it to your docs site.

Use this template