5. ADRs: Recording Architecture Decisions

Description

If any technical document is built for someone who doesn't yet trust their English, it's this one. An ADR is short by design, follows a fixed template of five fields, and uses vocabulary so narrow it fits on a card. There are no long paragraphs to hold up, no structure to improvise, no need to sound elegant. You have to fill five boxes with short, honest sentences. A B1-level developer can write a flawless ADR on the first try, because what gets evaluated isn't fluency but judgment: why this decision got made and what it costs.

In this lesson you're going to see what an Architecture Decision Record is, why it's written short, and why — once accepted — it doesn't get touched. You're going to learn the standard template (title, status, context, decision, consequences) and, more important for this guide, the precise English that goes in each field: the right verb tense, the formula that opens a context, the We will that makes a decision sound committed, and the four states marking a decision's life cycle — proposed, accepted, deprecated, and superseded by. You're going to practice the hardest part of all, which isn't grammar: writing the negative consequences without softening them. And you're going to close by writing a real ADR about a decision you've already made on a project of your own.

Connection to the module: In the previous lesson you learned to explain an architecture in writing — narrating a flow between components, presenting a rejected alternative fairly, writing for two audiences at once. That's the long muscle. The ADR is its brief counterpart: instead of explaining how the whole system works, it freezes one decision and its cost. The two complement each other. In a complete design doc you explain the architecture; when that discussion lands on a concrete choice with consequences, that choice deserves its own ADR so that in two years someone knows why. In the next lesson you'll move from the decision document to the project's entry document — the README — which is the first thing an outside reader opens. Here we're still writing for the team and for the future; there we'll start writing for whoever's arriving from outside.

