Architecture Decision Record (ADR) Template

An ADR captures a significant technical decision at the moment it's made: the context, the options considered, the reasoning. Six months or six years later, nobody has to reconstruct why a call was made by digging through git blame.

Number them sequentially and never delete or rewrite an old one. If a decision changes, write a new ADR that supersedes it.

How to use this document

• Write an ADR for decisions that are expensive to reverse or not obvious in hindsight, database choice, API versioning strategy, auth approach, a major library/framework pick. Don't write one for every PR.
• Write it when the decision is made, not months later from memory.
• Keep the status field current: Proposed while under discussion, Accepted once decided, Superseded by ADR-0XX if a later decision replaces it. Never delete, the history of "we tried X, it didn't work, here's why" is valuable.

ADR-[number]: [Short title of the decision]

Context

What situation forced this decision? What constraints (technical, team, timeline, cost) shaped the options?

Write this so someone with zero context on the project understands why the decision was needed at all.

[2-4 sentences describing the problem/forces at play. Avoid describing the solution here, that comes next.]

Decision

State the decision in one clear sentence, then elaborate.

We will [decision].

[Explain what this means concretely, what changes, what stays the same, what the new approach looks like at a high level.]

Options considered

Show your work. This is often the most valuable part of the document for future readers.

It proves the obvious alternative was actually considered and shows why it got rejected.

Option A: [name] (chosen or rejected)

• Pros: [...]
• Cons: [...]

Option B: [name] (chosen or rejected)

• Pros: [...]
• Cons: [...]

Option C: [name] (chosen or rejected)

• Pros: [...]
• Cons: [...]

Consequences

Every decision has tradeoffs. Be honest about what gets harder, not just what gets better.

Positive:

• [e.g. Simpler operational model, one less service to run]

Negative / accepted tradeoffs:

• [e.g. Higher latency on X path, mitigated by caching]
• [e.g. Locks us into vendor Y for at least 2 years given migration cost]

Follow-up work required:

• [e.g. Migrate existing data from old system by [date]]

Revisit triggers

Optional but useful. What would make you reconsider this decision?

It saves the next person from re-litigating it for the wrong reasons and flags the right ones.

• [e.g. If write volume exceeds X/sec, re-evaluate the single-database approach]

Example: filled ADR (abbreviated)

ADR-0007: Use Postgres logical replication instead of a message queue for cross-service data syncStatus: Accepted on 2026-02-10

Context: Two services need near-real-time visibility into each other's data. We considered introducing a message queue (Kafka/SQS) just for this sync, but the team already runs Postgres for both services and has no existing queue infrastructure or on-call expertise for one.

Decision: We will use Postgres logical replication to stream relevant tables from Service A's database directly into a read-only schema in Service B's database.

Options considered:

Message queue (Kafka), rejected: Adds a new piece of infra with its own on-call burden for what's a two-service sync problem. Overkill at current scale.

Polling via API, rejected: Adds latency from the poll interval and puts unnecessary load on Service A's API for what is fundamentally a data-layer concern.

Postgres logical replication, chosen: No new infrastructure, sub-second lag, and the team already has Postgres operational expertise.

Consequences: Negative: this couples the two services' schemas more tightly than a queue would (a column rename in A requires coordinating with B's replication config). We're accepting that given current team size and the two-service scope. Revisit trigger: if a third service needs the same data, move to a proper event stream instead of replicating point-to-point again.

이 템플릿을 팀 워크스페이스로 복제하려면 → rootr.io