Writing your first ADR

An Architecture Decision Record is a short document that captures a single decision. The power is in the constraint: one decision per ADR, written at the moment of deciding, kept forever.

The template

Every ADR has five sections:

1. Title — one sentence naming the decision
2. Status — proposed, accepted, deprecated, superseded
3. Context — the forces at play
4. Decision — what you chose
5. Consequences — what happens next, good and bad

Example

Title: Adopt Postgres over MongoDB for the new ingestion service.

Status: Accepted, 2026-03-12.

Context: We need durable storage for event ingestion. The team has deep Postgres experience. MongoDB would require new operational knowledge. Data is relational by nature.

Decision: Use Postgres 16 on Neon.

Consequences: Team can ship faster. We lock in on Postgres ergonomics. If scale exceeds single-node Postgres later, we migrate to Citus or add read replicas. Accepted risk.

How Atlas helps

The Decisions module guides you through the five sections. It suggests related applications and capabilities based on the text you write. It flags ADRs that conflict with existing ones so you can link "supersedes" relationships.

When to write an ADR

Write one when: you're about to make a change that's hard to reverse, two senior people disagree, or you suspect you'll forget why you chose this in six months.