What an ADR is (and isn't)

An Architecture Decision Record is a short document that records a single architecture decision: what got decided, in what context, and what consequences it brings. Nothing more. Its name says it all: architecture (a decision that affects the system's shape, not a line of code), decision (a choice among real alternatives), and record (a log, something written down and dated).

The analogy that captures it best is a logbook entry or an accounting entry. When an accountant records a transaction, they don't erase the previous one or rewrite it: they add a new, dated line that leaves a record. A ship's logbook works the same way: every entry stays, even if the course changes later. An ADR is exactly that for technical decisions. It's not living documentation that gets updated every week — that's what the next lesson's README is for. It's a historical record: the snapshot of why the team chose A over B at the moment it chose it, with the information it had then.

And this answers the most common question right away: why write the decision down if we already made it and it's already in the code? Because code tells you what got done, never why. Six months later, someone — maybe you yourself — is going to look at that message queue, that cache, that chosen database, and think "this is wrong, we should change it." Without the ADR, they have no way of knowing whether it was a thought-out decision with reasons that still hold, or an accident nobody reviewed. With the ADR, they read the context and alternatives in two minutes and decide with information instead of guessing. The ADR exists for your future self and for whoever arrives once you're no longer on the project.

What an ADR is not:

• It's not a tutorial or a how-to guide. It doesn't explain how to use the technology you chose. It explains why you chose it.
• It's not a design doc. The design doc describes a whole system or feature; the ADR isolates one specific decision within it.
• It's not a living document. It doesn't get edited after acceptance (we'll see why).
• It's not long. A one-page ADR is normal. A three-page one is probably mixing several decisions that should be separate.

Why short, and why immutable

These two properties are what make the ADR such a friendly format, and both have a reason behind them.

Short, because a well-thought-out decision explains itself in a few sentences. The template forces economy: there's no room to ramble. If you can't state the context in one paragraph and the decision in two sentences, you probably don't fully understand the problem yet — or you're stuffing two decisions into one document. Brevity isn't a space limit, it's a clarity test. For you, writing in a second language, it's a huge advantage: less text means less surface for errors. Five correct sentences are easier to pull off than five paragraphs.

Immutable, because a record that gets rewritten stops being a record. Here's the point that's hardest to accept at first: once an ADR is in accepted status, you don't edit it to change the decision. If the team decides the opposite tomorrow, you don't go back and modify the old ADR. You write a new ADR that documents the new decision, and mark the old one as superseded by the new one. The old one stays exactly as it was, forever.

Why so rigid? Go back to the accounting entry analogy, or think of it in terms you already know: an accepted ADR is like a commit in git's history. You don't rewrite old commits to fix the present; you make a new commit on top. The full history — mistakes included — is exactly what carries value. If you edited old ADRs to make them "always have said the right thing," you'd lose the one thing an ADR provides: the honest trail of how the team's thinking evolved. The person arriving two years from now doesn't want a clean, touched-up truth; they want to know what got tried, what got ruled out, and what changed, so they don't repeat an experiment that already failed.

The only edit allowed on an accepted ADR is changing its status (for example, from accepted to deprecated or to superseded by ADR-0012). The body — context, decision, consequences — stays intact.

What to expect: the first time you want to "fix" an old ADR you're going to feel like you're leaving a mistake in plain sight. That cleanup instinct is natural, and here it's wrong. Writing the new ADR that replaces the old one isn't more work than editing the old one, and it leaves something the team appreciates: the full chain of why A, then why B instead of A.

The template: five fields and each one's English

The classic template — Michael Nygard's, the most widely used — has five fields. No mystery. What matters for this guide is the concrete English that goes in each one, because every field has its own verb tense and register. Here's the map:

Let's go field by field.

Title — the headline

The title is a noun phrase (not a sentence with a conjugated verb) naming the decision, usually with a sequence number. It's the headline someone reads in an index to know whether this ADR concerns them.

ADR-0007: Store session state in Redis instead of in-process memory
ADR-0012: Adopt JWT for stateless authentication
ADR-0003: Use PostgreSQL as the primary datastore

Notice the pattern in English: an infinitive verb with no to at the start (Store, Adopt, Use), then the object, and when it helps, the contrast with instead of. Short, concrete, searchable. Avoid vague titles like Database decision or Auth stuff: they tell whoever's searching months later nothing.

Status — the status, with its exact vocabulary

Status is a single word marking where the decision sits in its life cycle. There are four, and their English is fixed — don't translate them or invent your own, they're technical terms everyone recognizes:

The difference between deprecated and superseded by is subtle and worth having clear, because it's exactly the kind of nuance you get asked about in an architecture interview:

• Deprecated: the decision no longer holds, but there's no new decision taking its place. Example: you decided to support Internet Explorer 11 and today it simply doesn't matter anymore; nobody decided "we support X instead."
• Superseded by ADR-0015: a new, concrete decision exists that replaces this one. You point to the number so the reader follows the chain. Example: ADR-0007 said "sessions in Redis" and ADR-0015 said "instead, stateless JWT tokens." ADR-0007 doesn't get deleted; it gets marked Superseded by ADR-0015.

In English you write it literally like this in the field:

Status: Superseded by ADR-0015

And in the new ADR, as a courtesy to the reader, you close the loop with a line pointing back:

This decision supersedes ADR-0007 (session state in Redis).

The verb here is supersede (to replace, to override). ADR-0015 supersedes ADR-0007 = 0015 overrides 0007. It's one of those words you'll almost only see in this context; worth memorizing.

Context — present simple, facts and forces

The context describes the situation forcing a decision: the constraints, the needs, the competing forces. It's the part your future self is going to appreciate the most, because it's where you understand what you knew at that moment.

Key English rule: the context goes in present simple, because it describes facts and forces that are true now. You're not narrating a story in the past; you're laying out a state of affairs. And it's descriptive, neutral, not taking a side yet:

Context:
Our web app keeps session state in each server's memory. We are
about to run multiple instances behind a load balancer. With
in-memory sessions, a user's requests must always hit the same
instance, which forces sticky sessions and breaks when an instance
restarts. We need a session store that all instances can share and
that survives a restart. Expected load is under 5,000 concurrent
sessions. The team already runs Redis for caching.

Notice the vocabulary of forces: we need, forces, breaks when, must always. These are the pressures justifying a decision. Also notice the context still doesn't say the solution: it describes the problem and the constraints (expected load, already using Redis) so that the decision, when it arrives, reads like a logical consequence and not a whim.

Decision — We will, period

Here's the most important sentence in the whole format, and it's one of the easiest to get right in English. The decision gets written in active voice, with the team as the subject, in committed future: We will...

Decision:
We will store session state in Redis, shared across all app
instances. Sessions will expire after 30 minutes of inactivity.
We will use the Redis instance we already operate for caching,
in a separate logical database.

We will store..., We will use.... Not We think we should maybe store..., not It was decided that sessions would be stored.... Remember lesson 3's rule on active voice and explicit subject: this is where it pays off the most. The ADR records a commitment; the English has to sound committed. We will is exactly that register: firm without being arrogant. A decision written in vague passive (it was decided) hides who decides and sounds like nobody's taking responsibility.

Compare the register:

If the decision is still under debate, don't force the We will: that ADR is still in Proposed status, and there it's legitimate to write We propose to... The firm We will is for once the status moves to Accepted.

Consequences: the field that sets a professional apart

The first three fields almost fill themselves in. The fourth, consequences, is where judgment shows — and where most people falter, not from the English, but from the temptation to look good.

Consequences are what changes in the world because this decision got made: the good and the bad. And the golden rule, the one that makes the whole ADR credible, is this: negative consequences get written with the same frankness as the positive ones. An ADR that only lists benefits isn't a record, it's a sales brochure, and nobody trusts it.

This is counterintuitive and needs to be said plainly: writing your own decision's cost doesn't make you look weak; it makes you look senior. Whoever genuinely understands a technology knows exactly what they're sacrificing by choosing it. Hiding the cost doesn't make it go away — it just guarantees it blows up later, once nobody remembers it was a known risk. Whoever runs into that limitation a year from now is going to deeply appreciate finding it written down, instead of discovering nobody thought to mention it.

The most common English (and attitude) mistake here is softening. Spanish sometimes wraps a problem in cotton, and translated literally it ends up in an English full of might, slightly, a bit, could potentially that takes the edge off the warning. Compare:

Notice the pattern in the correct column: it names the concrete cost, quantifies when it can (~1ms, under 5,000), and uses direct present/future (adds, must, now need) instead of stacked conditionals. You're not being negative; you're being exact. A good consequences block mixes both sides without hiding either:

Consequences:
Positive:
- All app instances share session state. We can scale horizontally
  without sticky sessions.
- Sessions survive an app restart. Users stay logged in during deploys.
- We reuse infrastructure the team already runs.

Negative:
- Redis becomes a hard dependency. If Redis is down, no one can log in.
  We must treat it as a critical service, not a best-effort cache.
- Every authenticated request makes a network call to Redis, adding
  ~1ms of latency per request.
- Developers must run Redis locally to start the app. We will document
  this in the README and provide a docker-compose file.

Neutral:
- Session data is now visible in Redis. We must not store secrets in it.

That last point, under Neutral, shows something useful: not everything is good or bad, sometimes it's just a consequence the reader needs to know about. And notice that the negative consequence often generates future work — documenting in the README, providing a docker-compose file; naming it here is what turns the ADR into something actionable instead of a complaint.

What to expect: the first time you write your own decision's negative consequences, you're going to feel like you're handing ammunition to anyone who wants to criticize it. It's the opposite. An ADR that acknowledges its costs upfront disarms criticism: there's no more "you didn't think about X," because X is written down, quantified, and has a plan. Early honesty is the best defense there is.

A complete ADR, start to finish

Here's everything together — the Redis decision we've been building — as it would look in a real file inside the repository, usually in a docs/adr/ folder with names like 0007-session-state-in-redis.md:

# ADR-0007: Store session state in Redis instead of in-process memory

Status: Accepted
Date: 2026-03-14
Deciders: Backend team

## Context
Our web app keeps session state in each server's memory. We are
about to run multiple instances behind a load balancer. With
in-memory sessions, a user's requests must always hit the same
instance, which forces sticky sessions and breaks when an instance
restarts. We need a session store that all instances can share and
that survives a restart. Expected load is under 5,000 concurrent
sessions. The team already runs Redis for caching.

## Decision
We will store session state in Redis, shared across all app
instances. Sessions will expire after 30 minutes of inactivity.
We will reuse the Redis instance we already operate, in a separate
logical database.

## Consequences
Positive:
- All instances share session state. We can scale horizontally
  without sticky sessions.
- Sessions survive an app restart. Users stay logged in during deploys.
- We reuse existing infrastructure.

Negative:
- Redis becomes a hard dependency for login. If Redis is down,
  no one can log in. We must treat it as a critical service.
- Every authenticated request adds a ~1ms Redis call.
- Developers must run Redis locally. We will add a docker-compose file.

Neutral:
- Session data lives in Redis. We must not store secrets there.

Read it all the way through and notice what it does not have: no unnecessary jargon, no thirty-word sentences, no advanced vocabulary. It has present simple in the context, We will in the decision, and honest consequences with numbers. It's a document a B1 developer writes well, and a senior engineer approves with no changes. That's the whole lesson's point: here you compete on judgment, not on accent.

Common mistakes (and their fix)

Exercises

Exercise 1 — Pick the right status

Read each scenario and write the Status: line that fits. Remember the difference between Deprecated (nothing replaces it) and Superseded by ADR-NNNN (a new, concrete decision replaces it).

1. The team decided in 2023 to support Internet Explorer 11. Today nobody uses it and nobody made an explicit decision to replace that support; it simply stopped making sense.
2. ADR-0007 said "store sessions in Redis." The team just approved ADR-0015, which says "instead, use stateless JWT tokens."
3. ADR-0003 decided to use PostgreSQL as the primary database. The team still uses PostgreSQL with no changes or plans to replace it.

Exercise 2 — Strip the cotton off the consequence

These three sentences are softened just like the ones in the lesson's table. Rewrite them in direct English: name the cost, quantify if you can, use present/future with no stacked conditionals.

1. This could potentially make onboarding a bit slower for new developers.
2. There might be some additional cost involved in running this.
3. It may be somewhat harder to debug issues in production.

Exercise 3 — Write the Decision field

Read the context and write the Decision sentence in English, in active voice with We will.

Context: Our mobile app currently bundles all images at build time, which makes the app 340MB. App store reviews mention the download size as a reason for uninstalling. We need to reduce the app size without rewriting the image-loading code.

Exercise 4 — Your first ADR about a decision you already made

Don't invent a hypothetical decision. That's the mistake that kills the practice. Pick an architecture decision you've already made on a real project — yours, from work, from a course, from a side project. It doesn't have to be big. It works perfectly: why you used SQLite instead of PostgreSQL, why you chose Tailwind instead of hand-written CSS, why you kept config in environment variables instead of a file, why you split the frontend from the backend. Any fork where there were at least two paths and you picked one.

Now write it as an ADR, in English, following these steps:

1. Title. A noun phrase with the choice and, if it applies, the instead of. Example: ADR-0001: Use SQLite instead of PostgreSQL for local development.
2. Status. Since you already made it and it's still active, it's Accepted.
3. Context. In present simple, describe what was pushing you to decide. How many users did you expect? What constraints did you have — time, budget, team, infrastructure? This is where you'll practice we need / it must / the constraint is the most.
4. Decision. One or two sentences with We will (or I will, if it's a solo project).
5. Consequences. Here's the real work. Write at least one benefit and at least one real cost. Force yourself to name the cost with the same clarity as the benefit. If you can't think of any cost, you haven't fully thought through the decision: every architecture choice sacrifices something.

How to tell it turned out well: hand it to someone who doesn't know your project — a community peer, even an AI model — to read. If from just that text they understand what problem you were solving, what you decided, and what it cost you, the ADR works. If they have to ask you "but why didn't you use the other one?", your context or your consequences still have a gap.

# ADR-0001: Use SQLite instead of PostgreSQL for local development

Status: Accepted

## Context
This is a side project with a single developer and no deployment
yet. We need a database to prototype the data model quickly. We
don't have a server to host PostgreSQL, and installing it locally
adds setup steps for every new contributor. Expected data volume
during development is under 10,000 rows.

## Decision
We will use SQLite for local development and testing. We will
revisit this decision before deploying to production with real
users.

## Consequences
Positive:
- Zero setup: SQLite ships with Python, no server to install or run.
- The whole database is a single file, easy to reset or share.

Negative:
- SQLite does not enforce some constraints PostgreSQL does (e.g.,
  strict typing), so bugs that only show up under PostgreSQL's
  rules may go unnoticed until deployment.
- We must rewrite and test all queries against PostgreSQL before
  going to production; some SQL syntax differs between the two.

What to expect: the exercise feels surprisingly fast — fifteen, twenty minutes — and that's exactly the lesson. Documenting a decision isn't a heavy end-of-project task; it's a cheap habit that leaves you an incredibly valuable trail. After writing three or four, the template becomes automatic and you start thinking in context / decision / consequences even before sitting down to write. That, on top of everything else, is exactly the mental structure you'll be asked for in a design interview.

Checklist before closing out an ADR

• One decision. Does the ADR cover a single decision, not two disguised as one?
• Searchable title. Does the title name the concrete choice, not a vague topic?
• Correct status. Is the status word one of the four (proposed, accepted, deprecated, superseded by)?
• Context in present. Does it describe the current forces without giving away the solution?
• Decided decision. Is it in We will, active voice, with no timid conditionals?
• Honest consequences. Is there at least one real, quantified, unsoftened cost?
• Immutability respected. If this replaces an old decision, did you write a new ADR and mark the old one superseded by, instead of editing it?

Summary and next step

Before moving on, you should be able to:

• Explain in one sentence what an ADR is and why it's written short and immutable.
• Fill in the template's five fields (title, status, context, decision, consequences) with each one's correct verb tense.
• Use the four statuses (proposed, accepted, deprecated, superseded by ADR-NNNN) without confusing deprecated with superseded by.
• Write a decision in active voice with We will..., with no vague passive or timid conditionals.
• Name at least one real, quantified cost in the consequences, with no softening from might, could potentially, or a bit.

Go back to the idea we opened with. If English gives you impostor syndrome, the ADR is the best place to start producing evidence that you can write serious technical documentation in English. It doesn't ask for fluency. It asks for five fields, present simple for the context, We will for the decision, and courage — more than grammar — to name what you chose's cost. All of that is within your reach today, with the English you already have.

And there's a benefit that goes beyond language: a repository with a well-kept docs/adr/ folder is one of the most credible seniority signals you can show without anyone's permission. It tells whoever reviews your portfolio that you don't just write code, you think about decisions, costs, and the team that comes after. It's judgment made text.

In the next lesson we switch audiences. You write the ADR for the team and for the future; you write the README for the stranger opening your repository for the first time and deciding, in thirty seconds, whether your project deserves their attention. Same plain-language principle, completely different reader.

Resources

• Documenting Architecture Decisions — Michael Nygard's original 2011 article defining the five-field template this lesson uses.
• adr.github.io — the ADR organization's hub on GitHub: shared vocabulary, templates, and tools for managing architecture decisions.
• architecture-decision-record (Joel Parker Henderson) — a repository with multiple ADR templates (Nygard, MADR, and others) and real examples of documented decisions.
• Architectural decision record process — AWS Prescriptive Guidance — how AWS describes an ADR's full life cycle, from Proposed to Superseded.
• Maintain an architecture decision record (ADR) — Microsoft Azure Well-Architected Framework — Microsoft's guide on why an ADR is an append-only record and what elements each entry should have.